4.7 KiB

Raw Blame History

Workflow Pattern Example: Systematic Debugging

Demonstrates identifying, specifying, and implementing a workflow pattern.

Pattern Identification

User: "I have a bug where users can't log in after password reset."

Agent flow:

Asked for error message and reproduction steps
Created minimal reproduction case, confirmed bug
Added logging, inspected state, reviewed recent changes
Identified root cause: password hash using wrong algorithm
Implemented fix, added regression test
Bug resolved

Pattern: Systematic debugging - structured investigation, not trial-and-error.

Type: Workflow (multi-step sequence with clear stages)

Why not orchestration: Doesn't primarily coordinate external tools Why not heuristic: Not a decision rule, but a procedural process

Pattern Specification

name: systematic-debugging
type: workflow
description: Structured root cause investigation

stages:
  - name: Reproduction
    goal: Create reliable, minimal reproduction
    actions:
      - Gather error messages, logs, stack traces
      - Document exact steps to trigger
      - Reduce to minimal reproduction case
      - Verify reproducibility
    exit_criteria: Can trigger bug on demand

  - name: Investigation
    goal: Form hypothesis about root cause
    actions:
      - Add logging at suspected points
      - Use debugger to inspect state
      - Review recent changes (git log, blame)
      - Check related issues/PRs
    exit_criteria: Specific, testable hypothesis

  - name: Validation
    goal: Confirm fix works without regressions
    actions:
      - Implement minimal fix
      - Test against reproduction case
      - Run full test suite
    exit_criteria: Fix resolves bug, no new failures

  - name: Prevention
    goal: Prevent future recurrence
    actions:
      - Add regression test
      - Document root cause in commit
    exit_criteria: Test would fail if bug reoccurs

quality_criteria:
  - Each stage has clear outputs
  - Don't skip reproduction for "fixes"
  - Don't accept fixes without root cause
  - Always add regression test

anti_patterns:
  - Random trial-and-error
  - Fixing symptoms instead of root cause
  - No regression tests
  - Incomplete reproduction

Component Recommendation

Invocation: User-triggered (bug report, debugging request) Automation: Cannot be fully automated (requires judgment) Domain Expertise: General software engineering

Decision: SKILL

SKILL because:

User invokes when encountering bugs
Requires judgment (hypothesis formation, fix validation)
Not specialized domain (any engineer should debug)
Benefits from progressive disclosure

Not COMMAND: Can't be scripted, requires contextual decisions Not AGENT: General engineering, not specialized domain Not HOOK: User-invoked, not event-triggered

COMMAND: /reproduce-bug — automate running reproduction steps COMMAND: /run-regression-tests — run tests related to bug area HOOK: post-fix — warn if no regression test added

Implementation Sketch

File Structure

skills/
  systematic-debugging/
    SKILL.md
    examples/
      auth-bug.md
      race-condition.md
    references/
      debugging-tools.md
      common-patterns.md

Key Sections

Quick Start:

Reproduce: Create minimal, reliable reproduction
Investigate: Form hypothesis using logging/debugging
Validate: Implement fix, verify no regressions
Prevent: Add regression test, document learnings

Hypothesis Documentation:

Hypothesis: Password reset uses bcrypt, login uses SHA-256,
causing hashes to never match.

Evidence:
- resetPassword() calls bcrypt.hash()
- login() calls crypto.createHash('sha256')
- Logged hashes have different formats

Test: Change login to use bcrypt.compare()

Regression Test:

it('allows login with new password after reset', async () => {
  const user = await createTestUser('test@example.com');
  await resetPassword(user.email);
  const newPassword = getLatestResetToken(user.email);

  const result = await login(user.email, newPassword);
  expect(result.success).toBe(true);
});

Anti-Patterns

Random trial and error:

✗ "Let me try changing this and see"
✓ "Based on logs, I hypothesize X. Let me test that."

Fixing symptoms:

✗ "Skip password verification for reset users"
✓ "Fix root cause: inconsistent hashing algorithms"

No regression test:

✗ Fix, commit, move on
✓ Add test that fails if bug reoccurs

Success Metrics

Metric	Before	After
Time to resolution	Varies (30min–5hr)	Consistent (1–2hr)
Regression rate	~15%	<5%
First-fix success	~40%	~75%

4.7 KiB Raw Blame History Unescape Escape