# Diagnosis Before Fix Rule

Enforce systematic root cause diagnosis before applying fixes to persistent failures, preventing shotgun debugging (random changes without understanding the root cause).

---

## When Diagnosis Is Required

Invoke the spec-driven-rca skill before attempting further fixes when ANY of these hold:

1. **3+ consecutive fix attempts** fail on the same error or test
2. **Integration tests fail** with non-environment errors
3. **QA finds CRITICAL/HIGH violations** not caught during TDD
4. **Pre-commit hook blocks** after 2+ formatting/validation retries
5. **3+ consecutive audit-gate HALTs on the same phase** (Plan D2 D10 / ADR-059) — Layer 9 audit-gate failures count as fix attempts. Each HALT (audit verdict reject OR fixture-gen failure) increments the audit-attempt counter for the `(story_id, phase)` tuple; on the 3rd, invoke spec-driven-rca before any further fix attempt and before bypassing audit via `DEVFORGEAI_AUDIT_BYPASS`.

    *Enforcement:* deterministic via `.claude/hooks/post-audit-attempt-counter.sh` (PostToolUse[Bash], `exit 2` on the 3rd consecutive `audit-gate` non-zero exit). Counter at `tmp/${STORY_ID}/audit-attempts-${PHASE}.count`. Reset by deleting the counter file after running `/rca`. See ADR-098 and `docs/gates/plans/c11-audit-attempt-escalation-hook.md` for the full design.

This rule cannot be skipped, deferred, or overridden without explicit user approval via AskUserQuestion.

---

## Skill Reference

Invoke `.claude/skills/spec-driven-rca/SKILL.md`. Its 4-phase methodology: **CAPTURE** (collect failure artifacts) → **INVESTIGATE** (cross-reference context files via diagnostic-analyst subagent) → **HYPOTHESIZE** (ranked hypotheses with confidence scores) → **PRESCRIBE** (targeted fixes with specific file paths).

---

## 3-Attempt Escalation Protocol

| Attempt | Action |
|---------|--------|
| 1 | Normal iterative fix. Apply fix, run tests. |
| 2 | Normal iterative fix. Apply fix, run tests. |
| 3 | **HALT.** Invoke spec-driven-rca skill. Apply prescribed fix. |
| 4 | If diagnosis prescription fails, try next hypothesis. |
| 5 | **HALT.** Escalate to user via AskUserQuestion (options: provide more context / skip the AC with justification / pause and investigate manually). |

---

## Scope

**Applies to:** TDD Green (Phase 03) test failures, TDD Refactor (Phase 04) regressions, Integration (Phase 05) cross-component failures, QA deep analysis (Phase 2) constraint violations.

**Does not apply to:** TDD Red (Phase 02 — tests are expected to fail), environment setup failures (Docker, database, network), user-requested manual fixes, single-attempt failures.

---

## References

- **Skill:** `.claude/skills/spec-driven-rca/SKILL.md`
- **Subagent:** `.claude/agents/diagnostic-analyst.md`
- **Investigation Patterns:** `.claude/skills/spec-driven-rca/references/investigation-patterns.md`
- **Workflow Integration:** `.claude/skills/spec-driven-rca/references/workflow-integration.md`
