validate-fix

Validate Fix

HARD GATE — Fix must not regress. Run full test suite and manual UAT before declaring success.

Prove the fix works. “I think it works” is not evidence. Run the suite, show the output, then harden against recurrence.

Two-commit red/green policy (e45s08) — Bug fixes follow the same two-commit discipline as develop-tdd: first commit adds/adjusts the failing test (test(<scope>): …), second commit applies the fix (fix(<scope>): …). Do not squash RED and GREEN before review.

Checklist

1. Re-run the originally failing test

# Run the specific test that captured the bug
<test command for the failing test>

Previously failing test now passes

2. Run the full test suite

# Run all tests — no filtering
<full test command from CLAUDE.md>

All tests pass (zero regressions)

3. Type check

<typecheck command>

No type errors introduced

4. Lint

<lint command>

No lint violations introduced

5. Harden against recurrence

For every bug fixed, add at least one prevention layer:

Mechanism	When to use
Type guard	Input could be the wrong shape
Schema validation (Zod, Pydantic, etc.)	External data crossing a boundary
Invariant assertion	Internal state that must always hold
Lint rule	Pattern that’s easy to repeat by mistake
Environment check at startup	Missing config causes silent failure

At least one hardening mechanism added
Hardening mechanism is tested

5b. Generalize-fix (HARD GATE — e80s04 / GH #98)

Sweep the defect class across the codebase after local hardening — see REFERENCE-generalize-fix.md.

Defect class documented (not just the one-line root cause)
Grep sweep run and match_count recorded
verify-generalize-sweep.sh passes on the artifact

6. Update the bug file and registry.yaml

Find the most recent specs/bugs/BUG-*.md file and append the resolution:

## Resolution

**Fixed:** [date]
**Root cause confirmed:** [one sentence]
**Fix applied:** [what was changed]
**Hardening added:** [type guard / schema / assertion / lint rule]
**Evidence:** all tests pass (`<verify command>`)
**Commit:** `fix(<scope>): <description>`

Also update the corresponding row in specs/bugs/registry.yaml: set status to fixed, fill in files_changed, approach, risk_level, commit_message, and any other resolution fields.

specs/bugs/BUG-*.md updated with resolution
specs/bugs/registry.yaml row updated with resolution fields

7. Behavioral Proof (HARD GATE)

Mechanical verification (tests passing) is only half the fix. You must prove behavioral correctness.

Manually demonstrate the fixed behavior (e.g., via run_shell_command or web_fetch)
Compare the output/state against the “Expected Behavior” in the bug file
Show the user evidence of the behavior, not just the test logs

Rules

Loop until behavioral correctness is verified: if any checklist item fails, or if the behavior is still incorrect despite passing tests, return to step 1 and run all checks again from the top — do not declare done until every item is green and the behavior is proven correct in a single run.
Never use @ts-ignore, as any, or // eslint-disable to “fix” a bug — these suppress the symptom without fixing the root cause
Never mark the task done if any test is still failing
The verify command from specs/bugs/BUG-*.md or the active epic task verify field must pass

Suggest next skill: audit-code → commit-message.

Verify

→ verify: grep -q 'generalize-fix' skills/validate-fix/SKILL.md && test -x scripts/verify-generalize-sweep.sh && bash scripts/verify-generalize-sweep.sh --self-test && echo OK