@brunosps00/dev-workflow 1.0.0 → 1.0.2

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

@@ -11,14 +11,34 @@ You are a brainstorming facilitator for the current workspace. This command exis
 ## Pipeline Position
 **Predecessor:** (user idea) | **Successor:** `/dw-plan prd`
 
-## Flags
+## How this command works (auto-dispatch, not flag switchboard)
 
-- **(default)**: normal brainstorm with 3-7 options (conservative, balanced, bold) and trade-offs. If the product has PRDs or rules, a **Product Inventory** is produced automatically and each option carries a classification tag.
-- **`--onepager`**: at the end of the brainstorm, generate a durable one-pager at `.dw/spec/ideas/<slug>.md` (using `.dw/templates/idea-onepager.md`) with Feature Inventory + Classification & Rationale + MVP Scope + Not Doing + Assumptions. Use when you want a persisted product artifact before moving to `/dw-plan prd`.
-- **`--council`**: after the normal brainstorm, invoke the `dw-council` skill to stress-test the top 2-3 options via 3-5 archetypes (pragmatic-engineer, architect-advisor, security-advocate, product-mind, devils-advocate). Useful when the choice is high-impact and there is genuine dissent between paths.
-- **`--research`**: heavyweight multi-source research mode. Pipeline: scope → plan → retrieve (parallel sources) → triangulate → outline-refine → synthesize → critique → refine → report. Output: cited research document. Use for state-of-the-art reviews, technology comparisons, regulatory landscape mapping. Sub-modes: `quick` (3 phases, 2-5min), `standard` (default, 6 phases, 5-10min), `deep` (8 phases, 10-20min), `ultradeep` (8+ phases, 20-45min).
-- **`--refactor`**: code-smell catalog mode. Audits a target directory or PRD scope for code smells using Martin Fowler's taxonomy (bloaters, change preventers, dispensables, couplers, conditional complexity, DRY violations). Maps each smell to a concrete refactoring technique with before/after sketches. Severity-ordered P0-P3 plan. Output: refactoring opportunities document.
-- Flags are composable where it makes sense: `--onepager --council` produces the one-pager after the council debate. `--research --onepager` saves the research output as a durable one-pager. `--refactor --onepager` saves the refactor plan as a durable one-pager. `--research --refactor` is NOT supported (pick one or the other — different ideation surfaces).
+`/dw-brainstorm` runs **FULL** by default. It opens with a **Signal Reading** phase that inspects the user's request, the project state (PRDs, rules, intel, recent commits), and the conversation so far, then **dispatches one or more internal modes**. The user does not pick a mode — the command does.
+
+Internal modes (the dispatcher picks 1+):
+
+| Mode | Auto-fires when |
+|------|-----------------|
+| **option-matrix** (always-on default) | Default surface: 3-7 options (conservative / balanced / bold) with `[IMPROVES] / [CONSOLIDATES] / [NEW]` tags. Always runs unless a hard override says otherwise. |
+| **grill** | Vocabulary feels unsettled — user terms differ from `.dw/rules/` / `.dw/constitution.md`, or two synonyms compete in the same conversation, or a contributor proposes a name that clashes with the glossary. |
+| **prototype** | User asks "is this state model right?" / "what should this look like?" with no clear answer; or the next sensible step is to RUN code, not write words. |
+| **council** | Two or more competing approaches surface with no obvious winner; or consensus forms too quickly (false-consensus signal). |
+| **research** | The question depends on external state-of-the-art ("what's the current best practice for X", multi-source comparisons, regulatory or framework landscape). |
+| **refactor-audit** | User points at a directory or describes a code area as "messy", "needs cleanup", "tech debt"; or a quarterly health-check is requested. |
+| **onepager** | The conversation has converged enough to deserve a durable product artifact (`.dw/spec/ideas/<slug>.md`); or the user signals they're about to call `/dw-plan prd` next. |
+
+Modes can chain inside one session — grill can surface a design question that the dispatcher then sends to prototype; refactor-audit can produce findings that the dispatcher sends to council for stress-testing.
+
+### Optional overrides (rarely needed)
+
+- **`--mode=<name>`** — force a specific dispatch and skip Signal Reading. Names: `option-matrix`, `grill`, `prototype`, `council`, `research`, `refactor-audit`, `onepager`. Combine with `+` to chain explicitly: `--mode=grill+onepager`.
+- **`--quiet`** — skip Signal Reading entirely and run only `option-matrix` as a minimal facilitator.
+
+Power users who already know what they want can pass `--mode=`. Everyone else gets auto-dispatch by default — the command reads the room and acts.
+
+### Migration note (transitional)
+
+Old flag invocations (`--onepager`, `--council`, `--research`, `--refactor`, `--grill`, `--prototype`) remain accepted for one minor cycle and map to the equivalent `--mode=` value. New code should use `--mode=` or rely on auto-dispatch.
 
 ## Decision Flowchart: Brainstorm vs Direct PRD
 
@@ -42,15 +62,16 @@ digraph brainstorm_decision {
 
 When available in the project under `./.agents/skills/`, use these skills to enrich ideation:
 
-- `dw-council` (opt-in via `--council`): multi-advisor stress-test of the most promising options with mandatory steel-manning and concession tracking. **DO NOT invoke by default** — only when the flag is present or when consensus forms too quickly (false-consensus signal).
-- `dw-ui-discipline`: use when brainstorming involves frontend or UI direction — its hard-gate (scene sentence, surface job) is a generative forcing function during ideation, not just a review check
-- `vercel-react-best-practices`: use when brainstorming React/Next.js architecture or performance trade-offs
-- `security-review`: use when brainstorming touches auth, data handling, or security-sensitive features
+- `dw-council`: invoked by the dispatcher's **council** mode — multi-advisor stress-test of the most promising options with mandatory steel-manning and concession tracking. The dispatcher fires it when 2+ paths tie OR consensus forms too quickly (false-consensus signal). Not invoked on every brainstorm — only when signals justify it.
+- `dw-simplification`: invoked by the dispatcher's **refactor-audit** mode — applies Chesterton's Fence + complexity metrics + the new **deep-modules** reference (deletion test, locality, leverage, interface depth) to every flagged smell.
+- `dw-ui-discipline`: use when brainstorming involves frontend or UI direction — its hard-gate (scene sentence, surface job) is a generative forcing function during ideation, not just a review check. Also picked up by the **prototype** mode's UI branch.
+- `vercel-react-best-practices`: use when brainstorming React/Next.js architecture or performance trade-offs.
+- `security-review`: use when brainstorming touches auth, data handling, or security-sensitive features.
 
 ## Template Reference
 
 - Brainstorm matrix template: `.dw/templates/brainstorm-matrix.md` (relative to workspace root)
-- Durable one-pager template: `.dw/templates/idea-onepager.md` (used with `--onepager` flag)
+- Durable one-pager template: `.dw/templates/idea-onepager.md` (used by the **onepager** mode)
 
 Use this command when the user wants to:
 - Generate ideas for product, UX, architecture, or automation
@@ -63,6 +84,19 @@ Use this command when the user wants to:
 
 <critical>The brainstorm is a **product-level** phase, not technical. DO NOT dive into architecture, stack, endpoints, schemas. That's the techspec's job. Here we work user journeys, value, features, and boundaries.</critical>
 
+### 0. Signal Reading (always first, unless `--quiet` or explicit `--mode=`)
+
+Before producing any output, **read the situation**:
+
+1. Inspect `.dw/spec/prd-*/`, `.dw/rules/`, `.dw/constitution.md`, `.dw/intel/` if they exist. Note the project's current vocabulary and recent PRDs.
+2. Inspect recent git activity (`git log --oneline -20`) to detect ongoing work.
+3. Re-read the user's request against the Auto-Dispatch table at the top of this file. Match signals to modes.
+4. Decide the dispatch: **option-matrix** always runs unless an explicit mode override skips it. Other modes (grill, prototype, council, research, refactor-audit, onepager) fire **additively** when their signals are present.
+5. State the dispatch decision to the user in one short line: e.g., "Dispatching: option-matrix + onepager (PRD is one step away)" or "Dispatching: grill (vocabulary unsettled in current PRD)". Do not bury this — surface it before running.
+6. Then proceed with the modes in this order (when chained): grill → research → option-matrix → council → refactor-audit → prototype → onepager. Skip modes not in the dispatch.
+
+### Standard flow (option-matrix mode)
+
 1. Start by summarizing the problem in 1 to 3 sentences.
 2. **Reframe as "How Might We"**: turn the raw idea into `How might we [verb] for [user] so that [outcome]?`. This pulls the team out of premature "solution mode".
 3. **Product Inventory (required if the product exists)**:
@@ -80,7 +114,7 @@ Use this command when the user wants to:
    - Approximate effort level
 7. Whenever it makes sense, include conservative, balanced, and bold alternatives.
 8. Close with a pragmatic recommendation and clear next steps.
-9. **If the `--onepager` flag is present**: at the end, generate `.dw/spec/ideas/<slug>.md` using `.dw/templates/idea-onepager.md`, filling Feature Inventory, Classification & Rationale, Recommended Direction (product language), MVP Scope (user stories), Not Doing, Key Assumptions, and Open Questions. Report the path to the user.
+9. **If the dispatcher selected `onepager` mode** (auto-fires when conversation has converged enough, or user signals they're heading to `/dw-plan prd` next): at the end, generate `.dw/spec/ideas/<slug>.md` using `.dw/templates/idea-onepager.md`, filling Feature Inventory, Classification & Rationale, Recommended Direction (product language), MVP Scope (user stories), Not Doing, Key Assumptions, and Open Questions. Report the path to the user.
 
 ## Preferred Response Format
 
@@ -104,7 +138,7 @@ Use this command when the user wants to:
 - Recommend 1 or 2 paths
 - Explain why they win in the current context
 
-### 6. One-pager (if `--onepager`)
+### 6. One-pager (if `onepager` mode fired)
 - Path of the created file at `.dw/spec/ideas/<slug>.md`
 
 ### 7. Next Steps
@@ -141,13 +175,15 @@ At the end, always leave the user in one of these situations:
 - With a clear recommendation (including an IMPROVES/CONSOLIDATES/NEW classification)
 - With better questions to decide
 - With a next workspace command to follow
-- With the one-pager at `.dw/spec/ideas/<slug>.md` (if `--onepager` was used)
-- With the research report at `~/Documents/<Topic>_Research_<date>/` (if `--research`)
-- With the refactor plan at `<target>/refactor-plan.md` (if `--refactor`)
+- With the one-pager at `.dw/spec/ideas/<slug>.md` (if **onepager** mode fired)
+- With the research report at `~/Documents/<Topic>_Research_<date>/` (if **research** mode fired)
+- With the refactor plan at `<target>/refactor-plan.md` (if **refactor-audit** mode fired)
+- With sharpened glossary entries in `.dw/rules/` (if **grill** mode fired)
+- With a runnable throwaway prototype + verdict template (if **prototype** mode fired)
 
-## Mode: `--research` (multi-source research)
+## Mode: research (multi-source research)
 
-Activated by the `--research` flag. Replaces the default brainstorm with a structured research pipeline that produces a cited document with verified claims.
+Fires when the question depends on external state-of-the-art (multi-source comparisons, framework / regulatory landscape, decisions needing cited evidence). Override: `--mode=research`. Replaces the default option-matrix with a structured research pipeline that produces a cited document with verified claims.
 
 <critical>Every factual claim MUST be cited immediately with [N] in the same sentence</critical>
 <critical>NEVER fabricate citations — if no source is found, say so explicitly</critical>
@@ -165,7 +201,7 @@ Activated by the `--research` flag. Replaces the default brainstorm with a struc
 ```
 Selection
 ├── Initial exploration → quick (3 phases, 2-5 min)
-├── Standard research → standard (6 phases, 5-10 min) [DEFAULT for --research]
+├── Standard research → standard (6 phases, 5-10 min) [DEFAULT for research]
 ├── Critical decision → deep (8 phases, 10-20 min)
 └── Comprehensive review → ultradeep (8+ phases, 20-45 min)
 ```
@@ -216,9 +252,9 @@ Target lengths: quick 2-4k words; standard 4-8k; deep 8-15k; ultradeep 15-20k+.
 - Label speculation explicitly.
 - Admit uncertainty: "No sources found for X."
 
-## Mode: `--refactor` (code-smell catalog)
+## Mode: refactor-audit (code-smell catalog + deep-modules)
 
-Activated by the `--refactor` flag. Audits a target codebase area for refactoring opportunities using Martin Fowler's smell taxonomy.
+Fires when the user points at a directory or describes a code area as "messy" / "needs cleanup" / "tech debt", or when a quarterly health-check is requested. Override: `--mode=refactor-audit`. Audits the target area for refactoring opportunities using Martin Fowler's smell taxonomy combined with the deep-modules analysis (deletion test, locality, leverage, interface depth) bundled in the `dw-simplification` skill.
 
 <critical>ASK EXACTLY 3 CLARIFICATION QUESTIONS BEFORE STARTING THE ANALYSIS</critical>
 
@@ -292,6 +328,111 @@ Saved to `<target>/refactor-plan.md`:
 - Proposing refactors that aren't tested or testable → high risk, won't ship.
 - Ignoring documented architectural decisions in `.dw/rules/` → flagging intentional design as smell.
 
+## Mode: grill (domain-grilling)
+
+Fires when vocabulary feels unsettled — user terms differ from `.dw/rules/` / `.dw/constitution.md`, two synonyms compete in the same conversation, or a contributor proposes a name that clashes with the glossary. Override: `--mode=grill`. Replaces the option-generation default with an **interview-style stress-test** of the plan/PRD against the project's domain vocabulary. Each round of questions sharpens one piece. Updates `.dw/rules/` (or `.dw/constitution.md`) inline as terms crystallize — never deferred to "after the conversation."
+
+<critical>Ask ONE question at a time. Wait for the answer. Don't dump a list of 5 questions and hope for the best.</critical>
+
+### When to use grill mode
+
+- Before `/dw-plan prd` when the domain feels unsettled or the team uses competing terms.
+- After `/dw-plan prd` when reviewers flag ambiguous language in the PRD.
+- During architectural discussion when "module", "service", "component" are being used interchangeably and you need to pin the canonical term.
+- When a contributor proposes a name that doesn't match the project's existing glossary.
+
+### During-session disciplines
+
+1. **Challenge against the glossary.** Read `.dw/rules/index.md` + per-module `.dw/rules/<module>.md` + `.dw/constitution.md`. Flag terminology conflicts the instant the user uses a term that differs from (or contradicts) what's already documented.
+
+2. **Sharpen fuzzy language.** When the user says "the user thing" or "the order stuff", propose a precise canonical term. Don't pretend you understood — push back.
+
+3. **Discuss concrete scenarios.** Force precision via specific edge cases: "What happens to the Order in state X when event Y arrives during retry Z?" Vague answers go back as further questions.
+
+4. **Cross-reference code.** When the user states a behavior, glance at the codebase to confirm it. Surface contradictions: "You said the API returns `OrderId` but `src/api/orders.ts:42` returns `{ order_id, status }`." Don't argue from generalities.
+
+5. **Update `.dw/rules/` inline.** When a term crystallizes, write it into the appropriate rules file in the same conversation turn. Lazy file creation: if the file doesn't exist, create it. Format follows the glossary discipline established by the project (see `.dw/rules/index.md` for shape).
+
+6. **Skip implementation details in the glossary.** `.dw/rules/` and `.dw/constitution.md` describe vocabulary and principles — not implementation. "Order: a customer's request to purchase one or more items, in one of these states: pending, paid, shipped, delivered, refunded" is fine. "Order: a TypeScript class in `src/orders/`" is implementation leak.
+
+### ADR creation discipline
+
+Only propose an ADR via `/dw-adr` when **all three** hold:
+
+| Criterion | Test |
+|-----------|------|
+| **Hard to reverse** | If we change this in 6 months, does it cost >1 week of work? |
+| **Surprising without context** | Would a new contributor reasonably reach a different decision? |
+| **Genuine trade-off** | Was there a real alternative we considered and chose against? |
+
+If any is missing, skip the ADR. Don't ADR every casual decision — that turns the ADR folder into noise.
+
+### Output
+
+grill mode produces:
+- **Updated `.dw/rules/<module>.md`** or `.dw/constitution.md` with crystallized terms.
+- **Updated PRD / TechSpec** if grilling happens mid-plan (terms in the artifact are aligned with the glossary).
+- **Optional `.dw/spec/<prd>/adrs/adr-NNN.md`** if criteria above hold.
+- **NO** option matrix or recommendation (that's option-matrix mode; grill is purely about sharpening). If the dispatcher chained grill+option-matrix, the option matrix runs in a separate phase.
+
+### When the discipline bends
+
+- **Greenfield project with no `.dw/rules/`**: grill anyway; the conversation produces the FIRST entries in `.dw/rules/index.md`. That's the value.
+- **Cosmetic terminology disagreements** ("should we call it `userId` or `user_id`?"): skip grill mode; use a coding-conventions ADR or `.dw/rules/index.md` Naming section.
+
+## Mode: prototype (throwaway prototype)
+
+Fires when the user asks "is this state model right?" / "what should this look like?" with no clear answer — i.e., the next sensible step is to RUN code, not write words. Override: `--mode=prototype`. Builds a **throwaway prototype that answers a single question**. The question decides the shape — pick a branch.
+
+<critical>The prototype is throwaway from day one. Don't polish. Don't add tests. Don't extract abstractions. The point is to LEARN something fast and then DELETE or absorb.</critical>
+
+### Pick a branch
+
+| User's question | Branch |
+|-----------------|--------|
+| "Does this state/logic model feel right?" | **LOGIC** — interactive terminal app that pushes the state machine through edge cases that are hard to reason about on paper. |
+| "What should this look like?" | **UI** — several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar. |
+
+If the question is ambiguous, ask the user. If user not reachable: default by surrounding code (backend module → LOGIC; page/component → UI) and state the assumption at the top of the prototype.
+
+### Rules (apply to both branches)
+
+1. **Throwaway from day one, clearly marked.** Place the prototype next to the module/page it's prototyping for (so context is obvious) but name it so a casual reader can see it's a prototype (`prototype-<slug>.ts`, `prototype-route.tsx`, etc.).
+
+2. **One command to run.** Whatever the project's task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must start it without thinking.
+
+3. **No persistence by default.** State lives in memory. Persistence is what the prototype is CHECKING, not what it depends on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear `PROTOTYPE — wipe me` name.
+
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype runnable, no abstractions.
+
+5. **Surface the state.** After every action (LOGIC) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+
+6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into real code. Don't leave it rotting in the repo.
+
+### When done
+
+The **answer** is the only thing worth keeping. Capture it durably:
+- Commit message that closes the prototype: "removed prototype X; decided <answer> based on <observation>"
+- Or an ADR (if the criteria from grill mode hold)
+- Or `.dw/spec/<prd>/NOTES.md` if mid-PRD
+- Or an issue comment if user-driven
+
+If the user isn't around, leave a `PROTOTYPE VERDICT: <pending>` placeholder so the next pass can fill it in before deletion.
+
+### Output
+
+prototype mode produces:
+- **Throwaway code file(s)** in the appropriate location.
+- A `NOTES.md` next to the prototype with the QUESTION it's answering.
+- After the user runs it and answers the question, instructions to remove the prototype + capture the verdict.
+
+### Anti-patterns
+
+- Building a prototype that's actually a feature in disguise — production-quality code, tests, deployment config. That's not a prototype; it's a first draft.
+- Leaving the prototype in the repo "in case we need it later" — six months later it's load-bearing.
+- Not capturing the verdict — the prototype answered the question and the answer evaporated.
+- Multiple prototypes stacked up at once — pick one question, answer it, move.
+
 ## Inspired by
 
 The codebase-grounded idea refinement pattern is inspired by [`addyosmani/agent-skills@idea-refine`](https://skills.sh/addyosmani/agent-skills/idea-refine) (Addy Osmani, Google — 1.4K+ installs). Adaptations for dev-workflow:
@@ -301,6 +442,8 @@ The codebase-grounded idea refinement pattern is inspired by [`addyosmani/agent-
 - Output at `.dw/spec/ideas/<slug>.md` (sibling of `prd-<slug>/`) instead of `docs/ideas/` — preserves dev-workflow path conventions.
 - Integration with the existing pipeline: `/dw-plan prd` accepts the one-pager as input, reducing clarification questions.
 
-Credit: Addy Osmani and the `idea-refine` pattern.
+The **grill** and **prototype** modes are adapted from [`mattpocock/skills/grill-with-docs`](https://github.com/mattpocock/skills/tree/main/grill-with-docs) and [`mattpocock/skills/prototype`](https://github.com/mattpocock/skills/tree/main/prototype) (Matt Pocock, MIT). dev-workflow adaptation: integrated as INTERNAL auto-dispatched modes rather than separate skills, paths rebased on `.dw/rules/` + `.dw/spec/<prd>/`, ADR creation gated on the 3-criteria test (hard-to-reverse + surprising + genuine trade-off).
+
+Credit: Addy Osmani (idea-refine) and Matt Pocock (grill-with-docs, prototype).
 
 </system_instructions>

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).

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

@@ -38,9 +38,10 @@ You are the codebase intelligence assistant. Two modes: query the existing index
 
 ## File Locations
 
-- Machine-readable intel (queried first): `.dw/intel/{stack,files,apis,deps}.json` + `.dw/intel/arch.md`
+- Machine-readable intel (queried first): `.dw/intel/{stack,files,apis,deps,bugfixes}.json` + `.dw/intel/arch.md`
 - Refresh metadata: `.dw/intel/.last-refresh.json`
-- Human-readable rules (queried second): `.dw/rules/{index,<module>,integrations}.md`
+- Human-readable rules (queried second): `.dw/rules/{index,<module>,integrations,concerns}.md`
+- Bugfix history source: `.dw/bugfixes/*/SUMMARY.md`
 - Direct grep fallback (queried last): the project source files
 
 ## Required Behavior
@@ -67,6 +68,8 @@ Classify the user's `{{QUERY}}` into one of the shapes documented in `.agents/sk
 - **api-list** — primary: `apis.json`
 - **find-export** — primary: `files.json` (search `exports` arrays)
 - **convention** — primary: `arch.md`, secondary: `.dw/rules/`
+- **bugfix-history** — primary: `bugfixes.json`, secondary: `.dw/rules/concerns.md` (triggers: "bugs in <module>", "recent fixes", "what broke in X", "fix history for Y")
+- **risk-area** — primary: `.dw/rules/concerns.md`, secondary: `bugfixes.json` (triggers: "is X risky", "what's fragile", "hot spots", "tech debt")
 
 ### 3. Search execution
 
@@ -143,7 +146,31 @@ When invoked with `--build`, the command produces or refreshes the queryable int
 5. **API extraction.** Routes, RPC handlers, GraphQL resolvers, public CLI surface. Output to `.dw/intel/apis.json`. Budget ≤1.5K tokens.
 6. **Dependency map.** Internal cross-module imports + external packages with `used_by` arrays. Output to `.dw/intel/deps.json`. Budget ≤1K tokens.
 7. **Architecture summary.** Prose document describing the project's shape, key patterns, request flows, deployment topology. Output to `.dw/intel/arch.md`. Budget ≤1.5K tokens.
-8. **Refresh metadata.** Write `.dw/intel/.last-refresh.json` with `updated_at`, `version`, `mode` (full or incremental), files-scanned count.
+8. **Bugfix history.** If `.dw/bugfixes/` exists and is non-empty, scan every `SUMMARY.md` and build `.dw/intel/bugfixes.json` (budget ≤1K tokens). Schema:
+   ```json
+   {
+     "schema_version": "1.0",
+     "fixes": [
+       {
+         "slug": "001-login-not-working",
+         "date": "YYYY-MM-DD",
+         "status": "Fixed",
+         "severity": "Medium",
+         "symptom_one_line": "...",
+         "root_cause_one_line": "...",
+         "modules_touched": ["src/auth/", "src/api/login/"],
+         "files_touched": ["src/auth/session.ts", "src/auth/session.test.ts"],
+         "related_concerns": ["src/auth/session.ts"],
+         "path": ".dw/bugfixes/001-login-not-working/"
+       }
+     ],
+     "by_module": {
+       "src/auth/": ["001-login-not-working", "007-refresh-token-leak"]
+     }
+   }
+   ```
+   Skip if `.dw/bugfixes/` does not exist. Reject SUMMARY.md files that fail frontmatter validation; log them in the build report. **Escalated bugfixes** (those with `escalated.md` but no `SUMMARY.md` because the fix lives under `.dw/spec/prd-bugfix-<slug>/`) are skipped from `bugfixes.json` until the spec ships a fix — they re-enter the index when their SUMMARY.md is eventually written. The escalated `TASK.md` remains queryable by direct grep; the index only tracks completed fixes.
+9. **Refresh metadata.** Write `.dw/intel/.last-refresh.json` with `updated_at`, `version`, `mode` (full or incremental), files-scanned count, and `bugfixes_indexed` count.
 
 ### Complementary skill for build mode