enhance(#1960): add RCA branching (fishbone + AND-gate) to gsd-debugger (#2405)

* 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:
Tom Boucher
2026-07-18 13:42:58 -04:00
committed by GitHub
parent 50efae13ce
commit f8b16d1874
48 changed files with 448 additions and 85 deletions

View File

@@ -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}

View File

@@ -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}