@jakkrichm/create-nexus-devflow 2.2.2 → 2.6.0

package/template/.claude/skills/check/SKILL.md

@@ -1,108 +1,111 @@
 ---
 name: check
-description: "[devflow][F] Prove the current work actually does what its spec says by running the real app and observing behavior against the \"done when\" criteria in current-feature.md. Drives the app (browser, CLI, or server), captures evidence (screenshots, output, console/network errors), and reports pass/fail per criterion. Does not edit source or commit - it observes; fixing stays /implement's job. Use when the user runs /check, asks to confirm a step or feature works, wants proof before /complete, or wants to check a change in the running app rather than just the build. (Supersedes the built-in /verify with a spec-aware version inside blueprint projects.)"
+description: "[devflow][F] Prove the current work actually does what its spec says and adheres to architectural standards through a Dual-Axis Independent Review (Spec Fidelity + Standards & Architecture). Drives the app (browser, CLI, or server), captures empirical evidence (screenshots, output, console/network errors), checks against 12 Fowler smells and deep-module standards, and reports pass/fail. Does not edit source or commit - it observes; fixing stays /implement's job. Use when the user runs /check, asks to confirm a step or feature works, wants proof before /complete, or wants to check a change in the running app rather than just the build."
 ---
 
-# check - prove it works against the spec, with evidence
+# check - Dual-Axis Independent Verification Engine
 
 Where this sits in the workflow:
 
     /implement  ->  [check]  ->  /complete
-    (built a       (run the app,    (only once the
-     step or        prove each       done-whens are
-     the feature)   done-when)       proven)
+    (built a       (dual-axis       (only once both
+     step or        review with      axes pass with
+     the feature)   empirical proof) evidence)
 
-`/implement` builds and does a quick build-plus-screenshot check inline. `/check`
-is the deeper, repeatable gate for when a "done when" needs the *real running app*,
-not just a green build: a click that triggers a download, a route that returns a
-file, a flow across screens. Run it on a single step whose done-when is
-behavioral, or on the whole feature as the acceptance check before `/complete`.
+`/implement` builds and does a quick build-plus-screenshot check inline. `/check` is the rigorous, repeatable gate for when a feature or step needs **empirical proof** on the running app and **two-axis code review** before merging.
 
-The point is evidence. A passing build proves the code compiles; `/check` proves
-the thing the spec promised actually happens. It changes no source and commits
-nothing - it runs the app and reports what it saw.
+It changes no source and commits nothing — it executes, inspects, and reports observed facts.
+
+---
 
 ## Input
 
-Optional: a specific thing to check (a step, a flow, a URL). With no argument,
-verify the whole current feature against every "done when" in
-`devflow/context/current-feature.md`.
+Optional: a specific target to check (a step, a flow, a URL). With no argument, verify the whole current feature against `devflow/context/current-feature.md` and `devflow/context/coding-standards.md`.
 
-## Step 1 - build the checklist
+---
 
-Read `devflow/context/current-feature.md`. Pull the observable "done when"
-criteria from the build steps (and any acceptance notes in the Testing section).
-Turn them into a concrete checklist of claims to prove - each one a specific,
-observable behavior, not "it works". If the user named one thing, scope to that.
+## Step 1 - Build the Dual-Axis Review Matrix
 
-If there's no current feature spec, ask what to verify rather than guessing.
+Read `devflow/context/current-feature.md` and `devflow/context/coding-standards.md`. Prepare the inspection criteria across two independent axes:
 
-## Step 2 - get the app running
+1. **Axis 1 (Standards & Architecture Criteria)**:
+   - Coding conventions in `coding-standards.md`
+   - Deep Modules discipline (Small interface, deep implementation, clean seams, no leaky abstractions)
+   - Baseline 12 Fowler Code Smells (Primitive obsession, Feature envy, Shotgun surgery, Speculative generality, etc.)
+   - Multi-lane technical gates (Typecheck, test suites, zero secrets, zero P0/P1 findings)
+2. **Axis 2 (Spec Fidelity & Behavioral Observables)**:
+   - Line-by-line Acceptance Criteria (ACs) and "Done When" observables from `current-feature.md`
+   - Scope Creep detection (Unrequested behavior in the diff)
+   - Missing Requirements detection (Unimplemented edge cases)
 
-Use the project's real commands (see Commands in `AGENTS.md`). Match the project
-type:
+---
 
-- **Web app** - start (or reuse) the dev/preview server, then drive a real browser
-  to the relevant routes. Prefer reusing an already-running server over starting a
-  duplicate. If Playwright is already installed or declared in `AGENTS.md`, prefer
-  it for browser driving, screenshots, console errors, and failed request checks.
-  If it is not installed, do not add it from `/check`; use another real-browser
-  evidence path and report what you used.
-- **CLI** - run the actual command(s) with representative inputs.
-- **Server/API** - start it and hit the endpoints.
-- **Library** - exercise the public API through an example or the test command.
+## Step 2 - Get the App Running & Exercise Live Proof
 
-If a `test` command is declared in `AGENTS.md`, you may run it as *one* input, but
-`/check` is broader than unit tests: it checks real behavior, which is exactly the
-evidence UI and integration steps ride on instead of unit tests.
+Use the project's real commands (from `AGENTS.md`):
 
-## Step 3 - exercise each claim
+- **Web app**: Start (or reuse) the local dev server. Drive a real browser to relevant routes. Prefer Playwright when installed for screenshots, network errors, and console assertions.
+- **CLI**: Execute commands with representative input fixtures, asserting exit codes and output snapshots.
+- **Server / API**: Hit endpoints with real payloads and assert on HTTP response status and bodies.
+- **Library**: Exercise public interfaces through integration tests or sample scripts.
 
-Drive the app to each checklist item and capture evidence as you go:
+> [!IMPORTANT]
+> **Evidence or it didn't happen**: Every verdict must be backed by empirical evidence (screenshot, command output, status code, response time). Never assume a pass from reading source code alone.
 
-- Navigate and interact for real (click, type, submit, download) - don't assert
-  from the code what the running app would do.
-- Capture **screenshots** for visual/UI claims, **output** for CLI/API claims.
-- Watch for **console errors and failed network requests**; a clean-looking screen
-  with errors in the console is not a pass.
+---
 
-## Step 4 - report (Two-Stage Review Pattern)
+## Step 3 - Dual-Axis Independent Report
 
-Format the verification report into two explicit review stages:
+Format the report into two distinct, un-merged review axes:
 
-### Stage 1: Spec Fidelity & Acceptance Gate
-Give a line-by-line verdict for each Acceptance Criterion and "done when" item:
+```markdown
+# 🔍 Verification Report: [Feature Name]
 
-    [pass] AC-1: Download PDF saves certificate-<slug>.pdf - file downloaded, opened to cert
-    [pass] AC-2: Both buttons show a loading state - screenshot: loading-state.png
-    [fail] AC-3: PDF border missing - printBackground not set; screenshot: pdf-no-border.png
-    [skip] AC-4: Vercel deploy smoke test - can't verify locally (pending staging)
+## ⚖️ Axis 1: Standards, Architecture & Quality Gate
 
-### Stage 2: Code Quality, Security & Architecture Gate
-Report the multi-lane technical verification results:
-- **Type & Syntax**: `tsc --noEmit` (0 errors)
-- **Automated Tests**: Unit & integration tests (100% pass)
-- **Security & Hygiene**: Zero secrets, sanitized inputs
-- **Findings Ledger**: 0 blockers (P0/P1) in `devflow/context/findings.md`
+- **Technical Lanes**:
+  - [pass] Type Safety: `tsc --noEmit` (0 errors)
+  - [pass] Automated Tests: `npm test` (All tests green)
+  - [pass] Security & Hygiene: Zero secrets, sanitized inputs
+  - [pass] Findings Ledger: 0 blocking P0/P1 in `devflow/context/findings.md`
+- **Deep Modules & Architecture**:
+  - [pass] Seam Integrity: Public interfaces remain small, implementation details hidden.
+  - [pass] The Deletion Test: Complexity is concentrated inside the module, not scattered across callers.
+- **Code Smells Assessment**:
+  - [clean] 12 Fowler Code Smells evaluated across git diff: No critical smells detected.
 
-### Final Verdict & Route
-- **All Passed**: State that the feature is verified and ready for `/complete`.
-- **Any Failure**: Hand back to `/implement` with exact failure evidence and reproduction steps. Never fix issues inside `/check`.
-- **Unverifiable**: Clearly state reasons and residual risk. Never fabricate a pass.
+## 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
 
-## Rules
+Line-by-line verification against `current-feature.md`:
+- [pass] **AC-1 (<title>)**: <Observed empirical evidence / screenshot path>
+- [pass] **AC-2 (<title>)**: <Observed empirical evidence / terminal output>
+- [fail] **AC-3 (<title>)**: <Exact observed failure with reproduction command>
+- [clean] **Scope Creep Check**: No unrequested features or unnecessary abstractions introduced.
+- [clean] **Completeness Check**: 100% of spec requirements addressed.
+
+---
+
+## 🚦 Final Routing & Verdict
 
-- **Observe, don't change.** `/check` runs the app and reports. It never edits
-  source, never commits, never merges. Fixing is `/implement`'s job.
-- **Evidence or it didn't happen.** Every `pass` is backed by something observed -
-  a screenshot, output, a response. No assumed passes from reading the code.
-- **Honest over green.** "Couldn't verify" and "failed" are valid, useful results.
-  Faking a pass defeats the entire gate.
-- **Check the spec, not vibes.** Verify against the done-whens in
-  `current-feature.md`, so "works" means what the spec said it would do.
+- **ALL PASSED**: Both axes green. Ready for `/complete`.
+- **ANY FAILURE**: Hand back to `/implement` with exact failure evidence and reproduction steps.
+- **UNVERIFIABLE**: Clearly document the gap and residual risk. Never fabricate a pass.
+```
 
-## Formatting
+---
+
+## Why Two Independent Axes?
+
+A code change can pass one axis and fail the other:
+- **Standards Pass, Spec Fail**: Code is beautifully architected and tested, but implements the wrong business behavior.
+- **Spec Pass, Standards Fail**: Feature works end-to-end, but violates encapsulation, introduces shallow modules, or leaks secrets.
+
+Reporting both axes side-by-side stops elegance from masking functional bugs, and stops functional completeness from excusing architectural rot.
+
+---
+
+## Rules
 
-Format the output to match the project's conventions in
-`devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
-enumerations and tables for matrices rather than dense paragraphs.
+- **Observe, don't change**: `/check` runs the app and reports. It never edits source or commits. Fixing is `/implement`'s job.
+- **Honest over green**: "Failed" and "Could not verify" are valid, valuable outputs. Faking a pass destroys the gate.
+- **Check the spec, not vibes**: Verify against documented ACs, not subjective feelings.

package/template/.claude/skills/complete/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: complete
-description: "[devflow][F] Wrap up a finished feature, fix, or rollback. Runs a final safety pass, archives its spec to devflow/history/features/, devflow/history/fixes/, or devflow/history/rollbacks/, updates the build plan for features and rollbacks, resets devflow/context/current-feature.md to its stub, makes one work-level commit, then squash-merges the branch to main and deletes it. Merges only with explicit approval, then asks separately before pushing main. Use when the user runs /complete, or asks to finish, wrap up, merge, or close out the current feature, fix, or rollback after it is built and reviewed."
+description: "[devflow][F] Wrap up a finished feature, fix, or rollback. Runs a final safety pass, archives its spec to devflow/history/features/, devflow/history/fixes/, or devflow/history/rollbacks/, updates the build plan for features and rollbacks, resets devflow/context/current-feature.md to its stub, and makes the work commit. Enforces a mandatory user gate: asks whether to squash-merge to main/master OR pull latest main/master into the feature/dev branch and push to remote for Merge Request (MR / PR) creation. Never merges into main/master without explicit user instruction."
 ---
 
-# complete - log the finished work, make the work commit, and merge
+# complete - log the finished work, make the work commit, and deliver
 
 Where this sits in the workflow:
 
     /feature, /fix, or /rollback  ->  /implement  ->  [complete]  ->  next
-    (the spec)                         (build it)      (commit + merge + log)
+    (the spec)                         (build it)      (commit + delivery gate)
 
 `/implement` built the feature, fix, or rollback on its branch, with optional per-step commit
 checkpoints. This skill closes it out: it logs the work, makes the single
-work-level commit, and squash-merges. Run it only when the work is done,
+work-level commit, and guides the delivery through a **Mandatory User Delivery Gate**. Run it only when the work is done,
 reviewed, and the documented `Verify` command, or the fallback build and tests,
 passes.
 
@@ -22,7 +22,7 @@ Confirm the work is actually finished: `devflow/context/current-feature.md`
 holds a real spec, its steps are built on a branch, and `Verify`, or the fallback
 build and tests, passes. If any of the
 spec's done-whens are behavioral, `/check` should have proven them against the
-running app first - don't merge on an unverified claim. Uncommitted step work is
+running app first - don't merge or complete on an unverified claim. Uncommitted step work is
 expected (per-step checkpoints are optional); this skill commits it. Don't require
 the steps to be pre-committed.
 
@@ -30,7 +30,7 @@ the steps to be pre-committed.
 
 Before logging or committing, run a short safety pass and report blockers only:
 
-- active spec exists and the work is not being completed from `main` or `master`
+- active spec exists and the work is not being completed directly from `main` or `master`
 - changed files are tied to the active spec, with no unrelated dirty work mixed
   in (a dirty `devflow/context/findings.md` is expected, since `/audit` writes it)
 - the exact `Verify` command from `AGENTS.md` passed in this session, when one is
@@ -107,25 +107,47 @@ into the app - delete the `prototypes/` folder now. The tokens live in the real
 stylesheet and the HTML mockups were always throwaway; fold the deletion into this
 feature's commit. Skip this if the feature didn't consume prototypes.
 
-## Step 2 - make the work commit
+## Step 2 - make the work commit on feature branch
 
 Stage everything on the branch (any uncommitted step work plus the Step 1 logging
-changes) and make one conventional work commit (for example `feat: <feature>`,
+changes) and make one conventional work commit on the active branch (for example `feat: <feature>`,
 `fix: <name>`, or `revert: roll back <feature>`). `Verify`, or the fallback build
 and tests, must pass first.
 
-## Step 3 - merge
+## Step 3 - Mandatory Delivery Gate (Ask User First)
+
+> [!IMPORTANT]
+> **MANDATORY USER SELECTION**: In real-world engineering teams, developers often do NOT have direct merge/push access to `main` or `master` (protected branches).
+> Therefore, you **MUST STOP AND ASK** the user to choose their desired delivery flow. **NEVER automatically merge into `main` or `master` without explicit user choice.**
+
+Present the user with two clear delivery options:
+
+### 🔀 Option 1: Team MR / PR Flow (Pull latest main/master & Push dev branch) [Default for Teams]
+- **When to choose**: When working in a team where code reviews happen via GitLab Merge Request (MR) or GitHub Pull Request (PR), or where developers lack direct write access to protected `main`/`master` branches.
+- **Execution Actions**:
+  1. Detect default base branch name (`main` or `master`).
+  2. Run `git pull origin <main/master>` (or `git fetch origin <main/master> && git merge origin/<main/master>`) to bring the latest upstream changes into the active feature/dev branch.
+  3. If merge conflicts occur, highlight them clearly and help the user resolve them.
+  4. Run `Verify` (or build & tests) to ensure integrity after the merge.
+  5. Run `git push origin <current-feature-branch>` to push the up-to-date branch to the remote repository.
+  6. Stop and inform the user that the branch is synchronized and pushed, ready for them to open a Merge Request (MR / PR) on GitLab/GitHub.
+  7. **Do NOT merge into local `main`/`master` and do NOT delete the branch.**
+
+### 🔀 Option 2: Direct Local Squash-Merge (Solo / Direct Access Mode)
+- **When to choose**: Only when the user explicitly instructs that they want to merge directly into `main` or `master` locally now (e.g. solo projects or Tech Leads with merge privileges).
+- **Execution Actions**:
+  1. Switch to `main` or `master`: `git checkout <main/master>`.
+  2. Squash-merge the branch: `git merge --squash <feature-branch>`.
+  3. Commit the squash-merge.
+  4. Delete the local feature branch only with the user's explicit consent.
+  5. **Stop and ask separately** before pushing local `main`/`master` to remote upstream. The merge approval does NOT count as push approval.
+  6. Run `git push origin <main/master>` only after separate explicit confirmation.
 
-1. Squash-merge the branch into main, only with the user's explicit go-ahead, so
-   the feature lands as one clean commit regardless of how many checkpoints the
-   branch carried.
-2. Delete the branch after a clean merge.
-3. Stop and ask whether to push local `main` to its upstream. The merge approval
-   does not count as push approval.
-4. Push main only after a separate explicit yes to push main in the current chat.
-   If the repo has no remote or upstream, say so instead of guessing.
+---
+
+## Step 4 - Finish & Try Path
 
-Then point the user at `/feature`, `/fix`, or `/rollback` for the next thing.
+Point the user at `/feature`, `/fix`, or `/rollback` for the next task.
 
 Finish with a concise **How to try it** note for the completed work. For a
 rollback, explain how to confirm the removed behavior is gone and name one
@@ -135,26 +157,15 @@ that command can read the archived feature after `current-feature.md` is reset.
 
 ## Rules
 
+- **Mandatory User Confirmation Gate**: Always ask before choosing between Team MR/PR Push vs Direct Squash-Merge.
+- **Never auto-merge into main/master**: The decision to merge into `main` or `master` belongs strictly to the user.
 - The work item is the unit of history: one squashed feature, fix, or rollback
-  commit on main, even if the branch carried several checkpoint commits.
+  commit, even if the branch carried several checkpoint commits.
 - A rollback preserves the original feature archive and adds a separate rollback
   archive. Never rewrite history to make the feature look as if it never existed.
-- Don't merge unfinished or failing work. The documented `Verify` command, or
+- Don't merge or push unfinished or failing work. The documented `Verify` command, or
   the fallback build and tests, must pass first.
-- Never merge while a P0 or P1 finding is `open` or `fixed` in the ledger. The
-  recorded ways past the gate without code are `accepted` (only by the user's
-  explicit decision, with their reason) or `invalid` (only from re-examination
-  evidence or the user's explicit call); both travel into the archive, never a
-  silent drop.
-- Merging and pushing are the user's calls: get an explicit yes for the merge,
-  then ask whether to push main. Do not treat merge approval, `/complete`, or
-  "looks good" as permission to push.
-- Push main only after a separate explicit yes to push main in the current chat.
+- Never merge or push while a P0 or P1 finding is `open` or `fixed` in the ledger.
+- Pushing to remote is always explicit: confirm before running `git push`.
 - One item per completion. If a parent feature still has unchecked sub-features,
-  leave the parent unchecked.
-
-## Formatting
-
-Format the output to match the project's conventions in
-`devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
-enumerations and tables for matrices rather than dense paragraphs.
+  leave the parent unchecked.

package/template/.claude/skills/debug/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: debug
-description: "[devflow][B] Diagnose a failing test, broken build, crash, error, regression, or unexpected behavior without editing source or Blueprint state. Reproduces the symptom with the smallest safe command, localizes the failing path, tests competing hypotheses, identifies the root cause when evidence supports one, and reports a repair handoff to /fix or /implement. Use when the user runs /debug, invokes $debug, asks why something is failing or broken, wants a root-cause investigation, or asks to diagnose before fixing."
+description: "[devflow][B] Diagnose a failing test, broken build, crash, error, regression, or unexpected behavior without editing source or DevFlow state. Follows a strict 6-Phase Scientific Debugging Loop: builds a red-capable tight feedback loop, reproduces & minimises, tests 3-5 falsifiable hypotheses, localizes the failure to a root cause, and reports a repair handoff to /fix or /implement. Use when the user runs /debug, invokes $debug, asks why something is failing or broken, wants a root-cause investigation, or asks to diagnose before fixing."
 ---
 
-# debug - find the cause before changing the code
+# debug - 6-Phase Scientific Debugging Protocol
 
 Where this sits in the workflow:
 
@@ -12,130 +12,112 @@ Where this sits in the workflow:
      crash, behavior)       isolate,       repair active work)
                             explain)
 
-`/debug` separates diagnosis from repair. It gathers evidence, narrows the
-failure to a specific cause when possible, and stops with a useful handoff. It
-does not make the code "temporarily work" while investigating.
+`/debug` separates diagnosis from repair. It gathers empirical evidence, narrows the failure to a specific root cause using scientific method, and stops with an actionable repair handoff. It does not guess, assume, or perform ad-hoc "vibe debugging".
+
+---
 
 ## Input
 
 Accept a symptom, failing command, error message, or unexpected behavior. Examples:
 
-    /debug npm test fails in cart-total.test.js
+    /debug npm test fails in cart-total.test.ts
     /debug the upload route returns 500 for PNG files
-    /debug why does the production build fail?
+    /debug why does the build fail on Windows?
 
-With no useful symptom, ask for the expected behavior, actual behavior, and
-smallest known reproduction. Do not guess which problem the user means.
+With no useful symptom, ask for expected behavior, actual behavior, and smallest known reproduction. Do not guess.
 
-## Step 1 - establish the boundary
+---
 
-Read the project instructions and the context relevant to the failure:
+## 🔬 The 6-Phase Scientific Debugging Loop
 
-- `AGENTS.md` and its real commands
-- `devflow/context/project-overview.md`
-- `devflow/context/coding-standards.md`
-- `devflow/context/current-feature.md`
-- the reported error, failing output, and affected files
-- git status, diff, and recent log when a regression is possible
+### Phase 1: Build a Red-Capable Feedback Loop (Golden Rule)
 
-State the symptom and what would count as reproducing it. Note whether the
-failure belongs to an active feature or is an unplanned bug.
+**This is the core discipline.** If you have a **tight** pass/fail command that actively goes RED on this bug, you will find the root cause. If you do not have one, staring at code will not save you.
 
-Do not treat a dirty working tree as permission to discard or rewrite anything.
-Use the diff as evidence and preserve it.
+**Spend disproportionate effort here. Ways to construct one (in order):**
+1. **Failing Unit / Integration Test** at the responsible module seam.
+2. **Curl / HTTP script** against the running local dev server.
+3. **CLI invocation** diffing stdout/stderr against expected output.
+4. **Headless browser script** (Playwright) asserting on DOM/network/console.
+5. **Replay captured trace**: Replay isolated payload/event log through the code path.
 
-## Step 2 - reproduce safely
+**Completion Criterion for Phase 1**:
+You must name **one single command** (a test invocation, a script, or curl) that you have **already run at least once** and proven:
+- [ ] **Red-capable**: It exercises the actual code path and catches the user's exact symptom (fails red now, will pass green once fixed).
+- [ ] **Deterministic**: Returns the same verdict every run.
+- [ ] **Fast & Agent-runnable**: Completes in seconds, executable without manual intervention.
 
-Run the smallest existing command or interaction that can reproduce the symptom.
+> [!CAUTION]
+> **No Red-Capable Command = No Phase 2.** If you catch yourself reading code to form theories before this command exists, **STOP**. Jumping straight to a hypothesis is the exact failure this protocol prevents.
 
-- Prefer one focused test, request, CLI command, or input over the entire suite.
-- Capture the exact exit code, error, stack trace, output, response, console
-  error, or failed request.
-- Reuse an already-running local app when available. If reproduction requires a
-  long-running server that is not running, ask the user to start it and provide
-  the documented command.
-- Do not install dependencies, change configuration, run migrations, mutate
-  production data, contact external users, or use destructive commands to force
-  a reproduction.
-- Do not edit code to add logs or probes. Use existing logs, debuggers,
-  read-only inspection, or one-off commands that do not change project files.
-- Compare git status after diagnostic commands. If one changes tracked or
-  untracked project files, stop and report those paths. Do not clean, restore,
-  or hide the changes.
+---
 
-If the symptom cannot be reproduced, say what was attempted and what evidence is
-missing. Continue with static investigation only when it can produce a clearly
-labeled hypothesis, not a claimed root cause.
+### Phase 2: Reproduce & Minimise
 
-## Step 3 - localize the failure
+Run the feedback loop and watch it go RED.
 
-Trace from the observed failure toward the smallest responsible area.
+1. **Confirm Symptom**: Ensure the failure mode matches what the user reported (not a nearby unrelated error).
+2. **Minimise the Repro**: Cut inputs, configs, dependencies, and steps **one at a time**, re-running the command after each cut. Keep only what is load-bearing for the failure.
+3. **Done when**: Every remaining parameter is load-bearing (removing any one makes the loop go green).
 
-Use the evidence that fits the project:
+---
 
-- the first relevant application frame in a stack trace
-- the smallest failing test and its inputs
-- request and response data at the failing boundary
-- console and network errors
-- callers, imports, data flow, and configuration reads
-- `git diff`, `git log`, and `git blame` for a suspected regression
-- comparison with a nearby working path or input
+### Phase 3: Form 3–5 Ranked Falsifiable Hypotheses
 
-Separate facts from hypotheses. Test the cheapest safe competing explanations
-first. Do not stop at the first plausible line, blame a dependency without
-evidence, or confuse the place an error surfaced with the place it originated.
+Generate **3 to 5 ranked hypotheses** before testing or inspecting deeply. Never anchor on the first plausible idea.
 
-## Step 4 - confirm or narrow
+Every hypothesis MUST be **falsifiable** using this exact format:
+> *"If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."*
 
-A root cause is confirmed only when the evidence connects all three:
+If you cannot state the prediction, it is a vibe: sharpen or discard it.
 
-1. the triggering input or state
-2. the responsible code, configuration, or contract
-3. the observed failure
+---
 
-When safe and read-only, vary one input or run a smaller focused command to
-confirm the connection. Do not change implementation or tests to prove the fix.
+### Phase 4: Targeted Instrumentation & Isolation
 
-Use one of these verdicts:
+Test hypotheses by changing **one variable at a time**:
+1. **Tool preference**: Read-only inspection > REPL/debugger > Targeted probe logs.
+2. **Debug Tag Rule**: If temporary diagnostic logs are necessary, tag every log line with a unique prefix, e.g. `[DEBUG-a4f2]`. This guarantees a single `grep` can find and remove all probes.
+3. **Redaction**: Redact all secrets, tokens, and credentials in terminal outputs (`<REDACTED>`).
 
-- **Confirmed** - evidence identifies the cause and explains the failure.
-- **Likely** - evidence narrows the cause, but one specific proof is unavailable.
-- **Blocked** - the failure cannot be reproduced or required evidence is
-  inaccessible.
+---
 
-## Step 5 - report and hand off
+### Phase 5: Confirm Root Cause at Real Seam
 
-Give a concise debug report:
+A root cause is **Confirmed** only when empirical evidence connects all three:
+1. The triggering input or state
+2. The responsible code / configuration boundary
+3. The observed failure
 
-- symptom and reproduction
-- verdict
-- root cause or leading hypothesis
-- evidence, including commands and relevant paths
-- affected behavior and likely repair boundary
-- what was not verified
-- exact next action
+**Seam Identification**: Identify the exact architectural seam (per `devflow/context/coding-standards.md` Deep Modules) where the regression test must live. If no clean seam exists, note that as an architectural finding.
 
-Choose the next action without writing files:
+---
+
+### Phase 6: Report & Hand-off
+
+Give a structured, concise debug report:
 
-- Active feature or fix caused the failure -> return the diagnosis to `/implement` with instructions to write a failing reproduction test ([TDD-Red]) first.
-- No active work item and the bug is confirmed -> recommend `/fix "<concise bug and confirmed cause>"` (which will write a failing test first before fixing).
-- Cause is only likely or blocked -> recommend the next diagnostic evidence, not a speculative repair.
-- The issue is planned product work rather than a defect -> point to `/feature`.
+```markdown
+### 🐞 Debug Report: <Concise Title>
+
+- **Symptom**: <Exact user symptom observed>
+- **Reproduction Command**: `<Single red-capable command>`
+- **Verdict**: Confirmed | Likely | Blocked
+- **Root Cause**: <Precise technical explanation of why it failed>
+- **Responsible Seam**: `<path/to/file.ts#line>`
+- **Evidence**:
+  - Test/Curl output confirming the red signal
+  - Trace connecting triggering state to failure
+- **Next Action**:
+  - For active feature -> Hand back to `/implement` with instructions to write failing test first.
+  - For standalone bug -> Recommend `/fix "<concise description>"` to create spec and implement regression test.
+```
+
+---
 
 ## Rules
 
-- Diagnose, do not repair. Never edit source, tests, configuration, lockfiles, or
-  Blueprint files.
-- Never create, switch, merge, or delete branches. Never commit or push.
-- Do not update the findings ledger. `/audit` owns recorded code-quality
-  findings; `/debug` reports one investigated failure in chat.
-- Evidence outranks confidence. Label uncertainty and failed reproduction
-  honestly.
-- Preserve the user's working tree and running processes.
-- Do not broaden one failure into a general audit or refactor.
-
-## Formatting
-
-Format the output to match the project's conventions in
-`devflow/context/ai-interaction.md`: concise, scannable markdown with a short
-evidence list and a clear next action.
+- **Diagnose, do not repair**: Never edit production source, package lockfiles, or DevFlow state inside `/debug`.
+- **Evidence outranks confidence**: Label uncertainty honestly (`Likely` vs `Confirmed`).
+- **Preserve git state**: Never switch branches, commit, reset, or clean the working tree.
+- **Clean up probes**: Ensure any temporary test scripts in scratch/ are cleanly referenced.