* test(#1960): add failing-first RCA-branching contract + schema-invariant tests Epic #1957 Phase 2A. Source-text-is-the-product contract tests (fishbone >=2 categories, AND-gate, multi-cause root_cause, backward compat, reasoning checkpoint candidate_causes+and_gate fields, debugger-philosophy single-cause note, DEBUG template) plus behavioral schema-invariant checks on two fixtures: two contributing causes (AND-gate yes) -> both recorded; single-cause (AND-gate no) -> one root_cause, identical to today. Failing-first: reference, agent edits, and template note do not yet exist. * feat(#1960): add RCA branching (fishbone + AND-gate) to gsd-debugger Epic #1957 Phase 2A. Guards against 5-Whys single-cause bias: before committing root_cause, the debugger enumerates candidate causes across >=2 Ishikawa categories (code/config/environment/data) and explicitly answers an AND-gate question. When the AND-gate fires, every contributing cause is recorded, so a multi-cause fix no longer recurs via the unaddressed second cause. Resolution.root_cause may hold one OR a small set (additive; single-cause sessions are byte-identical to today). The Structured Reasoning Checkpoint gains candidate_causes + and_gate fields; debugger-philosophy.md adds the single-cause-bias trap. Full rules extracted to gsd-core/references/debugger-rca-branching.md (slim Phase 2 routing + 2 checkpoint fields kept in the agent). INVENTORY + manifest + agent-size baseline + install-parity goldens + AGENTS.md + DEBUG template updated. * fix(#1960): address orthogonal review (AND-gate self-consistency, parity guard, narrowed claim, ripples) - Reference: the collapse rule now enforces AND-gate self-consistency — and_gate=yes with a single confirmed cause is flagged as incomplete (return to Phase 3); a race/timing note clarifies such bugs bridge categories; the 'byte-identical' backward-compat claim narrowed to 'root_cause shape unchanged; reasoning_checkpoint gains 2 fields in every session'. - DEBUG.md: stale 'five-field' mirror prose -> seven-field (parallel-surface drift the reviewer flagged); new debug-session-management parity test pins the field-count claim to the gsd-debugger.md YAML keys (CRLF-safe). - Scalar-assuming consumers of set-valued root_cause updated: session-manager compact summaries (319/332), diagnose-only return (1062), archive entry (1216), ROOT CAUSE FOUND return (1322). - Test: added the AND-gate-yes/single-cause invariant + fixture; rephrased the fixture describe block honestly as a schema-invariant specification. - Phase 2 bullet phrasing clarified ('at hypothesis formation, before the Phase 4 commit'). * test(#1960): parity regex accepts word-form count ('seven-field' or '7-field') * test(#1960): parity regex counts array-valued YAML keys (no inline value) * chore(#1960): backfill changeset pr number (PR #2405)
This commit is contained in:
@@ -316,7 +316,7 @@ Return compact summary (terminal — investigation resolved):
|
||||
## DEBUG SESSION COMPLETE
|
||||
|
||||
**Session:** {final path — resolved/ if archived, otherwise debug_file_path}
|
||||
**Root Cause:** {one sentence from Resolution.root_cause, or "not determined"}
|
||||
**Root Cause:** {one sentence, or a '; '-joined list when the AND-gate identified multiple contributing causes, from Resolution.root_cause; or "not determined"}
|
||||
**Fix:** {one sentence from Resolution.fix, or "not applied"}
|
||||
**Cycles:** {N} (investigation) + {M} (fix)
|
||||
**TDD:** {yes/no}
|
||||
@@ -329,7 +329,7 @@ If the session was abandoned by user choice, return (terminal — user stopped):
|
||||
## DEBUG SESSION COMPLETE
|
||||
|
||||
**Session:** {debug_file_path}
|
||||
**Root Cause:** {one sentence if found, or "not determined"}
|
||||
**Root Cause:** {one sentence if found (or a '; '-joined list if the AND-gate identified multiple contributing causes), or "not determined"}
|
||||
**Fix:** not applied
|
||||
**Cycles:** {N}
|
||||
**TDD:** {yes/no}
|
||||
|
||||
@@ -253,6 +253,10 @@ reasoning_checkpoint:
|
||||
falsification_test: "[what specific observation would prove this hypothesis wrong]"
|
||||
fix_rationale: "[why the proposed fix addresses the root cause — not just the symptom]"
|
||||
blind_spots: "[what you haven't tested that could invalidate this hypothesis]"
|
||||
candidate_causes:
|
||||
- "[cause in category: code|config|environment|data]"
|
||||
- "[cause in a DIFFERENT category — single-category is not a branch]"
|
||||
and_gate: "[could this failure require >1 contributing condition simultaneously? yes/no + why — see RCA branching]"
|
||||
```
|
||||
|
||||
**Check before proceeding:**
|
||||
@@ -260,8 +264,9 @@ reasoning_checkpoint:
|
||||
- Is the confirming evidence direct observation, not inference?
|
||||
- Does the fix address the root cause or a symptom?
|
||||
- Have you documented your blind spots honestly?
|
||||
- **Did you branch across ≥2 categories and answer the AND-gate?** (Single-cause is fine when the AND-gate is no — but you must have checked.)
|
||||
|
||||
If you cannot fill all five fields with specific, concrete answers — you do not have a confirmed root cause yet. Return to investigation_loop.
|
||||
If you cannot fill all seven fields with specific, concrete answers — you do not have a confirmed root cause yet. Return to investigation_loop.
|
||||
|
||||
## Minimal Reproduction
|
||||
|
||||
@@ -788,7 +793,7 @@ Each resolved session appends one entry:
|
||||
## {slug} — {one-line description}
|
||||
- **Date:** {ISO date}
|
||||
- **Error patterns:** {comma-separated keywords extracted from symptoms.errors and symptoms.actual}
|
||||
- **Root cause:** {from Resolution.root_cause}
|
||||
- **Root cause(s):** {from Resolution.root_cause — one cause, or a '; '-joined list when the AND-gate fired}
|
||||
- **Fix:** {from Resolution.fix}
|
||||
- **Files changed:** {from Resolution.files_changed}
|
||||
---
|
||||
@@ -998,6 +1003,10 @@ At investigation decision points, apply structured reasoning:
|
||||
|
||||
**Phase 2: Form hypothesis**
|
||||
- Based on evidence AND common pattern matches, form SPECIFIC, FALSIFIABLE hypothesis
|
||||
- **Branch, don't chain** — at hypothesis formation (so it's done before the Phase 4 commit), enumerate candidate causes across ≥2 Ishikawa categories (code / config / environment / data) and answer the AND-gate check; `root_cause` may hold a set when the AND-gate fires:
|
||||
|
||||
@~/.claude/gsd-core/references/debugger-rca-branching.md
|
||||
|
||||
- Update Current Focus with hypothesis, test, expecting, next_action
|
||||
|
||||
**Phase 3: Test hypothesis**
|
||||
@@ -1050,7 +1059,7 @@ Return structured diagnosis:
|
||||
|
||||
**Debug Session:** .planning/debug/{slug}.md
|
||||
|
||||
**Root Cause:** {from Resolution.root_cause}
|
||||
**Root Cause:** {from Resolution.root_cause — one cause, or a '; '-joined list when the AND-gate identified multiple contributing causes}
|
||||
|
||||
**Evidence Summary:**
|
||||
- {key finding 1}
|
||||
@@ -1090,7 +1099,7 @@ Update status to "fixing".
|
||||
|
||||
**0. Structured Reasoning Checkpoint (MANDATORY)**
|
||||
- Write the `reasoning_checkpoint` block to Current Focus (see Structured Reasoning Checkpoint in investigation_techniques)
|
||||
- Verify all five fields can be filled with specific, concrete answers
|
||||
- Verify every field can be filled with specific, concrete answers — including the RCA `candidate_causes` (≥2 categories) and `and_gate` fields
|
||||
- If any field is vague or empty: return to investigation_loop — root cause is not confirmed
|
||||
|
||||
**1. Implement minimal fix**
|
||||
@@ -1204,7 +1213,7 @@ Then append the entry:
|
||||
## {slug} — {one-line description of the bug}
|
||||
- **Date:** {ISO date}
|
||||
- **Error patterns:** {comma-separated keywords from Symptoms.errors + Symptoms.actual}
|
||||
- **Root cause:** {Resolution.root_cause}
|
||||
- **Root cause(s):** {Resolution.root_cause — joined as '; ' when multiple contributing causes were confirmed}
|
||||
- **Fix:** {Resolution.fix}
|
||||
- **Files changed:** {Resolution.files_changed joined as comma list}
|
||||
---
|
||||
@@ -1309,7 +1318,7 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
|
||||
|
||||
**Debug Session:** .planning/debug/{slug}.md
|
||||
|
||||
**Root Cause:** {specific cause with evidence}
|
||||
**Root Cause:** {specific cause with evidence — one cause, or a '; '-joined list when the AND-gate identified multiple contributing causes}
|
||||
|
||||
**Evidence Summary:**
|
||||
- {key finding 1}
|
||||
|
||||
Reference in New Issue
Block a user