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>
4.2 KiB
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:
- Fails when the fix is reverted (proves it tests the bug)
- 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)