defect-hunter

name	defect-hunter
description	Formal defect lifecycle — triage, isolation, fix, verification, and closure report. Use when a defect has been reported via QA, production incident, or bug ticket. Triggers on "defect", "bug report", "production issue", "ticket", "incident", or any request referencing a specific defect ID, customer report, or QA-found issue. Distinct from systematic-debug which covers ad-hoc investigation.

Defect Hunter Skill

Lifecycle Overview

Report → Triage → Isolate → Fix → Verify → Close

Every phase produces output. The closure report is the deliverable. Defects that close without a closure report close again as new defects.

Phase 1 — Triage & Classification

Classify before touching code.

Severity:

• P0 / Critical: Data corruption, incorrect payments issued, security breach, total outage → Escalate immediately. Do not start isolation without human acknowledgment.
• P1 / High: Core functionality broken for majority of users, no workaround available
• P2 / Medium: Feature broken, workaround available, not blocking users
• P3 / Low: Minor UX issue, cosmetic defect, non-blocking edge case

Payroll P0 rule (non-negotiable): Any defect affecting calculated amounts, tax withholding, deductions, garnishments, or direct deposit routing is automatically P0 regardless of how many employees are affected. One incorrect paycheck is a compliance event.

Defect type:

• Logic error (wrong calculation, wrong condition, wrong operator)
• Data error (bad input, corrupted state, migration issue, seeding problem)
• Integration error (API contract mismatch, timing issue, auth failure, version mismatch)
• UI error (display bug, wrong label, accessibility failure, incorrect formatting)
• Performance (timeout, slowness, memory exhaustion, N+1)
• Security (unauthorized access, data exposure, injection)

State severity and type before Phase 2. P0 = escalate first.

Phase 2 — Isolation

Narrow to the smallest reproducible case:

• Exact inputs that trigger the defect (values, state, sequence of actions)
• Inputs that do NOT trigger it (establishes the boundary of the defect)
• Exact code path affected (file and line range — not "somewhere in the module")
• Is the defect in logic, data, or environment?
• Is it deterministic or intermittent?

Write a failing test that captures the defect BEFORE writing the fix. This test is the regression test. It must fail now and pass after the fix. A defect without a regression test will recur.

Phase 3 — Fix

Apply the minimal fix addressing the confirmed root cause.

Same constraints as systematic-debug Phase 4:

• One fix per defect — no bundling with unrelated improvements
• Preserve all adjacent behavior — only fix what the defect covers
• Touch only the files necessary — flag other issues separately
• Regression test must FAIL before and PASS after

Phase 4 — Verification Checklist

Before closing:

[ ] Regression test written and passes
[ ] Original defect scenario no longer reproduces
[ ] Adjacent functionality manually spot-checked
[ ] Performance: fix did not introduce measurable regression
[ ] Security: fix does not introduce new attack surface
[ ] Payroll-specific: if calculation affected, verify adjacent pay periods
[ ] Full test suite passes
[ ] Code review completed (code-reviewer skill or human review)

Phase 5 — Closure Report

Output this structured report. It goes into DECISIONS.md under DEFECT LEARNINGS.

## Defect Closure Report

**Defect ID:** [Ticket/incident reference]
**Severity / Type:** [P0–P3 / Type from Phase 1]
**Reported by:** [QA / user / monitoring — date]
**Closed:** [Date]

**Root Cause:**
[One paragraph. What was wrong. Why it was wrong. Why it wasn't caught earlier.]

**Fix Summary:**
[What was changed. Files. Lines. Nature of change.]

**Regression Test:**
[Test file and test name/description]

**Verification Evidence:**
[What was checked, how, and the outcome]

**Blast Radius:**
[Adjacent systems checked. Any risks surfaced. None or list.]

**Prevented By:**
[What would have caught this earlier — spec gap? missing test case? review miss?
 What process change prevents this class of defect going forward?]

The "Prevented By" field is required and non-negotiable. It is the only output that makes the team smarter. Defects without a prevention lesson are defects you will see again.