refacil-sdd-ai 5.0.4 → 5.0.5

package/README.md

@@ -443,6 +443,8 @@ Local bus (WebSocket over `127.0.0.1`) so agents across different repos can comm
 
 **SDD-AI conventions in the bus**: anyone in the room joined with `/refacil:join` (methodology already active in the repo). **Change requests** to another session go with **clear scope** in the `ask` (no pasting the guide in every message); the destination repo channels with **`/refacil:propose`** and whoever implements **closes via bus** to who requested the work. Details and edge cases: `refacil-prereqs/BUS-CROSS-REPO.md` in the installed skills.
 
+**Contract-first questions (recommended)**: for cross-repo integration clarifications, format `ask/reply` around contract fields (integration point, input contract, output contract, compatibility, source of truth). If the first response is partial, send a focused retry `ask` only for unresolved points. This keeps bus conversations actionable for integration work instead of generic chat.
+
 **Pure observer** (0 tokens): `refacil-sdd-ai bus watch <session>` or `refacil-sdd-ai bus view` for the web UI.
 
 > **Diagrams, scenarios and pitch**: see `refacil-bus-diagrams.md` (included in the package) — includes architecture, flow with attend, flow without attend, comparative impact table, and visual decision guide (Mermaid).

package/agents/debugger.md

@@ -56,20 +56,26 @@ If you prefer to continue here, provide:
 
 The main agent passes you: `mode: investigation` + bug `description`.
 
-### Step 1: Investigate root cause
+### Step 1: Reproduce and minimize first
+
+- Define the minimal reproducible scenario from the description (inputs, trigger, observed failure).
+- Narrow scope to the smallest code path that can still explain the failure.
+
+### Step 2: Investigate root cause
 
 - Search the codebase for symbols/files mentioned in logs or stack traces from the description.
 - Trace the flow from entry (controller/endpoint) to the failure point.
 - Review recent commits if the bug is new: `git log --oneline -20`.
 - If the cause seems to be in an interaction with another repo (unexpected API response, event with a different format, broken contract on the producer/consumer side), indicate it in `hypotheses` with `crossRepo: true` and the protocol from `refacil-prereqs/BUS-CROSS-REPO.md` so the wrapper resolves it.
 
-### Step 2: Formulate hypotheses
+### Step 3: Formulate hypotheses with evidence
 
 Prepare 1-3 hypotheses ordered by confidence (`high`/`medium`/`low`), each with:
 - Suspicious file and line.
 - Description of the unhandled condition.
+- Evidence that supports the hypothesis (repro observation, log, code path check).
 
-### Step 3: Propose fix for hypothesis #1
+### Step 4: Propose fix for hypothesis #1
 
 Describe:
 - Minimum necessary change.
@@ -84,6 +90,7 @@ Describe:
 
 Hypotheses (ordered by confidence):
 1. [high|medium|low] file:line — [description]
+   Evidence: [what validates this hypothesis]
 2. ...
 
 Proposed fix for hypothesis #1:
@@ -101,6 +108,7 @@ Proposed fix for hypothesis #1:
       "file": "<path/file>",
       "line": <int or null>,
       "description": "<description of the cause>",
+      "evidence": "<brief evidence backing this hypothesis>",
       "crossRepo": <bool>
     }
   ],
@@ -197,6 +205,7 @@ Resolve and run the test command according to `METHODOLOGY-CONTRACT.md §3`. All
 ## Rules
 
 - In mode=investigation: **NEVER modify files**. Only report hypotheses and proposed fix.
+- In mode=investigation: follow diagnose loop discipline (reproduce, minimize, hypothesize, validate evidence) before proposing a fix.
 - In mode=fix: the fix must be MINIMAL. Never over-refactor.
 - Regression tests are MANDATORY in mode=fix.
 - Use **concise** output mode by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor and OpenCode",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/bug/SKILL.md

@@ -8,6 +8,9 @@ user-invocable: true
 
 This skill is a **wrapper** that guides the user through the bug fix flow and delegates the heavy work to the `refacil-debugger` sub-agent. The sub-agent operates in two modes: `investigation` (analyzes and proposes hypotheses without modifying anything) and `fix` (implements the approved correction, generates tests, and creates traceability). Hypothesis confirmation and branch validation occur in this wrapper, between the two invocations.
 
+The investigation stage follows a **diagnose loop** to reduce weak fixes:
+1) reproduce, 2) minimize scope, 3) form evidence-backed hypotheses, 4) validate evidence, 5) propose minimal correction.
+
 **Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
 
 ## Flow
@@ -40,8 +43,10 @@ Invoke the `refacil-debugger` sub-agent passing it:
 - `description`: complete bug description (collected in Step 1 or from `$ARGUMENTS`).
 
 The sub-agent:
+- Reproduces and minimizes the failure scope first.
 - Searches the codebase for symbols/files from logs or stack traces.
 - Traces the flow from entry to the failure point.
+- Validates hypotheses with explicit evidence.
 - Reviews recent commits if the bug is new.
 - Returns hypotheses ordered by confidence + proposed correction, fenced as ` ```refacil-debug-investigation `.
 
@@ -51,6 +56,7 @@ Show the user the hypotheses and the proposed correction. Ask explicitly:
 
 ```
 Most confident hypothesis: [description — file:line]
+Evidence used: [repro step / observed condition / validation result]
 Proposed fix: [minimal description]
 Files to modify: [list]
 
@@ -162,6 +168,7 @@ If the sub-agent returned `result: "FAILED"` (tests not passing), present the fa
 ## Rules
 
 - **Always investigate before proposing** — do not delegate the fix without a confirmed hypothesis.
+- In investigation, prefer the diagnose loop order: reproduce → minimize → hypothesize → validate evidence → propose fix.
 - **NEVER implement without explicit user approval** (Step 3).
 - **Always validate the branch** (Step 4) before delegating the fix.
 - **Do not replicate investigation or implementation logic here** — that lives in `refacil-debugger`.