| name | harness-maintain-debug |
| description | Systematic debugging as a maintenance transaction. Use when encountering bugs, test failures, regressions, unexpected behavior, or any fix request in existing code. Enforces: symptom → reproduce → evidence → root cause → minimal patch → regression → review → close. Triggers on: "debug this", "fix this bug", "test failed", "not working", "regression", "unexpected behavior", "why is this broken", "修一下", "为什么失败".
|
Harness Maintain: Debug
Systematic debugging as a tracked maintenance transaction. Every debug session produces a traceable repair record with enforced gates.
Iron Laws
1. NO PATCH WITHOUT REPRODUCTION AND EVIDENCE.
2. NO COMPLETION WITHOUT REGRESSION TEST.
3. NO CONTINUED PATCHING AFTER 3 FAILED HYPOTHESES — ESCALATE.
Violating the letter of these laws is violating the spirit of debugging.
When to Use
Use for ANY technical issue in existing code: test failures, bugs in production, unexpected behavior, performance problems, build failures, integration issues, regressions.
See ./references/anti-patterns.md for "use ESPECIALLY when" and "don't skip when" guidance.
Prerequisites
- Read
../../references/DOMAIN-AWARENESS.md for project terminology
- This is existing code (not green-field). If no codebase exists, use
harness-specify instead.
The Seven Phases — Overview
You MUST complete each phase before proceeding to the next. Read ./references/phases-detail.md for full steps.
| Phase | Name | One-line |
|---|
| 0 | Intake | Create the maintenance record, determine debug ID |
| 1 | Reproduce | Reproduce the issue consistently, record exact steps |
| 2 | Evidence | Gather logs, traces, diffs, multi-component boundary data |
| 3 | Diagnose | Find working examples, form single hypothesis, test minimally |
| 4 | Patch | Classify risk, create failing test, implement minimal fix |
| 5 | Regression | Add anti-recurrence test, verify red-green cycle |
| 6 | Review | Review diff, answer checklist, re-classify risk |
| 7 | Close | Verify all conditions met, route by risk level |
State Machine
intake
↓
reproducing
├─ not-reproduced → evidence-needed
│ └─ cannot-reproduce → close-with-note
└─ reproduced
↓
diagnosing
↓
root-caused
↓
patching ──── [risk gate: core/infra → human approval]
↓
regression
↓
review
↓
closed
└─ (if risk ≥ branch → eval → report)
Failure escalation:
hypothesis failed once → return to evidence
hypothesis failed twice → re-read code, compare working examples
three failed patches → ESCALATE to architecture-review
Escalation rule: Three failed patches means the architecture may be wrong, not the fix. Stop and discuss with the human before attempting more fixes.
Risk Integration
Debug flow does NOT bypass Harness risk gates. It calls harness-risk at two points:
- Before patching (Phase 4): Classify blast radius. core/infra → human approval required.
- Before closing (Phase 6): Re-check diff. Risk may have escalated.
Rule: Debug is not a low-risk exemption. A bug fix can still be a core/infra change.
Project File Structure
project/
├── maintenance/
│ ├── index.md # maintenance log index
│ └── debug/
│ └── YYYY-MM-DD-<slug>/
│ ├── record.md # debug record (required)
│ ├── evidence/ # logs, traces, patches (if needed)
│ └── ...
For small bugs, record.md contains everything. For complex bugs, split into separate files as needed. All sections currently live in record.md. When a record exceeds ~200 lines, split into separate files (repro.md, regression.md, review.md). The index should always be one row per debug session, not one row per phase.
References
../../references/DOMAIN-AWARENESS.md — project terminology and DDD rules../../references/ROUTING_TABLE.md — routing table (includes debug routes)./references/root-cause-tracing.md — backward tracing through call stacks./references/defense-in-depth.md — multi-layer validation after fixes./references/phases-detail.md — full instructions for all seven phases./references/anti-patterns.md — red flags, rationalizations, when to use process../../references/templates/DEBUG_RECORD_TEMPLATE.md — record template../../references/templates/DEBUG_INDEX_TEMPLATE.md — index template
Related Skills
- harness-risk — blast radius classification before and after patching
- harness-tdd — for writing the failing test in Phase 4
- harness-eval — for final compliance check
- harness-report — for implementation report if needed
Real-World Impact
From systematic debugging sessions (source: Superpowers project):
- Systematic approach: 15-30 minutes to fix
- Random fixes approach: 2-3 hours of thrashing
- First-time fix rate: 95% vs 40%
- New bugs introduced: Near zero vs common
