@brunosps00/dev-workflow 1.0.1 → 1.0.4

package/lib/prompts.js

@@ -33,4 +33,41 @@ async function selectLanguage(flagLang) {
   return lang;
 }
 
-module.exports = { selectLanguage, question };
+// Multi-select prompt. Accepts comma-separated indexes ("1,3,5"), "all" for every
+// option, or a single index. Returns an array of selected option strings.
+// Invalid or empty input falls back to the first option.
+function multiSelect(prompt, options) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    const optionsStr = options.map((o, i) => `  ${i + 1}) ${o}`).join('\n');
+    const help = `\n  Enter numbers separated by commas (e.g. 1,3,5) or "all" for everything.`;
+    rl.question(`\n${prompt}\n${optionsStr}${help}\n\n  Choose: `, (answer) => {
+      rl.close();
+      const trimmed = (answer || '').trim().toLowerCase();
+      if (!trimmed) {
+        resolve([options[0]]);
+        return;
+      }
+      if (trimmed === 'all') {
+        resolve(options.slice());
+        return;
+      }
+      const seen = new Set();
+      const selected = [];
+      for (const part of trimmed.split(',')) {
+        const idx = parseInt(part.trim(), 10) - 1;
+        if (idx >= 0 && idx < options.length && !seen.has(idx)) {
+          seen.add(idx);
+          selected.push(options[idx]);
+        }
+      }
+      resolve(selected.length > 0 ? selected : [options[0]]);
+    });
+  });
+}
+
+module.exports = { selectLanguage, question, multiSelect };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/agent-instructions.md

@@ -5,11 +5,27 @@ This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@br
 
 **The whole point of this file:** when the user states an intent that matches the Trigger Map below, run the matching `dw-*` command **without asking permission first** — unless the change is genuinely trivial (see Escape Hatches).
 
+## Auto-Sizing Matrix
+
+Before picking a command from the Trigger Map, gauge the change's actual scope. The same intent ("fix this", "add this") can mean very different amounts of work; the matrix names four sizes and routes each to a different entry point. **Pick the smallest one that fits — under-routing wastes ceremony, over-routing hides scope.**
+
+| Size | What it looks like | Route to |
+|------|---------------------|----------|
+| **Small** | ≤3 files, no migration, no new endpoint, can be summarized in one sentence. Examples: typo, log message, single-line config, dependency bump, version pin. | Just do it inline. No `dw-*` command. |
+| **Medium** | Clear feature or bug, <10 numbered tasks expected, single component or single service, no architectural decisions. Examples: add a form field with validation, fix a regression in a known module, wire a new API endpoint into an existing handler. | `/dw-bugfix` (for bugs) or `/dw-plan` (for features) — straight, not via `/dw-autopilot`. |
+| **Large** | Multi-component feature, ≥10 tasks expected, touches multiple modules, has user-visible UX surface AND backend. Examples: add a new entity end-to-end (model + migration + API + UI), introduce a third-party integration, redesign a flow. | `/dw-autopilot "<wish>"` — full PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR pipeline with three gates. |
+| **Complex** | New domain, ambiguous requirements, architectural decision required, regulatory or compliance surface, or scope that spans multiple PRDs. Examples: introduce event sourcing, rebuild auth, multi-tenancy, a new product line. | `/dw-brainstorm "<idea>"` first (auto-dispatches research/council modes), then `/dw-plan --council` so the techspec stage runs the multi-advisor debate. |
+
+**Safety valve:** if you start in Small or Medium but the work reveals it's actually Large (the inline listing exceeds 5 steps, or `/dw-bugfix` triggers its `Step 5.0` valve), STOP and escalate. There is no flag to bypass. Escalation is the correct outcome.
+
+**Adapted from** [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0). The four-size matrix is theirs; the mapping to `dw-*` commands is dev-workflow-specific.
+
 ## Trigger Map
 
 | User intent (literal or paraphrased) | Auto-trigger |
 |--------------------------------------|--------------|
 | "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-autopilot "X"` |
+| "Autopilot this PRD" / "Take this PRD to PR" / continue a bugfix escalation autonomously | `/dw-autopilot --from-prd <slug>` (existing PRD at `.dw/spec/<slug>/`) |
 | Pasted error / "X is broken" / "Bug in Y" / failing test screenshot | `/dw-bugfix "X"` |
 | "Plan this feature" / "Write a PRD + techspec + tasks" | `/dw-plan "X"` |
 | "Write a PRD for X" / "Spec out Y" | `/dw-plan prd "X"` |
@@ -18,9 +34,14 @@ This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@br
 | "Run this task" (with task ID) | `/dw-run <ID>` |
 | "Run all pending tasks" / "Execute the plan" | `/dw-run` |
 | "Continue where I left off" | `/dw-run --resume` |
+| "Pause work" / "End the session" / "Save where we are" | `/dw-pause` |
+| "Resume" / "Where did we stop?" / "Pick up where we left off" | `/dw-resume` |
 | "QA this feature" / "Run the test plan" | `/dw-qa` |
 | "Fix the QA bugs" | `/dw-qa --fix` |
 | "Evaluate the AI feature" / "Test the RAG / classifier" | `/dw-qa --ai` |
+| "Walk me through this feature" / "UAT this with me" / "Let's do a manual run-through" | `/dw-qa --uat` |
+| "Review this bugfix" / "Code-review fix `<slug>`" | `/dw-review --bugfix <slug>` |
+| "QA this bugfix" / "Validate fix `<slug>`" | `/dw-qa --bugfix <slug>` |
 | "Review my PR" / "Check code quality" / "Is this ready to ship?" | `/dw-review` |
 | "Just the PRD coverage check" | `/dw-review --coverage-only` |
 | "Just the code quality review" | `/dw-review --code-only` |
@@ -36,6 +57,8 @@ This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@br
 | "Open a new project" / "Bootstrap a stack" | `/dw-new-project` |
 | "Dockerize this" / "Add docker-compose" | `/dw-dockerize` |
 | "Functional doc" / "Map screens and flows" | `/dw-functional-doc` |
+| "Install Azure skills" / "Setup Microsoft docs MCP" / "Add Azure expertise" / "I'm going to work on Azure" | `/dw-install-azure-skills` |
+| "Install AWS skills" / "Setup AWS MCP" / "Add AWS expertise" / "I'm going to work on AWS" | `/dw-install-aws-skills` |
 
 **Priority:** when in doubt between two commands, `/dw-autopilot` is the safest default for any non-trivial feature request — it composes the rest.
 

package/scaffold/en/commands/dw-analyze-project.md

@@ -766,6 +766,67 @@ Three options:
 - Never write `.dw/constitution.md` without explicit user approval (option A) or explicit choice (options B/C).
 - Constitution file is committed to the repository like any other project artifact — never gitignored.
 
+### Step 9: Concerns Map Generation (Risk Map)
+
+After the constitution step, generate `.dw/rules/concerns.md` — the project's **risk map**. While `.dw/rules/` describes how the code IS and `.dw/constitution.md` describes what it SHOULD BE, the concerns map answers a third question: **where is it dangerous to mess around?**
+
+**Difference from the other two:**
+- `.dw/rules/*.md` — analytical (observed patterns).
+- `.dw/constitution.md` — declarative (committed principles).
+- `.dw/rules/concerns.md` — operational risk (load-bearing fragility, hot spots, hostile code).
+
+**Behavior:**
+
+If `.dw/rules/concerns.md` already exists with hand-edited entries between `<!-- preserved:start -->` and `<!-- preserved:end -->` markers, preserve those entries. Refresh the auto-generated sections (Hot Spots churn data, Known Bug History from `.dw/bugfixes/`).
+
+Otherwise (first run), build the file from scratch using `.dw/templates/concerns-template.md` as the base.
+
+**Data to collect:**
+
+1. **Hot Spots — churn analysis.** For each module discovered in Step 5, compute the count of commits touching files in that module over the last 90 days (`git log --since="90 days ago" --name-only -- <module-path> | wc -l`). Modules in the top 20% by churn are candidates. Cross-reference with `.dw/bugfixes/` (next item) — modules that also appear there are confirmed Hot Spots; the rest are flagged "high churn — verify with team."
+
+2. **Known Bug History — bugfix aggregation.** If `.dw/bugfixes/` exists, scan every `SUMMARY.md` in it. For each, parse the `Files Touched` table; aggregate file paths by their top-level module (e.g. `src/auth/session.ts` -> `src/auth/`). Any module with `>= 2` historical fixes lands in the Known Bug History section with the count and the recent bugfix slugs.
+
+3. **Fragile Integrations.** Look for telltale patterns in code and config:
+   - External SDK clients with retry/backoff scaffolding (suggests prior failures).
+   - Comments like `// FIXME: vendor returns 200 with empty body sometimes`, `// HACK: legacy API workaround`, `// TODO: handle vendor X edge case`.
+   - Hand-rolled retry loops around fetch/axios/HTTP clients.
+   - `.dw/incidents/` directory — every incident postmortem that names an external system goes in here.
+   List these candidates. Don't fabricate — only what you observe.
+
+4. **Hostile Code.** Heuristics for code that needs full understanding before modification:
+   - Regex literals longer than 80 characters with no explanatory comment.
+   - Functions over 100 lines with cyclomatic complexity that resists quick reading (rough heuristic: lots of nested `if`/`switch`/loops).
+   - Manual transaction/locking code outside an ORM's idiomatic layer.
+   - Custom serializers/parsers (e.g. hand-written JSON, CSV, binary formats) without a corresponding test file.
+   Flag candidates and let the user confirm.
+
+5. **Tech Debt — Acknowledged.** Scan README, CONTRIBUTING, docs/, and code comments for `TODO`, `FIXME`, `XXX`, `HACK`, `DEPRECATED` markers older than 90 days (use `git blame` to date them). Cluster by area. Present as candidates; the user decides which deserve acknowledgement (some are stale comments, some are real debt).
+
+**Procedure:**
+
+1. **Show candidates in chat first** (do NOT write the file yet). Format as a markdown table per section with a count and the strongest evidence for each entry. Cap each section at 10 entries — if more, list "+N more (see full analysis)" and let the user request expansion.
+
+2. Ask: "Approve as-is, drop specific entries (give the row labels), or skip this step entirely?" Wait for explicit response.
+
+3. On approval, write `.dw/rules/concerns.md` using `.dw/templates/concerns-template.md`. Fill in:
+   - Frontmatter `last_refreshed: <today's ISO date>`.
+   - Hot Spots table.
+   - Fragile Integrations table.
+   - Hostile Code table.
+   - Known Bug History table.
+   - Tech Debt — Acknowledged table.
+
+4. If a `<!-- preserved:start --> ... <!-- preserved:end -->` block existed in a prior version, append it back at the end of the file (the team's hand-curated entries).
+
+5. Print: "Wrote `.dw/rules/concerns.md`. Loaded on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix` when their target touches a listed area. Never blocks — it informs, surfaces, and suggests an ADR for deviations."
+
+**Special case — no signals found:**
+
+If after the heuristics nothing crosses the bar (small codebase, low churn, no incidents, no bugfix history), write a minimal `concerns.md` with all sections empty (just headers) and a note: "No risk signals at this time. Re-run after the project accumulates more history."
+
+**Refresh cadence:** users re-run `/dw-analyze-project` whenever rules drift. Step 9 refreshes auto sections while keeping preserved entries. There is no separate refresh-only command.
+
 ## Quality Checklist
 
 Before declaring the analysis complete, verify:
@@ -787,6 +848,9 @@ Before declaring the analysis complete, verify:
 - [ ] Generated one `.dw/rules/{project}.md` per leaf project discovered
 - [ ] Generated `.dw/rules/integrations.md` (if 2+ projects)
 - [ ] All file paths in rules reference real, existing files
+- [ ] Step 8 (constitution) offered and resolved (A/B/C)
+- [ ] Step 9 (concerns map) presented candidates, awaited approval, wrote `.dw/rules/concerns.md` (or noted no signals)
+- [ ] Preserved-marker blocks in concerns.md kept verbatim on refresh
 - [ ] Topology analysis completed (god nodes, coupling metrics, dependency graph)
 - [ ] Critical nodes table generated with Ca, Ce, instability
 - [ ] Circular dependencies identified and documented

package/scaffold/en/commands/dw-autopilot.md

@@ -44,13 +44,22 @@ A step that invokes a `/dw-xxx` command is ONLY considered complete when the art
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{WISH}}` | Description of what the user wants to build | "push notification system with per-channel preferences" |
+| `{{WISH}}` | Description of what the user wants to build (default mode) | "push notification system with per-channel preferences" |
+| `{{PRD_SLUG}}` | Existing PRD slug to autopilot from (when `--from-prd` is used) | `prd-bugfix-stripe-webhook-retry` |
+| `{{MODE}}` | Optional invocation flag | `--from-prd <slug>` |
+
+## Invocation Modes
+
+| Invocation | Behavior |
+|------------|----------|
+| `/dw-autopilot "<wish>"` | **Default.** Full pipeline from scratch: Codebase Intelligence → Research → Brainstorm → PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR. |
+| `/dw-autopilot --from-prd <slug>` | **Resume-from-PRD mode.** Skips Steps 1–4 (Intel, Research, Brainstorm, PRD). Starts at GATE 1 (presents the existing PRD for approval), then continues through TechSpec → Tasks → Run → QA → Review → Commit → PR. Used when `/dw-bugfix` has escalated via its safety valve and written a PRD to `.dw/spec/<slug>/`, or when the user previously authored a PRD by hand and wants the rest automated. |
 
 ## Approval Gates
 
 The autopilot stops ONLY at these 3 moments:
 
-1. **GATE 1 — PRD**: Presents the generated PRD and awaits user approval before generating techspec/tasks
+1. **GATE 1 — PRD**: Presents the generated PRD (default mode) or the existing PRD (--from-prd mode) and awaits user approval before generating techspec/tasks
 2. **GATE 2 — Tasks**: Presents the task list and awaits approval before starting execution
 3. **GATE 3 — PR**: After automatic commit, asks if the user wants to generate the Pull Request
 
@@ -66,6 +75,22 @@ If this command is re-invoked on the same PRD after interruption:
 
 ## Full Pipeline
 
+### Step 0: Resolve invocation mode (MANDATORY first action)
+
+Before Step 1, decide which mode is in effect:
+
+1. **If `--from-prd <slug>` is present in the invocation:**
+   - Resolve `{{PRD_SLUG}}` to `.dw/spec/<slug>/`.
+   - Verify the directory exists and contains a `prd.md`. If either is missing, STOP and report: `--from-prd target .dw/spec/<slug>/prd.md not found. Run /dw-plan prd or fix the slug.`
+   - Check whether `.dw/bugfixes/*/escalated.md` references this slug. If yes, note in the progress block: `Resuming from bugfix escalation: <NNN-bugfix-slug> → <slug>`.
+   - Set `mode: "from-prd"` in `autopilot-state.json` and `skipped_steps: [1, 2, 3, 4]` with `skip_reason: "from-prd-mode"`.
+   - Jump directly to **GATE 1** (PRD approval) using the existing `prd.md`.
+
+2. **Otherwise (default mode):**
+   - Set `mode: "autopilot"` and proceed to Step 1 normally.
+
+<critical>In `--from-prd` mode, Steps 1–4 MUST be marked as `skipped_steps` with `skip_reason: "from-prd-mode"`. The pre-commit audit (Step 14) MUST honor this — a skipped step is not the same as a missing step.</critical>
+
 ### Step 1: Codebase Intelligence
 
 <critical>If `.dw/intel/` exists, querying it via `/dw-intel` is MANDATORY before starting. Falls back to `.dw/rules/` and direct grep if absent.</critical>
@@ -104,12 +129,15 @@ Run `/dw-plan prd` using brainstorm findings.
 
 ### === GATE 1: PRD Approval ===
 
+**In default mode:** the PRD was just written in Step 4.
+**In `--from-prd` mode:** the PRD already existed on disk before this autopilot run started (typically authored by `/dw-bugfix --analysis` or by a safety-valve escalation, or hand-edited).
+
 Present to the user:
 - Summary of functional requirements
-- Decisions made automatically
+- Decisions made automatically (default mode) OR origin note: "PRD authored by /dw-bugfix escalation on <date>" / "PRD pre-existing on disk" (--from-prd mode)
 - Open questions (if any)
 
-**Wait for explicit approval.** If the user requests changes, adjust and re-present.
+**Wait for explicit approval.** If the user requests changes, adjust and re-present. In `--from-prd` mode, edits go directly into the existing `.dw/spec/<slug>/prd.md` — there is no separate draft.
 
 ### Step 5: TechSpec (Interactive — 7+ Questions)
 
@@ -216,6 +244,34 @@ Run `/dw-review --coverage-only` again to confirm QA fixes did not break PRD com
 Run `/dw-review --code-only` (Level 3) for formal review.
 - Generate persisted report
 
+### Step 13.5: Close the bugfix loop (Conditional)
+
+<critical>This step runs only when `mode == "from-prd"` AND the `prd_path` matches `.dw/spec/prd-bugfix-*`. Otherwise skip with `skip_reason: "not a bugfix escalation"`.</critical>
+
+When the autopilot is finishing a bugfix that was escalated by `/dw-bugfix`, the index entry in `.dw/bugfixes/NNN-<slug>/` still has only `TASK.md` and `escalated.md` — no `SUMMARY.md` was written because the surgical bugfix flow never reached step 5.5 (the spec-driven flow did the work instead). Without `SUMMARY.md`, `/dw-intel --build` skips this bugfix forever, so `bugfix-history` queries never surface the lesson learned.
+
+This step closes that loop **before** Step 14 (Commit) so the SUMMARY lands in the same commit as the fix.
+
+**Procedure:**
+
+1. **Find the index entry.** Glob `.dw/bugfixes/*/escalated.md`. For each, read the one-line content and check whether it references the current PRD slug (e.g., `→ see .dw/spec/prd-bugfix-stripe-webhook-retry/` matches the active PRD `prd-bugfix-stripe-webhook-retry`). The match is the target `NNN-<slug>/` directory.
+2. **If no match is found:** the bugfix index doesn't expect a back-write. Skip silently and continue to Step 14.
+3. **If `SUMMARY.md` already exists in the matched directory:** do not overwrite. Continue to Step 14 — the human or a previous run already closed the loop.
+4. **Otherwise, write `SUMMARY.md`** using `.dw/templates/bugfix-summary-template.md`. Source fields from:
+   - **Symptom (verbatim):** the `Symptom` section of `<prd_path>/prd.md`, or the first paragraph of the original `TASK.md` if the PRD doesn't carry it.
+   - **Root Cause:** the original `TASK.md` Root Cause section.
+   - **Resolution (2–4 bullets):** distilled from `<prd_path>/techspec.md` decisions + actual `git diff <base>...HEAD --stat` summary.
+   - **Files Touched:** parsed from `git diff <base>...HEAD --name-only` (exclude `.dw/` paths). If >5 files, that's expected for an escalated bugfix — list them all and add a note "escalated from bugfix because of scope".
+   - **Verification:** point to `<prd_path>/QA/qa-report.md` and the verify report referenced in Step 9's session output.
+   - **Related — Concerns touched:** copy from the corresponding entries in `.dw/rules/concerns.md` if any rows reference modules in `Files Touched`.
+   - **Frontmatter:** `slug: NNN-<slug>`, `created: <today's ISO date>`, `status: Fixed`, `severity: <inferred from PRD priority or default Medium>`, `related_concerns: [list from above]`.
+5. **Append a final-line note** to `escalated.md`: `Closed by /dw-autopilot --from-prd on <YYYY-MM-DD>; SUMMARY.md written.` Preserve the original escalation line above it.
+6. **Record the artifact** in `autopilot-state.json` `step_artifacts["13.5"] = [".dw/bugfixes/NNN-<slug>/SUMMARY.md", ".dw/bugfixes/NNN-<slug>/escalated.md"]`.
+
+<critical>NEVER fabricate verification evidence. If the QA report is empty or the diff is empty, do not invent files in `Files Touched`. Write the SUMMARY.md sections that are grounded and mark the rest as `_(not available — see <prd_path>/QA/ for details)_`.</critical>
+
+After this step, the bugfix becomes visible to `/dw-intel "bugfix history in <module>"` on the next `/dw-intel --build` run.
+
 ### Step 14: Commit
 
 <critical>MANDATORY PRE-COMMIT AUDIT — execute BEFORE invoking `/dw-commit`:
@@ -230,7 +286,7 @@ Run `ls` on each path below and confirm existence. If ANY is missing, DO NOT com
 - Evidence of the last `/dw-review --coverage-only` run with RF-by-RF matrix (session output or reference in `autopilot-state.json`)
 
 Also verify `autopilot-state.json`:
-- Every step 1 through 13 that is NOT in `skipped_steps` must be in `completed_steps`
+- Every step 1 through 13 (and 13.5 when in `--from-prd` mode against a `prd-bugfix-*` PRD) that is NOT in `skipped_steps` must be in `completed_steps`
 - Each completed step must have its artifacts listed in `step_artifacts`
 
 If any artifact or step is missing: STOP immediately. Report to the user: `Step N did not produce artifact X — re-running /dw-[command]`. Re-execute the command. Verify again. Only then proceed to `/dw-commit`.
@@ -263,9 +319,11 @@ Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following form
   "mode": "autopilot",
   "wish": "original user description",
   "prd_path": ".dw/spec/prd-[name]",
+  "from_prd_slug": null,
   "current_step": 8,
   "completed_steps": [1, 2, 3, 4, 5, 6, 7],
   "skipped_steps": [2],
+  "skip_reasons": {"2": "domain already mapped in .dw/rules/auth.md"},
   "gates_passed": ["prd", "tasks"],
   "step_artifacts": {
     "9": ["review-matrix-shown-in-session"],
@@ -288,6 +346,7 @@ Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following form
 - A step ONLY moves to `completed_steps` after verifying its artifacts exist on disk
 - If the session drops, re-invoke `/dw-autopilot` on the same PRD; the command reads `autopilot-state.json` and continues from the correct step, revalidating artifacts before trusting `completed_steps`
 - When the pipeline finishes (after commit or PR), remove the file or mark `"status": "completed"`
+- In `--from-prd` mode, set `from_prd_slug: "<slug>"`, `mode: "from-prd"`, and include steps 1–4 in `skipped_steps` with `skip_reason: "from-prd-mode"` — this is what the pre-commit audit checks against (Step 14 verifies that every step NOT in `skipped_steps` is in `completed_steps`)
 
 <critical>After EACH completed step, display the updated progress block to the user. This is MANDATORY — the user MUST see what was done and what comes next. If a step was skipped, the reason MUST appear in the progress block.</critical>
 

package/scaffold/en/commands/dw-bugfix.md

@@ -9,7 +9,30 @@
     - Do NOT use when fixing bugs found during QA testing (use `/dw-qa --fix` instead)
 
     ## Pipeline Position
-    **Predecessor:** (bug report) | **Successor:** `/dw-commit` then `/dw-generate-pr`
+    **Predecessor:** (bug report) | **Successor:** `/dw-commit` then `/dw-generate-pr` (optionally `/dw-review --bugfix <slug>` and `/dw-qa --bugfix <slug>` in between for additional rigor)
+
+    ## File Locations
+
+    Every bugfix has an index entry in `.dw/bugfixes/`. Direct mode keeps the full artifact there. Analysis mode and safety-valve escalations split: the index entry stays in `.dw/bugfixes/`, but the `prd.md` that `/dw-plan` will consume lands in `.dw/spec/prd-bugfix-<slug>/` (the path `/dw-plan techspec` and `/dw-plan tasks` already expect).
+
+    **Index home — always created:**
+
+    - Bugfix index directory: `.dw/bugfixes/NNN-<slug>/` (NNN zero-padded to 3 digits, sequential across all bugfixes ever recorded)
+    - Direct-mode artifacts written here: `TASK.md` (triage + plan), `fix-report.md` (verify evidence), `SUMMARY.md` (one-page record)
+    - Analysis / escalation artifacts written here: `TASK.md` (triage + would-be plan), `escalated.md` (one line pointing to the spec directory that took over)
+    - Downstream review output (when `/dw-review --bugfix <slug>` runs): `.dw/bugfixes/NNN-<slug>/review/`
+    - Downstream QA output (when `/dw-qa --bugfix <slug>` runs): `.dw/bugfixes/NNN-<slug>/QA/`
+
+    **Spec home — created only on Analysis or safety-valve escalation:**
+
+    - Spec directory: `.dw/spec/prd-bugfix-<slug>/`
+    - `prd.md` lives here (NOT in `.dw/bugfixes/`) so `/dw-plan techspec prd-bugfix-<slug>` and `/dw-plan tasks prd-bugfix-<slug>` operate against the path they were designed for, with no modification to `/dw-plan`.
+
+    **Templates:** `.dw/templates/bugfix-template.md` (for `TASK.md`/`prd.md`), `.dw/templates/bugfix-summary-template.md` (for `SUMMARY.md`), `.dw/templates/pr-bugfix-template.md` (for the PR body).
+
+    **Next-number discovery:** list `.dw/bugfixes/`, parse the leading 3-digit prefix of each directory, take `max + 1` (or `1` if empty). Create the directory before writing anything. The same `NNN-<slug>` is used to name the spec directory's slug portion (e.g., bugfix `007-stripe-webhook-retry` escalates to spec `.dw/spec/prd-bugfix-stripe-webhook-retry/`).
+
+    **Slug:** kebab-case derived from `{{BUG_DESCRIPTION}}` (e.g., "login-not-working", "error-500-save-user").
 
     ## Complementary Skills
 
@@ -34,23 +57,23 @@
 
     | Mode | When to Use | Result |
     |------|-------------|--------|
-    | **Direct** (default) | Simple bug, <=5 files, no migration | Executes immediate fix |
-    | **Analysis** (`--analysis`) | Complex bug, needs planning | Generates `tasks/dw-bugfix-*/prd.md` for techspec -> tasks |
+    | **Direct** (default) | Simple bug, <=5 files, no migration, <=5 numbered tasks | Executes immediate fix; persists `TASK.md` + `fix-report.md` + `SUMMARY.md` in `.dw/bugfixes/NNN-<slug>/` |
+    | **Analysis** (`--analysis`) | Complex bug, needs planning | Splits: `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}` as the index entry + `.dw/spec/prd-bugfix-<slug>/prd.md` for the techspec -> tasks pipeline |
 
     ### Analysis Mode
 
-    When the user specifies `--analysis` or when you detect the bug needs more planning:
+    When the user specifies `--analysis` or when the safety valve (step 5.0) trips:
 
     ```
     bugfix my-project "Login not working" --analysis
     ```
 
     In this mode:
-    1. Follow the normal question and analysis flow
-    2. Instead of executing, generate a document at `.dw/spec/dw-bugfix-[name]/prd.md`
-    3. The file is named `prd.md` to maintain compatibility with the create-techspec/dw-plan tasks pipeline
-    4. Then the user can run `create-techspec .dw/spec/dw-bugfix-[name]`
-    5. And then `create-tasks .dw/spec/dw-bugfix-[name]`
+    1. Follow the normal question and analysis flow.
+    2. Allocate `NNN` and create `.dw/bugfixes/NNN-<slug>/`. Write `TASK.md` (the triage + clarification answers + the would-be plan that won't run here).
+    3. Create the spec directory `.dw/spec/prd-bugfix-<slug>/` and write `prd.md` there (using `.dw/templates/bugfix-template.md`). This is the path `/dw-plan techspec` and `/dw-plan tasks` already know how to operate against.
+    4. Write `.dw/bugfixes/NNN-<slug>/escalated.md` with exactly one line: `Escalated to /dw-plan on <YYYY-MM-DD> → see .dw/spec/prd-bugfix-<slug>/`. This is the cross-reference that lets `/dw-intel --build` include the bugfix in `bugfixes.json` even though the active planning happens in `.dw/spec/`.
+    5. Tell the user the next commands: `/dw-plan techspec prd-bugfix-<slug>` and `/dw-plan tasks prd-bugfix-<slug>`.
 
     ## Workflow
 
@@ -144,6 +167,27 @@
     - {{TARGET}}/.dw/rules/*.md
     ```
 
+    ### 1.5. Load Concerns (Required when concerns.md exists)
+
+    If `.dw/rules/concerns.md` exists:
+    - Read it once.
+    - For each file or module referenced in `{{BUG_DESCRIPTION}}` or in the suspected fix area, cross-check against Hot Spots, Fragile Integrations, Hostile Code, and Known Bug History.
+    - If a match is found, surface it BEFORE asking the 3 clarification questions:
+
+    ```
+    ## Concern detected
+
+    The area you're touching is flagged in `.dw/rules/concerns.md`:
+
+    > [verbatim entry from concerns.md]
+
+    This means: [translate the concern into what it implies for this fix — extra test, extra reviewer, ADR, etc.]
+
+    Proceeding — but the fix-report.md must explicitly call out which concern was touched and how it was handled.
+    ```
+
+    If `.dw/rules/concerns.md` is missing, do NOT auto-create it (that's `/dw-analyze-project` Step 9's job). Note in chat: "no concerns map yet — consider running `/dw-analyze-project` after the fix to build one." Continue.
+
     ### 2. Collect Evidence (Required)
 
     Execute commands to understand the current state:
@@ -246,6 +290,40 @@
     - With `--analysis`: Go to step 6
     - Without `--analysis`: Continue to step 5
 
+    ### 5.0. Safety Valve (MANDATORY before step 5)
+
+    <critical>
+    BEFORE drafting the numbered task list in step 5, sketch the inline steps you intend to write.
+    If that sketch reveals **more than 5 distinct numbered tasks**, OR **any cross-file dependency that means tasks must be executed in a specific order**, OR **a task that requires running database migration / refactor / new endpoint / API contract change**, then the bugfix scope was UNDERESTIMATED and you MUST escalate.
+    </critical>
+
+    **Why this exists:** the triage at step 0 catches scope problems from the symptom description. The checkpoint at 4.1 catches them after root cause analysis. This valve catches the remaining case — when the fix itself, once laid out, reveals more complexity than triage and root cause analysis predicted. There is NO bypass flag. Escalation is the correct outcome.
+
+    **Escalation procedure:**
+
+    1. Allocate `NNN` for `.dw/bugfixes/NNN-<slug>/`. Write `TASK.md` with the triage, clarifications, root cause, and the would-be plan.
+    2. Create `.dw/spec/prd-bugfix-<slug>/` and write `prd.md` there (use `.dw/templates/bugfix-template.md`). This is the path `/dw-plan` expects.
+    3. Write `.dw/bugfixes/NNN-<slug>/escalated.md` with: `Escalated to /dw-plan on <YYYY-MM-DD> — reason: <which valve criterion tripped> → see .dw/spec/prd-bugfix-<slug>/`.
+    4. Report to the user:
+
+    ```
+    ## Scope larger than a bugfix
+
+    Listing the fix produced [N] tasks / [cross-file deps] / [forbidden change type].
+    Per the safety valve, this is no longer a surgical bugfix.
+
+    Bugfix index preserved at `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}`.
+    PRD created at `.dw/spec/prd-bugfix-<slug>/prd.md`.
+
+    Next — pick one:
+      - Manual chain: `/dw-plan techspec prd-bugfix-<slug>` → `/dw-plan tasks prd-bugfix-<slug>` → `/dw-run` → `/dw-qa` → `/dw-review` → `/dw-commit` → `/dw-generate-pr`.
+      - Hand off to autopilot: `/dw-autopilot --from-prd prd-bugfix-<slug>` — picks up at GATE 1 (PRD approval) and runs the rest automatically with the usual three gates.
+    ```
+
+    5. Stop this command. Do not proceed to step 5. The user (or autopilot) invokes `/dw-plan` or `/dw-autopilot --from-prd` next.
+
+    **If the valve does NOT trip:** Continue to step 5.
+
     ### 5. Propose Numbered Tasks (Required)
 
     <critical>
@@ -284,14 +362,24 @@
     - `adjust` - Tell me what to modify in the plan
     ```
 
-    ### 5.5. Final Verification (Direct mode — required before commit)
+    ### 5.5. Final Verification + Persistence (Direct mode — required before commit)
 
     <critical>After applying the approved tasks in Direct mode, invoke `dw-verify` before committing. The VERIFICATION REPORT must show:
     1. The project's verify command (test + lint + build) with exit 0.
     2. Original-symptom reproduction: the scenario that triggered the bug no longer triggers it.
-    
+
     Without PASS on both, DO NOT commit. Report what failed and return to step 4 (root-cause analysis).</critical>
 
+    **On PASS, persist the bugfix artifact (always — including Direct mode):**
+
+    1. Discover the next `NNN` (see File Locations section).
+    2. Create `.dw/bugfixes/NNN-<slug>/` if not yet created in step 5.0.
+    3. Write `TASK.md` with the triage, clarifications, root cause, and the approved plan as executed (use `.dw/templates/bugfix-template.md` as the base structure).
+    4. Write `fix-report.md` with the verbatim `dw-verify` VERIFICATION REPORT plus the before/after reproduction trace.
+    5. Write `SUMMARY.md` using `.dw/templates/bugfix-summary-template.md`. Fill in slug, date, status `Fixed`, severity, related_concerns (from step 1.5), Symptom (verbatim), Root Cause (one sentence), Resolution (2-4 bullets), Files Touched, Verification, Related, Followups.
+    6. If the fix touched a concern listed in `.dw/rules/concerns.md`, append a line to that concern's row's `Last incident` column (or add a new row under Known Bug History) — preserve hand-written entries between `<!-- preserved:start -->` markers.
+    7. Report paths of all three files in chat before the commit step.
+
     ### 6. Generate Bugfix Document (Analysis Mode)
 
     <critical>
@@ -301,28 +389,35 @@
     </critical>
 
     **Actions:**
-    1. Create directory: `.dw/spec/dw-bugfix-[bug-name]/`
-    2. Populate with all information collected in previous steps
-    3. Save as: `.dw/spec/dw-bugfix-[bug-name]/prd.md` (uses name `prd.md` for pipeline compatibility)
+    1. Discover the next `NNN` and create `.dw/bugfixes/NNN-<slug>/`.
+    2. Write `TASK.md` in the bugfix dir (the triage, clarifications, root cause, and analysis output) using `.dw/templates/bugfix-template.md` as the base.
+    3. Create `.dw/spec/prd-bugfix-<slug>/` and write `prd.md` there using `.dw/templates/bugfix-template.md`. This is the path `/dw-plan` already understands — no modification to `/dw-plan` needed.
+    4. Write `.dw/bugfixes/NNN-<slug>/escalated.md` with: `Analysis mode on <YYYY-MM-DD> → see .dw/spec/prd-bugfix-<slug>/`.
 
-    **Bug name:** Use kebab-case based on the description (e.g., "login-not-working", "error-500-save-user")
+    **Bug slug:** kebab-case from the description (e.g., "login-not-working", "error-500-save-user").
 
-    **IMPORTANT:** The file must be named `prd.md` (not `bugfix.md`) so that the
-    `create-techspec` and `create-tasks` commands work without modification, since they expect `prd.md`.
+    **Why the split:** `/dw-plan techspec` and `/dw-plan tasks` already hardcode `.dw/spec/prd-<slug>/prd.md` as their input. To keep `/dw-plan` untouched, the PRD lands there; the `.dw/bugfixes/NNN-<slug>/` directory remains the queryable index entry (consumed by `/dw-intel`, `/dw-review --bugfix`, `/dw-qa --bugfix`). The `escalated.md` file is the cross-reference.
 
     **Output format:**
     ```
     ## Bugfix Document Generated
 
-    File created: `.dw/spec/dw-bugfix-[name]/prd.md`
+    Bugfix index: `.dw/bugfixes/NNN-<slug>/{TASK.md, escalated.md}`
+    Planning PRD: `.dw/spec/prd-bugfix-<slug>/prd.md`
+
+    **Next steps — pick one:**
+
+    Option A (manual chain, full control):
+    1. Review `.dw/spec/prd-bugfix-<slug>/prd.md`
+    2. Run: `/dw-plan techspec prd-bugfix-<slug>`
+    3. Run: `/dw-plan tasks prd-bugfix-<slug>`
+    4. Execute tasks with: `/dw-run` (or by task ID against the spec)
 
-    **Next steps:**
-    1. Review the generated document
-    2. Run: `create-techspec .dw/spec/dw-bugfix-[name]`
-    3. Run: `create-tasks .dw/spec/dw-bugfix-[name]`
-    4. Execute the tasks with: `run-task [number] .dw/spec/dw-bugfix-[name]`
+    Option B (hand off to autopilot):
+    1. Run: `/dw-autopilot --from-prd prd-bugfix-<slug>`
+    2. Autopilot picks up at GATE 1 (PRD approval) and runs TechSpec, Tasks, Run, QA, Review, Commit, PR with the usual three gates.
 
-    The flow follows the same pattern as a feature/PRD.
+    The bugfix index entry stays queryable via `/dw-intel "bugfix history in <module>"`. Downstream `/dw-review --bugfix <slug>` and `/dw-qa --bugfix <slug>` still target `.dw/bugfixes/NNN-<slug>/` when you want a focused review of just the eventual surgical patch.
     ```
 
     ---
@@ -376,18 +471,21 @@
 
     ## Quality Checklist
 
-    - [ ] **Bug vs Feature triage performed**
-    - [ ] **Scope checkpoint performed (step 4.1)**
+    - [ ] **Bug vs Feature triage performed (step 0)**
+    - [ ] **Concerns map consulted if present (step 1.5)**
     - [ ] Project/PRD context loaded
     - [ ] Evidence collected (git log, errors)
     - [ ] **EXACTLY 3 questions asked**
     - [ ] Responses received and analyzed
     - [ ] Root cause identified
+    - [ ] **Scope checkpoint performed (step 4.1)**
+    - [ ] **Safety valve checked (step 5.0) — escalated to `/dw-plan` if tripped**
     - [ ] Tasks numbered sequentially
     - [ ] **Maximum 5 affected files**
     - [ ] **No migrations**
     - [ ] **Test task included (correct project framework)**
     - [ ] Awaiting approval before executing
+    - [ ] **`.dw/bugfixes/NNN-<slug>/{TASK,fix-report,SUMMARY}.md` written after verify PASS**
 
     <critical>
     FIRST: Evaluate if it's a bug or feature (Step 0).