debug-inspect

Fagan Inspection — 6-Phase Systematic Analysis

Fagan inspection is a formal peer review methodology achieving 60-90% defect detection rates. You will execute all 6 phases in sequence. Do not skip phases — the rigor is the point.

Ask for a bug description if not provided. Then proceed through all phases, documenting results at each step.

---

Phase 1: Planning

Define the inspection scope:

1. Restate the bug clearly — symptoms, environment, frequency, impact
2. Identify inspection scope: which files, components, services are involved
3. Define success criteria: what does "root cause found" look like?
4. List affected stakeholders and systems
5. Identify what information is still missing and flag it

Document: Bug summary, scope, success criteria, open questions.

---

Phase 2: Overview

Build context before touching code:

1. Run git log --oneline -30 — look for recent changes to affected areas, revert commits, emergency fixes
2. Review any feature specs, tickets, or comments in the relevant code areas
3. Map the impact: which users, systems, environments are affected?
4. Construct a preliminary timeline of when the issue first appeared

Document: Commit history analysis, preliminary timeline, impact scope.

---

Phase 3: Preparation

Systematic artifact examination — read the code before theorizing:

1. Code analysis — read the affected files; look for anti-patterns, complex conditionals, unusual logic
2. Test analysis — identify what's tested, what isn't, and what's tested incorrectly
3. Configuration analysis — check environment-specific settings, dependency versions, resource limits
4. Dependency analysis — version conflicts, external service assumptions
5. Generate hypotheses — list 3-5 possible causes ranked by likelihood

Document: Code review findings, test coverage gaps, config issues, preliminary hypotheses.

---

Phase 4: Inspection Meeting

Systematic defect identification across all categories:

Logic Defects

• Algorithm errors, incorrect business logic
• Control flow issues (wrong branching, missing cases)
• Boundary violations (off-by-one, overflow, underflow)
• State management issues, invalid transitions

Interface Defects

• API misuse, wrong parameter types or ordering
• Component communication failures
• Protocol violations, incorrect message formats
• Version incompatibilities not handled

Data Defects

• Input validation gaps
• Type mismatches or implicit coercions
• Data corruption, incorrect transformations
• Race conditions on shared state

Performance & Security Defects

• Memory leaks, resource exhaustion patterns
• N+1 queries, blocking operations
• Injection vulnerabilities, auth issues, data exposure

For each defect found: document evidence, assign severity (P0-P3), categorize.

Root cause analysis: Apply fishbone thinking across People / Process / Technology / Environment / Data / Methods.

Document: Defect list with evidence, root cause analysis, severity matrix.

---

Phase 5: Rework Planning

Turn findings into a concrete fix plan:

1. Fix proposals — one or more approaches with tradeoff analysis (simplicity vs completeness vs risk)
2. Test strategy — what new tests are needed to validate the fix and prevent recurrence?
3. Risk assessment — what could go wrong with the proposed fix? Regression risk?
4. Implementation order — what needs to change first? Any dependencies?
5. Rollback plan — how do you revert if the fix makes things worse?

Document: Fix proposals with tradeoffs, test strategy, risk assessment, implementation order.

---

Phase 6: Follow-up

Close the loop:

1. Summarize validation steps — how will you confirm the fix worked?
2. List documentation updates needed (code comments, runbooks, README)
3. Capture lessons learned — what process change prevents this class of bug?
4. Generate the debug report

---

Output Format

Produce a structured debug report:

# Fagan Inspection Report

**Report ID:** INSPECT-[YYYYMMDD]
**Severity:** P[0-3]
**Date:** [today]

## Executive Summary
[2-3 sentences: what the bug is, root cause, recommended fix]

## Phase Results

### Phase 1 — Planning
[Scope, success criteria, open questions]

### Phase 2 — Overview
[Git history findings, timeline, impact scope]

### Phase 3 — Preparation
[Code findings, test gaps, config issues, initial hypotheses]

### Phase 4 — Inspection
[Defects found with evidence, root cause analysis]

### Phase 5 — Rework Plan
[Fix proposal, test strategy, risk assessment]

### Phase 6 — Follow-up
[Validation steps, doc updates needed, lessons learned]

## Completion Checklist
- [ ] All 6 phases completed
- [ ] Root cause identified with evidence
- [ ] Fix recommended with tradeoffs
- [ ] Test strategy defined
- [ ] Risk assessment completed
- [ ] Lessons learned documented