@code-yeongyu/lazycodex 0.1.1

package/packages/shared-skills/skills/debugging/references/methodology/04-oracle-triple.md

@@ -0,0 +1,136 @@
+# Phase 4 — Oracle Triple Consultation
+
+At 2 consecutive failed hypothesis rounds, stop investigating and reframe. Continuing past two failures usually means the real cause is in a category you haven't imagined — and more time on your current mental model is wasted time.
+
+The Oracle Triple is how you break out of the mental box.
+
+> ⚠️ **Wrong tool for non-debugging tasks.** The Triple is for *stuck root-cause hunts*. If your task is producing an artifact (extraction, reverse engineering, audit, compliance documentation) and you want a skeptical review before declaring it done, use the **Verification Oracle** pattern in [partial-runtime-evidence.md](partial-runtime-evidence.md#verification-oracle-pattern-for-non-debug-tasks). Running the Triple on a finished extraction returns three diverging "what if you tried…" tangents that are not what you need.
+
+---
+
+## When to invoke
+
+| Situation | Invoke? |
+|---|---|
+| 1 round failed, you have new distinguishing evidence | No — run one more round with a refined hypothesis set |
+| 2 rounds failed, hypotheses now feel like variations of each other | **Yes — invoke now** |
+| 2 rounds failed, no new evidence angles left to try | **Yes — invoke now** |
+| You've been investigating >2 hours on the same bug | **Yes — invoke now regardless of round count** |
+| 1 round failed but the user is watching and wants speed | No — one round isn't enough to justify Oracle cost. Resist the urge. |
+
+---
+
+## Why three Oracles, and why *orthogonal* framings
+
+A single Oracle call returns a single coherent analysis. Coherent analyses tend to inherit the framing of the prompt, which means they inherit the same blind spots the investigator already has. Three Oracles with *orthogonal framings* force the analyses to diverge, and the places where they agree across frames is where the real signal lives.
+
+The three framings below are chosen to cover distinct bug-cause categories:
+
+- **A (obvious-but-missed)** — embarrassingly simple causes the investigator walked past.
+- **B (system-boundary)** — causes living at integration seams, not in the code being read.
+- **C (invariant-violation)** — assumptions load-bearing to current hypotheses that may themselves be false.
+
+Spawn all three in parallel.
+
+---
+
+## The three prompts
+
+```
+task(subagent_type="oracle", load_skills=[], run_in_background=true,
+     prompt="[CONTEXT: bug description + evidence captured so far, verbatim, with file:line refs]
+
+     Framing A — OBVIOUS-BUT-MISSED.
+     What is the most embarrassing, most obvious cause that a senior engineer would spot in 30 seconds and we've overlooked? Consider:
+     - typos, off-by-one
+     - wrong variable name / wrong constant / wrong import
+     - stale cache, wrong file edited, wrong process inspected
+     - attached to the wrong instance of the service
+     - test harness running different code than the app
+     - editing src/ while running dist/
+     
+     Give me exactly three candidate causes ranked by likelihood, with one sentence each explaining why our evidence is consistent with each.")
+
+task(subagent_type="oracle", load_skills=[], run_in_background=true,
+     prompt="[CONTEXT: bug description + evidence captured so far]
+
+     Framing B — SYSTEM-BOUNDARY.
+     What if the bug is NOT in the code we've been reading, but at a boundary? Consider:
+     - third-party SDK behavior that contradicts its docs
+     - middleware that mutates the request or response
+     - a proxy/gateway/load balancer that rewrites headers or bodies
+     - build-time vs runtime env-var resolution
+     - module-load-order issue
+     - shared-library version mismatch (system lib vs bundled lib)
+     - ABI difference (native addons, glibc versions, musl vs glibc)
+     - wrong transport (HTTP/1.1 vs HTTP/2, TLS version negotiation)
+     
+     Give me three candidate causes, each naming the specific boundary and the specific contract assumption that might be violated.")
+
+task(subagent_type="oracle", load_skills=[], run_in_background=true,
+     prompt="[CONTEXT: bug description + evidence captured so far]
+
+     Framing C — INVARIANT-VIOLATION.
+     Which invariants that we've been ASSUMING TRUE might actually be false?
+     Enumerate the five assumptions most load-bearing to our current hypotheses, then for each:
+     - describe the smallest runtime query that would falsify it
+     - predict what the observable would be if the invariant holds vs if it fails
+     
+     We want at least one of these queries to be decisive.")
+```
+
+---
+
+## Synthesizing across three Oracles
+
+**Do not pick the highest-ranked candidate from a single Oracle.** That defeats the purpose of getting three framings.
+
+Instead, walk the outputs in this order:
+
+### 1. Agreement scan
+
+Note which candidate causes appear in at least two Oracles' outputs. Independent agreement across orthogonal framings is strong signal — when the obvious-but-missed framing and the system-boundary framing both land on the same cause, that's usually the bug.
+
+### 2. Disagreement scan
+
+Note where Oracles disagree. Disagreement is genuine uncertainty that runtime evidence (not more reasoning) must resolve. Each disagreement becomes a candidate for the next round's distinguishing query.
+
+### 3. New falsification queries
+
+Framing C produces concrete "one query that would decide it" suggestions. Pull these verbatim into your new round's evidence-gathering plan — they are designed to be decisive.
+
+### 4. Build the new hypothesis set
+
+Minimum 3, same rules as Phase 2. Aim to have hypotheses drawn from the agreement scan (likely cause) AND from the disagreement scan (so one round's evidence resolves the disagreement).
+
+Record in the journal:
+
+```markdown
+## Oracle Triple — Round <N>
+- Invoked at: <ISO timestamp>
+- Framing A summary: <top 3 candidates, one line each>
+- Framing B summary: <top 3 candidates>
+- Framing C summary: <5 load-bearing assumptions + falsification queries>
+
+### Cross-framing agreement
+- <candidate> appeared in A + B
+- <candidate> appeared in B + C
+
+### New hypothesis set
+1. <hypothesis> — evidence to gather: <one-liner>
+2. ...
+```
+
+### 5. Reset the counter
+
+Reset the "consecutive failed rounds" counter to 0. Return to Phase 3 (parallel investigation) with the new set.
+
+---
+
+## If *another* 2 rounds fail after the Oracle Triple
+
+You are genuinely stuck. This is the escalation threshold.
+
+Escalate to the user (see `05-escalate.md`) with the full trace: every hypothesis tried, every piece of evidence captured, both Oracle syntheses. Do not guess a fix.
+
+This is rare — in practice, the Oracle Triple resolves almost all stuck debugging sessions within one round, because it pulls in framings the investigator was too close to the code to see.

package/packages/shared-skills/skills/debugging/references/methodology/05-escalate.md

@@ -0,0 +1,69 @@
+# Phase 5 — User Decision Escalation
+
+Escalation is for genuine ambiguity, not for skipping investigation. Most "should I ask the user" moments are really "I don't want to do one more query" moments, and those are wrong.
+
+---
+
+## Ask the user ONLY when
+
+- **Evidence exhausted**, contradictions remain, and further investigation would require a decision with policy implications (e.g. "patch the third-party SDK vs wrap it vs change architecture").
+- The bug has **multiple valid fixes with different scope/risk tradeoffs** and the user's preference drives the choice.
+- A proposed fix would **change observable product behavior** for the end user (not just fix the internal bug).
+- You've **exhausted the Oracle Triple** and another 2 rounds failed after synthesis.
+
+## Do NOT ask when
+
+- You haven't tried the Oracle Triple yet.
+- The question can be answered by one more runtime query.
+- You're asking for permission to do the obvious thing.
+- You're asking because you're tired.
+
+---
+
+## Escalation format (paste into the reply)
+
+Keep it short. Evidence-dense. One decision, not a status update.
+
+```markdown
+## Decision needed
+
+**What we know** (verbatim evidence, not paraphrase):
+- <fact 1 with file:line or address>
+- <fact 2 with source>
+- <what the evidence rules IN>
+- <what the evidence rules OUT>
+
+**What the decision is** (one sentence):
+<the fork in the road>
+
+**Options**:
+
+| # | Fix | Scope | Risk | Effort |
+|---|-----|-------|------|--------|
+| A | <short label> | <files touched / layers> | <regressions possible> | <rough> |
+| B | ... | ... | ... | ... |
+| C | ... | ... | ... | ... |
+
+**Recommendation**: <A/B/C> because <one-sentence reason>.
+
+Which direction do you want?
+```
+
+---
+
+## Anti-patterns in escalation
+
+- **Asking without evidence.** "What do you want me to do?" is not an escalation, it's abandonment. Every escalation includes the evidence the user needs to decide.
+- **Two questions in one.** One decision per escalation. Multi-part questions lead to partial answers and re-escalation.
+- **Escalating before Phase 4.** If you haven't tried the Oracle Triple, you haven't earned the right to escalate.
+- **Presenting options you don't actually have.** If option C requires a library the user doesn't use, don't list it. The options are only things you can actually do today.
+- **Hiding a recommendation.** The user hired you to think — always end with a recommendation, even if you're low-confidence. Say so explicitly: "Recommendation (low confidence): B, because X. If you have context about Y that I don't, it might change to A."
+
+---
+
+## What happens after the user responds
+
+- **User picks an option**: return to Phase 6 (root cause confirmation) with the chosen direction. The user's choice is not itself confirmation — you still need runtime evidence that the cause you're fixing is the cause in play.
+- **User proposes a different option you hadn't considered**: treat it as new information. Update hypotheses. May trigger another Phase 3 round.
+- **User gives more context that resolves the disagreement**: skip to Phase 6.
+- **User is also unsure**: that's a signal you need more evidence, not more opinions. Run one more targeted query before asking again.

package/packages/shared-skills/skills/debugging/references/methodology/06-fix.md

@@ -0,0 +1,116 @@
+# Phase 6 + 7 — Root Cause Confirmation & TDD Fix
+
+A cause is not "confirmed" until you can toggle the bug by toggling the cause. Every other level of evidence is correlation, and correlation-driven fixes ship bugs.
+
+---
+
+## Phase 6 — Root Cause Confirmation
+
+You are allowed to call the cause "confirmed" only when ALL THREE of these hold:
+
+### 1. Captured runtime value matches the hypothesis exactly
+
+Not "the value looks consistent with" — the value is exactly the value the hypothesis predicted. If your hypothesis was "baseUrl is api.anthropic.com despite ANTHROPIC_BASE_URL being set to a proxy", the captured value is literally `"https://api.anthropic.com"` in the debugger at the moment of the HTTP call.
+
+### 2. Reproducible
+
+Running the repro a second time yields the same observation. Flaky repros mean you haven't isolated the cause; you've isolated a symptom that sometimes appears when the cause does. Keep investigating.
+
+### 3. Toggle proof (the one most skipped)
+
+**Changing the value** (via debugger assignment, env override, or a speculative one-line patch) **makes the bug disappear — and reverting brings the bug back**.
+
+If you can't toggle the bug by toggling the suspected cause, what you have is a correlation, not a mechanism. A correlation is a strong hypothesis, not a confirmed cause.
+
+Examples of a valid toggle proof:
+
+| Suspected cause | Toggle |
+|---|---|
+| Env var overrides library default, and the override is wrong | Unset the env var → bug goes away. Reset it → bug comes back. |
+| Async task is not awaited | Add `await` → bug goes away. Remove `await` → bug comes back. |
+| Third-party SDK uses hardcoded URL | Monkey-patch SDK to use env URL → bug goes away. Unpatch → bug comes back. |
+| Race condition on shared state | Add a mutex → bug goes away under load. Remove mutex → bug comes back under load. |
+
+If you can't construct a toggle proof, you haven't confirmed the cause. Run one more round.
+
+### Update the journal
+
+```markdown
+## Root cause (confirmed <ISO timestamp>)
+- Mechanism: <one paragraph, causal not correlational — the chain from cause to observable symptom>
+- Evidence: <file:line of captured value | path to saved repro | address + register state>
+- Toggle proof: "With <change X>, repro produces <good>. Reverting <change X>, repro produces <bad>."
+- Fix scope: <files and approximate line count>
+```
+
+The "mechanism" field is the acid test. If you can't write the causal chain from cause to observable symptom as one paragraph, you don't yet understand the bug well enough to fix it.
+
+---
+
+## Phase 7 — TDD Fix
+
+Red, green, refactor. No shortcuts.
+
+### 1. Red — failing-first test
+
+Write a test that fails *specifically because of this bug*. Requirements:
+
+- **Test name reads like a bug report.** `test_refinement_turn_returns_empty_content_when_anthropic_returns_401` is good. `test_bug_fix` is not.
+- **Failure message clearly shows what the bug looks like.** If someone reads only the failure output, they understand what's broken.
+- **Minimum infrastructure.** Don't spin up the whole server if a unit test against the right seam captures the mechanism.
+
+Run the test. Confirm it fails. Paste the failure output into the journal:
+
+```markdown
+### Red phase (<ISO timestamp>)
+Test: <path>::<name>
+Command: <exact invocation>
+Output:
+```
+<verbatim failure output>
+```
+Confirms: the bug is reproducible at the test-harness level, not just the manual repro.
+```
+
+### 2. Green — minimum change
+
+Make the test pass with the **smallest change that fully fixes the observed mechanism**.
+
+If the diff is larger than ~30 lines and you aren't refactoring, something is wrong — either you're fixing more than the bug, or the root cause was deeper than you confirmed. Back to Phase 6.
+
+Signs you're over-fixing:
+- Adding "just in case" null checks or try/except around other code
+- Refactoring adjacent functions because "while I'm here"
+- Adding new configuration options the bug didn't require
+- Introducing new abstractions to "make this cleaner"
+
+Resist all of these. Fix the bug. Note the surrounding issues for follow-up. Move on.
+
+### 3. Refactor — ONLY AFTER GREEN
+
+Only cleanup directly related to the fix. Do not re-architect.
+
+If the code around the fix is rough, note it in the journal as a follow-up for the user; do not expand scope here. Refactoring during a bugfix is how one-line fixes turn into hundred-line diffs nobody can review.
+
+### 4. Regression — full suite green
+
+Run the full test suite for the affected package (not just the one new test). Existing tests must still pass.
+
+If they don't, your "fix" broke something else. Back to Phase 6 with the new failure as evidence — usually it means the mechanism you thought you fixed was load-bearing for some other code path you didn't know about, and the "broken" test is actually pointing at a better understanding of the system.
+
+### Update the journal
+
+```markdown
+### Green phase (<ISO timestamp>)
+Fix: <file:line> — <two-line description of the change>
+Test: <path>::<name> now passes
+Full suite: <N tests, <M failures — should be 0>
+```
+
+---
+
+## The red-green discipline summary
+
+No red test → no proof the fix addresses the reported bug. Only proof it doesn't break tests that already existed.
+
+A test written *after* the fix might still pass with the fix reverted. If that's the case, the test doesn't lock the bug — it locks something else. Always verify the test fails without the fix and passes with it. The journal should show both outputs.

package/packages/shared-skills/skills/debugging/references/methodology/08-qa.md

@@ -0,0 +1,94 @@
+# Phase 8 — Manual QA by Actually Using It
+
+Tests cover cases you thought of. Real usage covers the ones you didn't.
+
+The single fastest way to ship a broken fix is to stop at "tests pass". Manual QA means interacting with the running system the way the user does, then comparing observed behavior to the original bug report.
+
+---
+
+## Product-type playbook
+
+Pick the row that matches the product. Do what it says. Do not substitute.
+
+| Product type | QA means… |
+|---|---|
+| **CLI tool** | Open `tmux`, run the actual command end-to-end, capture output. Paste the session transcript into the journal. Include exit code, stdout, stderr, side-effect check (files created/modified). |
+| **HTTP API** | Start the real server, hit endpoints with `curl` or `httpie`, inspect response status + body + headers. Hit the specific endpoint that reproduced the bug. If there's auth, use real auth. |
+| **Browser-served web app** | **Drive a real browser via Playwright CLI.** See [tools/playwright-cli.md](../tools/playwright-cli.md). Navigate the exact page/flow that reproduced the bug. Capture screenshot + DOM + network evidence. **Do not substitute with curl** — browsers have state (cookies, localStorage, service workers, client-side JS, viewport-dependent CSS) that curl does not have. |
+| **Agent / LLM pipeline** | Run the same user prompt that originally failed. Capture the full turn — tool calls, messages, usage counters. **Confirm non-zero usage** (zero usage = still failing silently, see silent-failure check below). |
+| **Background worker / job queue** | Trigger the job through the normal entry point (API call, cron tick, message publish), tail the worker logs, observe completion state in the queue or DB. Don't just call the worker function directly — the trigger path matters. |
+| **MCP server** | Invoke the tool via its actual client (Claude Desktop, Cursor, etc. if available) or `mcp-cli`, not just the HTTP probe endpoint. The MCP handshake itself is sometimes where bugs live. |
+| **Native binary** | Re-run the exact command that crashed / misbehaved. If the input was a file, use the same file. If the bug was exploitable, confirm the exploit repro via pwntools (see [tools/pwntools.md](../tools/pwntools.md)). Capture exit code, signal if any, core dump if generated. |
+| **Bundled-app binary** (Bun SEA, Node SEA, Electron, etc.) | Re-run the exact command. If the operation requires paid quota / blocked network, capture the **app's debug log** (`APP_DEBUG=1 APP_LOG_LEVEL=debug APP_LOG_FILE=/tmp/trace.log`) which usually emits the assembled request before sending. See [methodology/partial-runtime-evidence.md](partial-runtime-evidence.md) for combining partial signals into a defensible verification. |
+| **Long-running daemon** | Start fresh, let it run for the amount of time the bug originally took to manifest (not less), capture resource usage (memory, fd, cpu) throughout. Short-running QA misses resource leaks and cumulative state bugs. |
+
+---
+
+## Journal format
+
+Every QA run goes in the journal under "Findings":
+
+```markdown
+### Manual QA — <product type> (<ISO timestamp>)
+- Scenario: <one line describing what you did>
+- Command: `<exact invocation>`
+- Observed output:
+```
+<verbatim output, trimmed to relevant section>
+```
+- Expected output: <what correct behavior looks like>
+- Fix verified: yes / no / partial — <details>
+```
+
+If any QA step shows **partial or regressed behavior**, this is not "mostly done" — it's incomplete. Return to Phase 6.
+
+---
+
+## The silent-failure check (always run)
+
+Regardless of product type, audit the fix against these silent-failure patterns. If the original bug was a silent failure, the same pattern may exist in adjacent code that you haven't tested yet.
+
+### Universal silent-failure signals
+
+- HTTP 2xx with empty or default body
+- Response `ok: true` but a sub-field contains an error token (e.g. `stopReason: "error"`, `status: "failed"`)
+- `usage.totalTokens === 0` on an LLM response
+- Process exit code 0 but stderr contains an exception traceback
+- Panic recovered and logged but ignored
+- Goroutine / task / promise rejection with no top-level handler
+- `try { ... } catch { /* swallowed */ }` or `except: pass`
+- Success response shape but semantic field indicates failure (e.g. `error: null` actually being `error: "..."` with falsy check)
+- Write returned success but read-back shows stale data
+- Job marked complete but side-effect did not happen
+- Cache hit path returned stale data and no refresh was triggered
+
+### Language-specific silent-failure signals
+
+Check the runtime reference for additional patterns:
+
+- [runtimes/python.md](../runtimes/python.md) — asyncio task exceptions, bare `except`, `logging.exception` that goes nowhere
+- [runtimes/node.md](../runtimes/node.md) — unhandled promise rejections, `void` on async, swallowed `.catch(() => {})`
+- [runtimes/rust.md](../runtimes/rust.md) — `.unwrap_or_default()`, `let _ = result`, error variants discarded
+- [runtimes/go.md](../runtimes/go.md) — `if err != nil { return err }` that never reaches user output, recovered panics, buffered channels that block silently
+- [runtimes/native-binary.md](../runtimes/native-binary.md) — ignored return codes from libc, missing `perror`, `alarm()` / signal masks
+- [runtimes/bundled-js-binary.md](../runtimes/bundled-js-binary.md) — `process.env.X` baked at build time, dead code from tree-shaking failures, worker sub-bundles diverging from main bundle
+
+### What to do when you find another silent-failure spot
+
+Don't fix it. This is out of scope for the current bug.
+
+Note it in the journal under a "Follow-ups" section with:
+- File:line
+- Pattern matched
+- Proposed fix sketch (one line)
+- Risk level (what happens if left unfixed)
+
+Surface these to the user in the final message under "Next steps I didn't take".
+
+---
+
+## The "fix verified" bar
+
+"Fix verified" means: the exact original failing scenario, re-run, now produces the correct output. Not a similar scenario. Not a unit test of the fix. The original scenario.
+
+If you can't re-run the original scenario (e.g. it required a specific data state that's gone), construct the closest equivalent and document the difference in the journal. Escalate to the user if the equivalent is materially different.

package/packages/shared-skills/skills/debugging/references/methodology/09-cleanup.md

@@ -0,0 +1,164 @@
+# Phase 9 + 10 — Cleanup & Final Verification
+
+The working tree after the session must differ from before only by the real fix and its test. Anything else is a process failure.
+
+---
+
+## Phase 9 — Cleanup & Revert
+
+### The walk
+
+Open the journal's "Artifacts to revert" list. Walk it top to bottom. Check each box only after the revert command succeeds and produces no error.
+
+### Standard revert operations
+
+Most sessions create some combination of these artifacts. The commands below are the defaults — your journal should have the exact commands for this session.
+
+```bash
+# --- Temporary source edits (instrumentation statements, debug prints) ---
+git checkout <file>                              # reverts only that file
+git diff <file>                                  # verify clean
+
+# --- tmux sessions ---
+tmux kill-session -t <session-name>
+tmux ls                                          # confirm gone
+
+# --- Temp fixtures / scratch scripts ---
+rm -f /tmp/debug-*.*
+ls /tmp/debug-*.* 2>/dev/null                    # confirm gone (ls returns non-zero when no match)
+
+# --- Background processes (debugger-attached runtimes) ---
+pkill -f 'node --inspect' || true
+pkill -f 'python -m pdb' || true
+pkill -f 'debugpy' || true
+pkill -f 'dlv' || true
+pkill -f 'gdb' || true
+pkill -f 'lldb' || true
+
+# --- Debug-relevant ports confirmed free ---
+lsof -iTCP:9229 -sTCP:LISTEN -nP 2>/dev/null     # Node inspector default
+lsof -iTCP:5678 -sTCP:LISTEN -nP 2>/dev/null     # debugpy default
+lsof -iTCP:2345 -sTCP:LISTEN -nP 2>/dev/null     # dlv default
+lsof -iTCP:9999 -sTCP:LISTEN -nP 2>/dev/null     # pwndbg/gdb-server default
+
+# --- Env var overrides in current shell ---
+unset DEBUG_OVERRIDE_FOO
+unset PYTHONBREAKPOINT
+unset RUST_LOG
+unset DEBUG
+
+# --- Ghidra scratch projects (if created just for this session) ---
+# rm -rf ~/ghidra-projects/debug-scratch
+
+# --- Core dumps from debugging (if any) ---
+rm -f ./core ./core.* ~/core.*
+
+# --- Playwright trace files ---
+rm -rf playwright-report/ test-results/
+```
+
+### The verify command
+
+This is the single most important check of the whole skill:
+
+```bash
+git status
+git diff --stat
+```
+
+The diff must contain **only**:
+
+1. The real fix.
+2. The new failing-first test.
+3. Nothing else.
+
+### Detector checklist — scan the diff for these
+
+If `git status` shows any untracked debug file, or `git diff` shows any of the patterns below, **you are not done**. Clean it.
+
+| Pattern | Usually means |
+|---|---|
+| `debugger;` | Node debug statement left behind |
+| `breakpoint()` | Python debug statement left behind |
+| `dbg!(...)` | Rust debug macro left behind |
+| `fmt.Println("DEBUG: ...")` | Go ad-hoc print |
+| `console.log("[DEBUG]` | Node ad-hoc log |
+| `print(f"DEBUG: ` | Python ad-hoc print |
+| `// TODO DEBUG`, `// HACK`, `// XXX` | Stale debug marker |
+| `// <PROJECT>-DEBUG` | Session-specific marker from this skill's edits |
+| Commented-out code blocks near the fix | Dead code from trial fixes |
+| Reordered imports or formatting in unrelated files | Drift from your editor's autoformat during the session |
+
+### Remove the journal
+
+Only once the git check is clean:
+
+```bash
+rm .debug-journal.md
+sed -i.bak '/^\.debug-journal\.md$/d' .git/info/exclude && rm -f .git/info/exclude.bak
+```
+
+The journal is not part of the fix; it doesn't belong in the commit or in the git exclude list.
+
+---
+
+## Phase 10 — Final Verification
+
+Last gate before reporting done. All four gates must be true, and all four must have **evidence in your final message** to the user. Passing a gate without evidence is the same as failing it.
+
+### The four gates
+
+1. **Red→green toggle confirmed** — show the failing test output from before the fix and passing output after. Both outputs visible in the reply or the journal.
+
+2. **Full test suite green** — show the suite's final pass line (e.g. `42 passed in 3.14s`). Not just the new test.
+
+3. **Manual QA reproduced the fix** — show the command or scenario that originally failed and its now-correct output. Verbatim, not paraphrased.
+
+4. **Working tree clean of debug artifacts** — show `git diff --stat` output containing only fix + test, plus `git status` clean of untracked debug files.
+
+If any of the four lacks evidence, you have not finished — return to the appropriate phase.
+
+### Final message template
+
+Keep it short. Evidence-dense. The user should be able to skim it in 30 seconds.
+
+```markdown
+Fixed.
+
+**Root cause**: <one sentence — the mechanism, not the symptom>
+**Fix**: `<file:line>` — <two words>
+**Test**: `<test file>::<test name>` — red without fix, green with fix
+**QA**: <one line describing what you ran and what you saw>
+
+Diff:
+```
+<git diff --stat output — should be tiny>
+```
+
+**Next steps I didn't take** (awaiting your decision):
+- <follow-up 1, if any — from QA silent-failure scan or refactor opportunities noted during Phase 7>
+- <follow-up 2 — or "none" if nothing else surfaced>
+```
+
+### Example (from a real session)
+
+```markdown
+Fixed.
+
+**Root cause**: pi-mono Agent's `model.baseUrl` was hardcoded to `api.anthropic.com`, so the `ANTHROPIC_BASE_URL` env var was silently ignored. The proxy API key was rejected by the real Anthropic API with 401, but pi-mono packaged the error into the assistant message's `errorMessage` field instead of throwing, so the route's try/catch never fired and the client received HTTP 200 with empty content.
+
+**Fix**: `core/pi-bridge/modelResolver.ts:117` — override baseUrl
+**Test**: `__tests__/core/modelResolver.test.ts::resolves_env_override` — red without fix, green with fix
+**QA**: `curl -X POST /api/refinement/chat` with proxy env set, observed non-zero usage and non-empty content
+
+Diff:
+```
+ core/pi-bridge/modelResolver.ts              | 3 +++
+ __tests__/core/modelResolver.test.ts         | 42 ++++++++++++++++++++++
+ 2 files changed, 45 insertions(+)
+```
+
+**Next steps I didn't take** (awaiting your decision):
+- pi-mono itself silently swallows LLM errors into `errorMessage`; adding a throw-on-error wrapper at our orchestrator layer would surface these upstream
+- Same silent-failure pattern exists in the planning route — likely the same fix applies
+```