mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-30 20:21:09 +08:00
67ff3fe339
- Add 3 new Claude skills: investigate (Iron Law debugging), security-audit (OWASP Top 10 + STRIDE), ship (gated release pipeline) - Port all 3 skills to Codex v4 format under .codex/skills/ using Deep Interaction pattern (spawn_agent + assign_task phase transitions) - Update README/README_CN acknowledgments: credit gstack (https://github.com/garrytan/gstack) as inspiration source Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# Iron Law of Debugging
|
|
|
|
The Iron Law defines the non-negotiable rules that govern every investigation performed by this skill. These rules exist to prevent symptom-fixing and ensure durable, evidence-based solutions.
|
|
|
|
## When to Use
|
|
|
|
| Phase | Usage | Section |
|
|
|-------|-------|---------|
|
|
| Phase 3 | Hypothesis must produce confirmed root cause before proceeding | Rule 1 |
|
|
| Phase 1 | Reproduction must produce observable evidence | Rule 2 |
|
|
| Phase 4 | Fix scope must be minimal | Rule 3 |
|
|
| Phase 4 | Regression test is mandatory | Rule 4 |
|
|
| Phase 3 | 3 consecutive unproductive hypothesis failures trigger escalation | Rule 5 |
|
|
|
|
---
|
|
|
|
## Rules
|
|
|
|
### Rule 1: Never Fix Without Confirmed Root Cause
|
|
|
|
**Statement**: No code modification is permitted until a root cause has been confirmed through hypothesis testing with concrete evidence.
|
|
|
|
**Enforcement**: Phase 4 begins with an Iron Law gate check. If `confirmed_root_cause` is absent from the investigation report, Phase 4 is blocked.
|
|
|
|
**Rationale**: Fixing symptoms without understanding the cause leads to:
|
|
- Incomplete fixes that break under different conditions
|
|
- Masking of deeper issues
|
|
- Wasted investigation time when the bug recurs
|
|
|
|
### Rule 2: Evidence Must Be Reproducible
|
|
|
|
**Statement**: The bug must be reproducible through documented steps, or if not reproducible, the evidence must be sufficient to identify the root cause through static analysis.
|
|
|
|
**Enforcement**: Phase 1 documents reproduction steps and evidence. If reproduction fails, this is flagged as a concern but does not block investigation if sufficient static evidence exists.
|
|
|
|
**Acceptable evidence types**:
|
|
- Failing test case
|
|
- Error message with stack trace
|
|
- Log output showing the failure
|
|
- Code path analysis showing the defect condition
|
|
|
|
### Rule 3: Fix Must Be Minimal
|
|
|
|
**Statement**: The fix must change only what is necessary to address the confirmed root cause. No refactoring, no feature additions, no style changes to unrelated code.
|
|
|
|
**Enforcement**: Phase 4 requires a fix plan before implementation. Changes exceeding 3 files require written justification.
|
|
|
|
**What counts as minimal**:
|
|
- Adding a missing null check
|
|
- Fixing an incorrect condition
|
|
- Correcting a wrong variable reference
|
|
- Adding a missing import or dependency
|
|
|
|
**What is NOT minimal**:
|
|
- Refactoring the function "while we're here"
|
|
- Renaming variables for clarity
|
|
- Adding error handling to unrelated code paths
|
|
- Reformatting surrounding code
|
|
|
|
### Rule 4: Regression Test Required
|
|
|
|
**Statement**: Every fix must include a test that:
|
|
1. Fails when the fix is reverted (proves it tests the bug)
|
|
2. Passes when the fix is applied (proves the fix works)
|
|
|
|
**Enforcement**: Phase 4 requires a regression test before the phase is marked complete.
|
|
|
|
**Test requirements**:
|
|
- Test name clearly references the bug scenario
|
|
- Test exercises the exact code path of the root cause
|
|
- Test is deterministic (no timing dependencies, no external services)
|
|
- Test is placed in the appropriate test file for the affected module
|
|
|
|
### Rule 5: 3-Strike Escalation on Hypothesis Failure
|
|
|
|
**Statement**: If 3 consecutive hypothesis tests produce no actionable insight, the investigation must STOP and escalate with a full diagnostic dump.
|
|
|
|
**Enforcement**: Phase 3 tracks a strike counter. On the 3rd consecutive unproductive failure, execution halts and outputs the escalation block.
|
|
|
|
**What counts as a strike**:
|
|
- Hypothesis rejected AND no new insight gained
|
|
- Test was inconclusive AND no narrowing of search space
|
|
|
|
**What does NOT count as a strike**:
|
|
- Hypothesis rejected BUT new evidence narrows the search
|
|
- Hypothesis rejected BUT reveals a different potential cause
|
|
- Test inconclusive BUT identifies a new area to investigate
|
|
|
|
**Post-escalation**: Status set to BLOCKED. No further automated investigation. Preserve all intermediate outputs for human review.
|
|
|
|
---
|
|
|
|
## Validation Checklist
|
|
|
|
Before completing any investigation, verify:
|
|
|
|
- [ ] Rule 1: Root cause confirmed before any fix was applied
|
|
- [ ] Rule 2: Bug reproduction documented (or static evidence justified)
|
|
- [ ] Rule 3: Fix changes only necessary code (file count, line count documented)
|
|
- [ ] Rule 4: Regression test exists and passes
|
|
- [ ] Rule 5: No more than 3 consecutive unproductive hypothesis tests (or escalation triggered)
|