Step 3 · Fix and Verify

Goal

Apply a minimal, targeted fix at the root cause, verify all tests pass, and commit with a clear record of what was wrong and why the fix is correct.

Instructions

You are in workflow step 3 of the bug-cycle. The root cause is known. Now fix it and prove it's fixed.

Tasks to Perform

1. Review the Root Cause One More Time

Before writing the fix, state:

  • What is wrong (exact file:line)
  • What the correct behaviour should be
  • What the minimal change is to achieve it

If the fix requires changing more than ~20 lines, you may not have found the actual root cause. Re-examine.

2. Apply the Fix

Rules for the fix:

  • Minimal — change only what needs to change to fix this bug
  • Don't refactor — do not improve surrounding code during a bug fix (separate commit)
  • Don't add features — do not extend functionality during a bug fix
  • Fix the cause, not the symptom — not "ignore the error" but "prevent the error"
# After making the fix:
# Remove any debug output that was added during diagnosis
grep -rn "var_dump\|console\.log\|dd(\|print_r\|debugger" src/ | grep -v test

3. Run the Regression Test

The failing test from Step 1 should now pass:

[test runner] [path/to/regression-test]
# Expected: PASS

4. Run the Full Test Suite

[full test runner command]
# Expected: all tests pass — including all pre-existing tests

If any pre-existing test fails after your fix: you have introduced a regression. Re-examine your fix.

5. Verify Related Code Paths

If Step 2 revealed other code paths with the same pattern:

  • Apply the same fix to each one
  • Write tests for each

6. Commit the Fix

Use the bug-fix commit template:

git add [only the files changed for the fix]
git commit -m "fix: [what was broken] — [root cause in one sentence]

[Optional body: fuller explanation of the chain of events]

Regression test: [path/to/test]
$(if relevant) Also fixes: [related paths that had the same issue]"

Example:

fix: password reset link invalid for users with + in email

Root cause: urlencode() was used instead of rawurlencode() when building
the reset URL, causing + to be decoded as a space by the server when
the user clicked the link, invalidating the token match.

Regression test: tests/Auth/PasswordResetTest.php::test_reset_link_valid_with_plus_in_email

7. File a Post-Mortem (High/Critical bugs only)

If this bug caused user-facing data loss, downtime, or incorrect billing, create a post-mortem:

# Create the post-mortem document
cat > docs/bugs/$(date +%Y-%m-%d)-[slug].md << 'EOF'
# Post-Mortem: [Bug Title]
**Date:** YYYY-MM-DD
**Severity:** High
**Duration:**
**Users affected:**

## Timeline
##  Root Cause
## Resolution
## Prevention
EOF

8. Update TODO.md

Mark the task done with the completion date. Status rules: [ ] = not started · [~] = in progress (one at a time) · [x] = done (prefix the date).

## Done
- [x] YYYY-MM-DD  fix: [one-line description] — root cause: [one sentence] _(ref: workflows/bug-cycle/03-fix-and-verify.md)_

Expected Output

  • Fix applied at root cause (not symptom)
  • Regression test passes
  • Full test suite passes
  • Clean commit with descriptive message
  • Post-mortem filed if required

Exit Criteria

This step is complete when:

  • [ ] Regression test passes
  • [ ] Full test suite passes
  • [ ] No debug output remains in code
  • [ ] Fix is committed with a descriptive message
  • [ ] TODO.md shows the task as done
  • [ ] Post-mortem filed (if High/Critical)