---
name: validate-fix
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."
---


# Validate Fix
> **HARD GATE** — **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success. A fix that passes tests but breaks something else is a failure.


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

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

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