catlog22 Investigate
Systematic debugging skill that enforces the Iron Law: never fix without a confirmed root cause. Produces a structured debug report with full evidence chain, minimal fix, and regression test.
Iron Law Principle
No fix without confirmed root cause. Every investigation follows a strict evidence chain:
- Reproduce the bug with concrete evidence
- Analyze patterns to assess scope
- Form and test hypotheses (max 3 strikes)
- Implement minimal fix ONLY after root cause is confirmed
- Verify fix and generate structured report
Violation of the Iron Law (skipping to Phase 4 without Phase 3 confirmation) is prohibited.
Key Design Principles
- Evidence-First: Collect before theorizing. Logs, stack traces, and reproduction steps are mandatory inputs.
- Minimal Fix: Change only what is necessary. Refactoring is not debugging.
- 3-Strike Escalation: If 3 consecutive hypothesis tests fail, STOP and escalate with a diagnostic dump.
- Regression Coverage: Every fix must include a test that fails without the fix and passes with it.
- Structured Output: All findings are recorded in machine-readable JSON for future reference.
Execution Flow
Phase 1: Root Cause Investigation
Reproduce bug, collect evidence (errors, logs, traces)
Use ccw cli --tool gemini --mode analysis for initial diagnosis
Output: investigation-report.json
|
v
Phase 2: Pattern Analysis
Search codebase for similar patterns (same error, module, antipattern)
Assess scope: isolated vs systemic
Output: pattern-analysis section in report
|
v
Phase 3: Hypothesis Testing
Form max 3 hypotheses from evidence
Test each with minimal read-only probes
3-strike rule: STOP and escalate on 3 consecutive failures
Output: confirmed root cause with evidence chain
|
v
Phase 4: Implementation [GATE: requires Phase 3 confirmed root cause]
Implement minimal fix
Add regression test
Verify fix resolves reproduction case
|
v
Phase 5: Verification & Report
Run full test suite
Check for regressions
Generate structured debug report to .workflow/.debug/
Directory Setup
mkdir -p .workflow/.debug
Output Structure
.workflow/.debug/
debug-report-{YYYY-MM-DD}-{slug}.json # Structured debug report
Completion Status Protocol
This skill follows the Completion Status Protocol defined in _shared/SKILL-DESIGN-SPEC.md sections 13-14.
| Status | When |
|---|---|
| DONE | Root cause confirmed, fix applied, regression test passes, no regressions |
| DONE_WITH_CONCERNS | Fix applied but partial test coverage or minor warnings |
| BLOCKED | Cannot reproduce bug, or 3-strike escalation triggered in Phase 3 |
| NEEDS_CONTEXT | Missing reproduction steps, unclear error conditions |
Reference Documents
| Document | Purpose |
|---|---|
| phases/01-root-cause-investigation.md | Evidence collection and reproduction |
| phases/02-pattern-analysis.md | Codebase pattern search and scope assessment |
| phases/03-hypothesis-testing.md | Hypothesis formation, testing, and 3-strike rule |
| phases/04-implementation.md | Minimal fix with Iron Law gate |
| phases/05-verification-report.md | Test suite, regression check, report generation |
| specs/iron-law.md | Iron Law rules definition |
| specs/debug-report-format.md | Structured debug report JSON schema |
CLI Integration
This skill leverages ccw cli for multi-model analysis at key points:
| Phase | CLI Usage | Mode |
|---|---|---|
| Phase 1 | Initial diagnosis from error evidence | --mode analysis |
| Phase 2 | Cross-file pattern search | --mode analysis |
| Phase 3 | Hypothesis validation assistance | --mode analysis |
All CLI calls use --mode analysis (read-only). No write-mode CLI calls during investigation phases 1-3.