---
description: "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation."
alwaysApply: false
---

# 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

```bash
# 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

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

- [ ] All tests pass (zero regressions)

### 3. Type check

```bash
<typecheck command>
```

- [ ] No type errors introduced

### 4. Lint

```bash
<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](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:

```markdown
## 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:

```bash
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+).