diff --git a/CHANGELOG.md b/CHANGELOG.md index 882e75b..27f1594 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 explanation": it prints the current state, the requested state, the valid next state(s) from the state machine, and the shortest legal path to the requested state when reachable (e.g. `draft -> done` is rejected with the hint `draft -> approved -> in-progress -> done`). No file is mutated on refusal. +- `/sd:bug` Phase 3 no longer assumes a confirmed root cause always arrives. The investigation loop + previously said "Continue until one is CONFIRMED" with no exit, so a bug whose every hypothesis is + rejected/inconclusive had no defined stopping point. Added Gate 3a (hypothesis tree exhausted): the + loop now terminates on a CONFIRMED hypothesis OR an exhausted tree, and the exhausted case STOPs and + asks the user to re-enumerate (with new evidence), add observability, or abort as "root cause not + found" - never guessing a fix from an unconfirmed tree. - `install/install.sh` marked executable (mode `100755`, matching `uninstall.sh`); it was `100644`, so the documented `./install/install.sh` invocation failed with "Permission denied" on a fresh Linux checkout. Surfaced by the new CI round-trip. diff --git a/commands/bug.md b/commands/bug.md index d07647e..953d1c3 100644 --- a/commands/bug.md +++ b/commands/bug.md @@ -108,7 +108,29 @@ If the user insists on proceeding without repro, log a constitution exception to - Result: CONFIRMED / REJECTED / INCONCLUSIVE. - Append result with evidence pointers (file:line, log lines, query results) to `03-decisions.md`. - Document REJECTED hypotheses with FULL reasoning - this is knowledge preservation for future similar bugs. - - Continue until one is CONFIRMED. + - Terminate the loop when EITHER one hypothesis is CONFIRMED (proceed to Gate 3) OR every enumerated + hypothesis is exhausted - all REJECTED, or only INCONCLUSIVE ones remain with no new evidence to act + on (go to Gate 3a). Never guess a fix from an unconfirmed tree. + +### ⛔ Gate 3a - Hypothesis tree exhausted (no confirmed root cause) + +Reached ONLY when the loop ends with no CONFIRMED hypothesis. STOP. Do NOT proceed to a fix - a fix on an +unconfirmed root cause risks treating a symptom. + +Append the exhausted tree (every hypothesis with its REJECTED / INCONCLUSIVE verdict and reasoning) to +`.specs/BUG-/03-decisions.md` - this is the knowledge record for the next investigation. + +Ask: + +> All hypotheses were rejected or inconclusive; no root cause confirmed. How do you want to proceed? +> (re-enumerate / observe / abort) + +- `re-enumerate` -> return to Phase 3 step 1 with the new evidence/telemetry that justifies fresh + hypotheses. Do not re-run identical hypotheses. +- `observe` -> add observability (logging, tracing, metrics), reproduce again to gather evidence, then + re-enumerate. Log the gap to `05-retro.md`. +- `abort` -> set status and close the spec as "root cause not found"; record the exhausted tree as the + outcome in `05-retro.md`. ### ⛔ Gate 3 - Root cause confirmed