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

---

Generalize-fix (e80s04 / GH #98)

After local hardening in validate-fix, sweep the defect class across the codebase.

Steps

1. Classify — name the pattern (e.g. unscoped org query, fail-open verify, hardcoded package manager).
2. Sweep — grep for sibling instances; record match_count and grep_pattern.
3. Resolve — patch all matches in this PR or file one tracking issue listing every remaining instance.
4. Artifact — write sweep evidence before declaring done:

cat > specs/verifications/generalize-sweep-BUG-YYYY-MM-DD-slug.json <<EOF
{
  "defect_class": "fail-open-verify",
  "grep_pattern": "\\\\|\\\\| echo",
  "match_count": 0,
  "sweep_scope": "skills/*/SKILL.md",
  "patched_in_pr": [],
  "tracked_issues": []
}
EOF
bash scripts/verify-generalize-sweep.sh specs/verifications/generalize-sweep-*.json

Security classes

When the defect class is security- or gate-relevant:

• Add a row to security-review CWE fixture table (see skills/security-review/SKILL.md § CWE mapping mandate).
• If security-impact was MEDIUM+: add regression test, false-positive exclusion rule, and threat-model update (HIGH+).