@brunosps00/dev-workflow 1.0.0 → 1.0.2

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

@@ -0,0 +1,92 @@
+<system_instructions>
+You are a session-handoff agent. Your job is to consolidate the current session's mental state into `.dw/STATE.md` so the next session (yours or a teammate's) can resume without losing context.
+
+## When to Use
+- Use when the user says "pause work", "end session", "I need to stop for now", "save what we're doing"
+- Use proactively before a long break, before switching projects, or before a context window is about to be compacted
+- Do NOT use mid-task when nothing has been decided or learned (nothing to consolidate)
+- Do NOT use as a substitute for `/dw-commit` — STATE.md is mental state, not code changes
+
+## Pipeline Position
+**Predecessor:** any working session | **Successor:** `/dw-resume` (in a future session)
+
+## What this command does NOT do
+- It does NOT commit code (use `/dw-commit`)
+- It does NOT replace per-PRD `MEMORY.md` (workflow memory for a single feature lives there; `dw-memory` skill manages it)
+- It does NOT promote anything to ADRs (use `/dw-adr` for durable architectural decisions)
+
+## File Location
+- Single artifact: `.dw/STATE.md` (project-level, not per-PRD)
+- Template: `.dw/templates/state-template.md` (used only on first creation)
+
+## Workflow
+
+### 1. Ensure STATE.md exists
+- If `.dw/STATE.md` is missing, copy `.dw/templates/state-template.md` to `.dw/STATE.md`. Notify in chat: "STATE.md not found — initialized from template."
+- If `.dw/templates/state-template.md` is also missing (very old project), create a minimal STATE.md with the required sections (Open Loops, Decisions, Blockers, Todos, Deferred Ideas, Lessons, Preferences, Notes).
+
+### 2. Survey the session
+Read the conversation context and identify, **without inventing**:
+
+- **Open loops**: tasks/work started but not finished (e.g. "PRD `prd-foo` is at TechSpec stage, awaiting user approval"; "Task 3 of `prd-bar` failing on lint")
+- **Decisions made**: choices the user and agent agreed on during the session that affect future work
+- **Blockers encountered**: things that stopped forward motion (waiting on input, broken tooling, knowledge gap)
+- **Todos** mentioned in passing that don't yet have a PRD or task file
+- **Ideas explored and parked** (with the reason for parking)
+- **Lessons learned** — small operational lessons worth recording
+- **Preferences expressed** — conventions the user wants applied going forward
+
+### 3. Merge into STATE.md
+
+<critical>NEVER overwrite STATE.md blindly. Read the existing file, parse the sections, and merge: append new items, do not delete old ones unless the user explicitly asked you to.</critical>
+
+Rules:
+- Each new entry gets a date prefix `YYYY-MM-DD` (use today's date).
+- Use bullet lists. Keep each item to one line where possible; two lines if context is essential.
+- If a section ends up with `_none_` placeholder and you have nothing to add, keep `_none_`.
+- Update the `last_paused` frontmatter field to today's date (YYYY-MM-DD).
+
+### 4. Compaction pass (when STATE.md is large)
+
+If after merging STATE.md exceeds **~6KB** or any single section exceeds **20 items**, compact:
+
+- **Open Loops resolved during the session**: remove them.
+- **Todos completed during the session**: remove them.
+- **Decisions older than 30 days that have been formalized into ADRs or constitution**: remove (the ADR is the durable record).
+- **Lessons older than 60 days**: keep only those still relevant; drop dated tactical advice.
+- **Deferred Ideas older than 90 days with no revisit trigger**: ask the user before dropping.
+
+If compaction removes more than 5 items, list them in chat so the user can veto.
+
+### 5. Report
+
+Present a brief summary to the user:
+
+```
+## Session Paused
+
+Updated `.dw/STATE.md`:
+- Open Loops: +N (now: X total)
+- Decisions: +N
+- Blockers: +N (Y unresolved)
+- Todos: +N (Z total)
+- Deferred: +N
+
+[If compaction ran: lines removed and why]
+
+Resume with `/dw-resume` next session.
+```
+
+## Required Behavior
+
+<critical>NEVER fabricate state. If you don't see evidence of a blocker or decision in the conversation, don't add it. Empty sections are fine.</critical>
+
+<critical>NEVER touch per-PRD memory files (`.dw/spec/*/MEMORY.md`, `.dw/spec/*/tasks/*_memory.md`). Those are managed by `dw-memory` skill and are PRD-local.</critical>
+
+<critical>NEVER drop user content silently. If you compact, you list what you removed.</critical>
+
+## Inspired by
+
+This command adapts the session-handoff pattern 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, Felipe Rodrigues). Adaptations: `.dw/STATE.md` location instead of `.specs/project/STATE.md`, explicit compaction protocol, frontmatter with `last_paused` / `last_resumed` for ordering signals, complementarity with the existing `dw-memory` skill.
+
+</system_instructions>

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

@@ -19,6 +19,8 @@ You are the QA orchestrator. Two modes: run QA against the implementation (UI or
 | `/dw-qa --fix` | QA pass followed by an iterative fix+retest loop. Each detected bug → root-cause → fix → retest with evidence → mark resolved. Continues until all bugs marked Closed or user accepts a deferred list. |
 | `/dw-qa --api` | Forces API-only mode (skips UI even when frontend dependencies are present). Useful for backend-only sub-features in fullstack repos. |
 | `/dw-qa --ai` | Adds AI feature evaluation against the reference dataset at `.dw/eval/datasets/<feature>/`. Computes precision@k / faithfulness / outcome accuracy per the feature type. Logs JSONL to `QA/logs/ai/`. |
+| `/dw-qa --uat` | **Interactive UAT walkthrough.** The agent walks the user through the feature step-by-step, asking targeted questions ("does this match expectation?", "what's the expected behavior in case X?"). No Playwright auto-driving, no AI eval. Output: `QA/uat-report.md`. Used after `--fix` (or instead of `/dw-qa` for primarily-judgment-bound features). |
+| `/dw-qa --bugfix <NNN-slug>` | Targets a bugfix at `.dw/bugfixes/NNN-slug/` instead of a PRD. Runs the standard QA flow scoped to the files touched by the fix; output written to `.dw/bugfixes/NNN-slug/QA/`. Combines with `--fix`/`--api`/`--ai`/`--uat`. |
 
 ## Mode auto-detection
 
@@ -32,8 +34,17 @@ The default `/dw-qa` inspects the project to choose UI vs API:
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to PRD directory containing tasks (auto-detect from active branch if omitted) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--fix` / `--api` / `--ai` (optional; default = auto-detect) | — |
+| `{{PRD_PATH}}` | Path to PRD directory containing tasks (auto-detect from active branch if omitted; ignored when `--bugfix` is used) | `.dw/spec/prd-invoice-export` |
+| `{{BUGFIX_SLUG}}` | Bugfix slug when `--bugfix` flag is used | `001-login-not-working` |
+| `{{MODE}}` | `--fix` / `--api` / `--ai` / `--uat` / `--bugfix <slug>` (optional; default = auto-detect, target = PRD) | — |
+
+## Target Resolution
+
+Compute `<target>` ONCE at the start; substitute it wherever you see `<target>` below.
+
+1. **PRD target (default):** `<target>` = `{{PRD_PATH}}`. Artifacts read: `prd.md` (FRs), `techspec.md`, `tasks.md`, per-task files. Output written to `<target>/QA/`.
+
+2. **Bugfix target (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artifacts read: `TASK.md` (numbered tasks + files touched), `fix-report.md` (verify evidence + reproduction trace), `SUMMARY.md`. QA is scoped to the files in the `Files Touched` table and the adjacent surfaces those files expose. Output written to `<target>/QA/`. The `qa-report.md` produced here is shorter — there are at most 5 tasks and a single root-cause to validate, not a full FR matrix.
 
 ## Complementary Skills
 
@@ -50,19 +61,20 @@ When available under `./.agents/skills/`, these are invoked operationally:
 ## Output Structure
 
 ```
-.dw/spec/<prd>/QA/
-├── qa-report.md                  # Test plan + execution summary
-├── bugs.md                       # Bug catalog with status
+<target>/QA/                          # <target> = .dw/spec/<prd>/ OR .dw/bugfixes/<NNN-slug>/
+├── qa-report.md                      # Test plan + execution summary
+├── bugs.md                           # Bug catalog with status
+├── uat-report.md                     # (--uat mode only) Walkthrough log + user observations
 ├── scripts/
-│   ├── ui/<RF>-<slug>.spec.ts    # Playwright scripts (UI mode)
-│   ├── api/<RF>-<slug>.http      # API test files
-│   └── ai/<feature>-eval.ts      # AI eval scripts (--ai mode)
+│   ├── ui/<RF>-<slug>.spec.ts        # Playwright scripts (UI mode)
+│   ├── api/<RF>-<slug>.http          # API test files
+│   └── ai/<feature>-eval.ts          # AI eval scripts (--ai mode)
 ├── evidence/
-│   ├── ui/                       # Screenshots per RF + retests
+│   ├── ui/                           # Screenshots per RF + retests
 │   └── ...
 └── logs/
-    ├── api/<RF>-<slug>.log       # JSONL request/response per call
-    └── ai/<feature>-<date>.jsonl # AI eval results
+    ├── api/<RF>-<slug>.log           # JSONL request/response per call
+    └── ai/<feature>-<date>.jsonl     # AI eval results
 ```
 
 ## Mode 1: Default (`/dw-qa`)
@@ -105,6 +117,70 @@ When available under `./.agents/skills/`, these are invoked operationally:
 4. Compare to prior run's JSONL — alert on >10% regression in any metric.
 5. Append AI-mode section to `qa-report.md`.
 
+## Mode 1.5: Interactive UAT (`/dw-qa --uat`)
+
+The UAT mode is a **human-in-the-loop walkthrough**. There is no Playwright auto-driving and no AI eval. The agent is the navigator; the user is the verifier. Use this when behavior is judgment-bound — a redesign, a content-heavy flow, a new flow whose acceptance criteria are partly aesthetic, or a bugfix whose user-facing manifestation needs a human eye to confirm.
+
+### Pre-flight
+
+1. **Bugfix target:** read `<target>/SUMMARY.md` → Symptom + Resolution. The walkthrough is the reproduction trace from `fix-report.md` (before → after), now confirmed live.
+2. **PRD target:** read `<target>/prd.md` → for each FR, draft a one-line "what should you see when X happens?" question.
+3. Start the project's dev server (or instruct the user to start it if it needs interactive credentials).
+
+### Walkthrough loop
+
+For each FR (PRD target) or each numbered task in `TASK.md` (bugfix target):
+
+1. **Agent describes the next step in plain words.** Example: "Open `/invoices/export` while logged in as a viewer. The export button should be disabled and a tooltip should explain why."
+2. **User performs the step in their browser/app** and reports what they observed.
+3. **Agent asks one targeted follow-up** matched to the FR/task — never more than one open question at a time:
+   - "Does the disabled state visually communicate why? (text, icon, contrast — your call)"
+   - "If you tab to the button, does the tooltip become accessible via keyboard?"
+   - "What happened in the network panel?" (only if a backend behavior is relevant)
+4. **Agent records the answer verbatim** in `uat-report.md` under that FR/task's section. No interpretation, no rephrasing.
+5. **Agent flags a finding** when the user reports unexpected behavior. The finding goes into `bugs.md` with `source: uat` and `severity: <user's choice>`.
+6. **Repeat until all FRs / numbered tasks have been walked.**
+
+### Output
+
+Save to `<target>/QA/uat-report.md`:
+
+```markdown
+# UAT Walkthrough — <target>
+
+Date: YYYY-MM-DD
+Walked by: <user identifier or "user">
+Browser/env: <as reported>
+
+## FR-1.1 (or Task 1) — <one-line scope>
+
+- Step: <what agent asked>
+- User observation: <verbatim>
+- Verdict: PASS / FAIL / NEEDS-DESIGN-INPUT
+- Notes: <any follow-up>
+
+## FR-1.2 (or Task 2) — ...
+...
+
+## Summary
+
+- Walked: N FRs / tasks
+- PASS: N
+- FAIL: N (cross-ref bugs.md entries with source:uat)
+- NEEDS-DESIGN-INPUT: N (no bug; the spec was under-defined here)
+```
+
+### Required behavior
+
+<critical>
+- NEVER auto-drive the browser in `--uat` mode. The user navigates; you observe.
+- NEVER paraphrase the user's observation. Quote verbatim under each FR/task.
+- NEVER mark a finding as a bug without the user's explicit "yes, that's a bug" — UAT findings can also surface unclear specs (NEEDS-DESIGN-INPUT), which are not bugs.
+- Cap each FR's section at one open question per turn. UAT is interactive, not interrogation.
+</critical>
+
+UAT composes with `--bugfix <slug>` (walks the regression test path with the user instead of FRs) and with `--fix` (after a fix lands, UAT is the human green-light before commit).
+
 ## Mode 2: Fix loop (`/dw-qa --fix`)
 
 ### Behavior

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

@@ -0,0 +1,90 @@
+<system_instructions>
+You are a session-resumption agent. Your job is to read `.dw/STATE.md`, orient yourself and the user, and route to the most useful next step. This command is the inverse of `/dw-pause`.
+
+## When to Use
+- Use when the user says "resume work", "continue", "where did we stop?", "pick up where we left off", or starts a new session in an existing project
+- Use proactively at the start of any session that lands in a project with a non-empty `.dw/STATE.md` and the user hasn't yet stated an intent
+
+## Pipeline Position
+**Predecessor:** `/dw-pause` (previous session) | **Successor:** depends on what's open (typically `/dw-run --resume`, `/dw-bugfix`, `/dw-plan`, `/dw-qa`, or `/dw-review`)
+
+## File Location
+- Read-only target: `.dw/STATE.md`
+- Cross-reference: `.dw/spec/` (list active PRDs), `.dw/bugfixes/` (list open bugfixes), `.dw/incidents/` (if any)
+
+## Workflow
+
+### 1. Read STATE.md
+- If `.dw/STATE.md` is missing, report: "No paused state found — this looks like a fresh session. Run `/dw-help` for next steps." Stop here.
+- If `STATE.md` exists but every section is `_none_`, report: "STATE.md is empty — nothing to resume. Tell me what you want to do."
+
+### 2. Cross-reference with disk
+Verify that the state still matches the filesystem:
+
+- For each Open Loop referencing a PRD path, run `ls` on `.dw/spec/<slug>/`. If missing, flag `[stale: PRD not found]` and ask if the user wants it removed.
+- For each Open Loop referencing a bugfix slug, check `.dw/bugfixes/<NNN-slug>/`.
+- For each Blocker referencing an external system, do not verify — just surface it.
+- If `last_paused` in frontmatter is more than 14 days old, surface this prominently (state may be stale).
+
+### 3. Produce TLDR
+
+Present a concise summary, **not the raw STATE.md**:
+
+```
+## Where you left off
+
+Last paused: YYYY-MM-DD (Nd ago)
+
+### Open Loops (N)
+- [path or label] — next: <one-line next action> [<status flag if stale>]
+- ...
+
+### Blockers (N unresolved)
+- [label] — waiting on <X>
+
+### Top Todos (up to 5)
+- ...
+
+[Decisions, Lessons, Preferences — only mention if relevant to active loops]
+```
+
+Keep the TLDR under 30 lines. If STATE.md has more, summarize and offer `cat .dw/STATE.md` as a follow-up.
+
+### 4. Suggest the next step
+
+Based on the TLDR, route to a concrete command. Use these heuristics:
+
+| Strongest signal in STATE.md | Suggested command |
+|------------------------------|-------------------|
+| Open Loop on a PRD at `tasks/` stage | `/dw-run --resume` |
+| Open Loop on a PRD at `techspec` stage | `/dw-plan techspec` |
+| Open Loop on a PRD at `prd` stage | `/dw-plan tasks` (if PRD approved) or continue PRD |
+| Open Loop on a bugfix slug | `/dw-bugfix --resume <slug>` or `/dw-qa --bugfix <slug>` |
+| Blocker waiting on external input | Suggest the user resolve the blocker first |
+| Only Todos and Decisions, no active work | Ask the user what they want to start |
+
+Phrase the suggestion as a question, not an order:
+
+```
+Want me to <suggested command>?
+- yes → I'll run it
+- no, <other intent> → tell me what instead
+```
+
+### 5. Update STATE.md frontmatter
+
+Set `last_resumed` to today's date (YYYY-MM-DD). Do not modify section content — that's the user's call now that the session is back.
+
+## Required Behavior
+
+<critical>NEVER auto-execute the suggested command. `/dw-resume` only proposes; the user confirms before any `/dw-run`, `/dw-plan`, or `/dw-bugfix` fires.</critical>
+
+<critical>NEVER fabricate stale-detection results. If you didn't run `ls`, don't report the file exists or doesn't exist.</critical>
+
+<critical>NEVER dump the full STATE.md into the chat. Summarize. Long state files mean compaction is needed — suggest `/dw-pause` to compact next time.</critical>
+
+## Inspired by
+
+This command adapts the session-handoff pattern 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, Felipe Rodrigues). Adaptations: routing heuristics map STATE.md content to specific `dw-*` commands; cross-reference with `.dw/spec/` and `.dw/bugfixes/` to detect staleness; never auto-execute.
+
+</system_instructions>

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

@@ -15,16 +15,28 @@ You are the review orchestrator. Runs both Level 2 (PRD compliance / coverage) a
 
 | Invocation | What runs |
 |------------|-----------|
-| `/dw-review` | **Default.** Level 2 (PRD coverage) + Level 3 (code quality) in sequence. Consolidated report saved to `.dw/spec/<prd>/QA/review-consolidated.md`. |
-| `/dw-review --coverage-only` | Only Level 2 — maps every PRD requirement to the code that delivers it. Skips code quality. |
-| `/dw-review --code-only` | Only Level 3 — code quality / convention / security checks. Skips PRD mapping. |
+| `/dw-review` | **Default.** Level 2 (PRD coverage) + Level 3 (code quality) in sequence. Consolidated report saved to `<target>/QA/review-consolidated.md` (target resolves to PRD dir or bugfix dir; see Target Resolution). |
+| `/dw-review --coverage-only` | Only Level 2 — maps every PRD requirement (or bugfix scope) to the code that delivers it. Skips code quality. |
+| `/dw-review --code-only` | Only Level 3 — code quality / convention / security checks. Skips PRD/scope mapping. |
+| `/dw-review --bugfix <NNN-slug>` | Targets a bugfix at `.dw/bugfixes/NNN-slug/` instead of a PRD. Level 2 maps the bugfix scope (TASK.md + fix-report.md + SUMMARY.md) to the code that delivers the fix; Level 3 checks the diff. Output: `.dw/bugfixes/NNN-slug/review/`. |
 
 ## Inputs
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to PRD directory (auto-detect from active branch if omitted) | `.dw/spec/prd-invoice-export` |
-| `{{MODE}}` | `--coverage-only` / `--code-only` (optional; default = both) | — |
+| `{{PRD_PATH}}` | Path to PRD directory (auto-detect from active branch if omitted; ignored when `--bugfix` is used) | `.dw/spec/prd-invoice-export` |
+| `{{BUGFIX_SLUG}}` | Bugfix slug when `--bugfix` flag is used | `001-login-not-working` |
+| `{{MODE}}` | `--coverage-only` / `--code-only` / `--bugfix <slug>` (optional; default = both, target = PRD) | — |
+
+## Target Resolution
+
+The review runs against one of two target kinds. Compute `<target>` ONCE at the start; substitute it wherever you see `<target>` below.
+
+1. **PRD target (default):** `<target>` = `{{PRD_PATH}}` (auto-detected from active branch when omitted). Artifacts read: `prd.md`, `techspec.md`, `tasks.md`, `tasks/<N>_task.md`, `tasks-validation.md`. Output written to `<target>/QA/`. Filenames: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+2. **Bugfix target (`--bugfix <slug>`):** `<target>` = `.dw/bugfixes/<slug>/`. Artifacts read: `TASK.md` (the fix plan with numbered tasks 1..≤5), `fix-report.md` (verify evidence), `SUMMARY.md` (one-page record). There are no FRs in the PRD sense — instead, each numbered task in `TASK.md` is the unit of coverage. Output written to `<target>/review/`. Filenames: `review-coverage.md`, `dw-code-review.md`, `review-consolidated.md`.
+
+When the bugfix target is used, the Coverage mapping (Level 2) operates on the numbered tasks from `TASK.md` (not FR-N.M); a task is DELIVERED when (a) the files it claimed to touch are in the diff and (b) the regression test referenced in `fix-report.md` exists and runs. Orphan code in bugfix mode is anything in the diff that does not correspond to a numbered task — a strong signal the safety valve should have escalated to `/dw-plan`.
 
 ## Complementary Skills
 
@@ -59,10 +71,8 @@ When available under `./.agents/skills/`, these are invoked as analytical suppor
 ### Behavior
 
 1. **Load artifacts:**
-   - `.dw/spec/<prd>/prd.md` → extract functional requirements.
-   - `.dw/spec/<prd>/techspec.md` → extract architectural decisions.
-   - `.dw/spec/<prd>/tasks.md` + per-task files → extract committed work.
-   - `tasks-validation.md` → carry forward dimension status.
+   - **PRD target:** `<target>/prd.md` → extract functional requirements. `<target>/techspec.md` → extract architectural decisions. `<target>/tasks.md` + per-task files → extract committed work. `<target>/tasks-validation.md` → carry forward dimension status.
+   - **Bugfix target:** `<target>/TASK.md` → extract the numbered tasks (1..≤5) and their target files. `<target>/fix-report.md` → extract the verify evidence and the regression test reference. `<target>/SUMMARY.md` → extract Symptom, Root Cause, Files Touched, Verification.
 
 2. **Map each FR to code:**
    - For each `FR-N.M`, find code that delivers it (file path + line range + commit SHA).
@@ -78,7 +88,7 @@ When available under `./.agents/skills/`, these are invoked as analytical suppor
 
 ### Output
 
-Saved to `.dw/spec/<prd>/QA/review-coverage.md`:
+Saved to `<target>/QA/review-coverage.md` (PRD target) or `<target>/review/review-coverage.md` (bugfix target):
 
 ```markdown
 # Coverage Review
@@ -145,14 +155,14 @@ If MISSING > 0, the verdict suggests revisiting `/dw-plan tasks` to scope or `/d
 
 ### Output
 
-Saved to `.dw/spec/<prd>/QA/dw-review --code-only.md`. The verdict line is one of:
+Saved to `<target>/QA/dw-code-review.md` (PRD target) or `<target>/review/dw-code-review.md` (bugfix target). The verdict line is one of:
 - **APPROVED** — all gates green; ready for commit + PR.
 - **APPROVED WITH CAVEATS** — green but findings worth fixing in follow-up (filed with severities).
 - **REJECTED** — at least one hard gate failed. Specify which.
 
 ## Consolidated output (default mode)
 
-When both levels run, a consolidated report at `.dw/spec/<prd>/QA/review-consolidated.md`:
+When both levels run, a consolidated report at `<target>/QA/review-consolidated.md` (PRD target) or `<target>/review/review-consolidated.md` (bugfix target):
 
 ```markdown
 # Consolidated Review

package/scaffold/en/templates/bugfix-summary-template.md

@@ -0,0 +1,66 @@
+---
+schema_version: "1.0"
+slug: ""
+created: ""
+status: "Fixed | In Review | QA Pending | Reverted"
+severity: "Low | Medium | High"
+related_concerns: []
+---
+
+# Bugfix Summary — {{NNN}}-{{slug}}
+
+One-page record of a bugfix. Sibling files in this directory:
+
+- `TASK.md` — the original triage, clarification answers, and the fix plan that ran
+- `fix-report.md` — verification evidence (`dw-verify` PASS output, reproduction proof, regression test run)
+- `review/` — populated by `/dw-review --bugfix {{NNN}}-{{slug}}`
+- `QA/` — populated by `/dw-qa --bugfix {{NNN}}-{{slug}}` (when applicable)
+
+## Symptom
+
+What the user observed. Quote the original bug description verbatim; do not paraphrase.
+
+> _"…"_
+
+## Root Cause
+
+What was actually broken, in a single sentence. Not the symptom — the cause.
+
+_…_
+
+## Resolution
+
+What changed, in 2-4 bullets. File paths, not snippets.
+
+- _change 1_
+- _change 2_
+
+## Files Touched
+
+Full list, including tests. ≤5 — if more, the safety valve should have escalated to `/dw-plan`.
+
+| Path | Change |
+|------|--------|
+| `src/foo/bar.ts` | _surgical fix to X_ |
+| `src/foo/bar.test.ts` | _regression test added_ |
+
+## Verification
+
+How the fix was proven, beyond "tests pass".
+
+- **Reproduction before fix:** _step that triggered the bug, captured_
+- **Reproduction after fix:** _same step, now passes_
+- **Regression test:** _name + path_
+- **Verify report:** `fix-report.md`
+
+## Related
+
+- **Concerns touched:** _refs from `.dw/rules/concerns.md` if the fix landed in a flagged area_
+- **Adjacent bugfixes:** _slugs of prior fixes in the same module, if any_
+- **PRD context:** _if the bug surfaced inside a feature in flight, link to its PRD path_
+
+## Followups
+
+Open loops this fix surfaced but did not resolve. Add to `.dw/STATE.md` Open-Loops on close.
+
+- _none_

package/scaffold/en/templates/concerns-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+generated_by: dw-analyze-project (Step 9)
+last_refreshed: ""
+---
+
+# Concerns — Risk Map
+
+Risk map for this codebase. Not conventions ("how we do things" — that's `.dw/rules/`), not architecture ("how it's built" — that's `.dw/intel/arch.md`). This file answers a single question: **where is it dangerous to mess around?**
+
+Loaded on-demand by `/dw-plan`, `/dw-run`, and `/dw-bugfix` when their target touches an entry below. Auto-installed by `/dw-analyze-project` Step 9; never blocks (absence = no flagged areas yet).
+
+## Hot Spots
+
+Files or modules with high churn, frequent bug reports, or repeated "I touched this and broke something" history. Mention them in PRDs that touch the same area; add an extra reviewer or extra test pass.
+
+| Path | Why it's hot | First flagged | Last incident |
+|------|--------------|---------------|---------------|
+| _e.g. `src/auth/session.ts`_ | _3 token-handling fixes in 60d_ | _YYYY-MM-DD_ | _YYYY-MM-DD_ |
+
+## Fragile Integrations
+
+External systems (APIs, queues, vendors, legacy databases) that have a track record of silent failures, schema drift, rate-limit surprises, or undocumented behavior. New code touching them needs explicit retry/timeout/idempotency handling.
+
+| Integration | Failure mode | Mitigation expected |
+|-------------|--------------|---------------------|
+| _e.g. legacy SAP export_ | _silent 200 OK with empty body when source is locked_ | _check body length; log and alert_ |
+
+## Hostile Code
+
+Specific functions, regexes, parsers, or algorithms that are hard to reason about — anyone touching them should fully understand them first (or rewrite, not patch). Common offenders: hand-rolled regex, ad-hoc string parsers, custom serializers, race-prone async, manual transaction code.
+
+| Path / function | Why it's hostile | Owner / context |
+|-----------------|------------------|-----------------|
+| _e.g. `src/billing/parseInvoice.ts:parseLine`_ | _900-char regex with 12 alternatives, no comments_ | _Bruno wrote it in 2024; rewrite if it breaks_ |
+
+## Known Bug History
+
+Aggregated from `.dw/bugfixes/*/SUMMARY.md` by `/dw-intel --build`. Lists modules with ≥2 historical fixes. Read alongside Hot Spots when planning related work.
+
+| Module | Bug count | Recent slugs |
+|--------|-----------|--------------|
+| _e.g. `src/payments/`_ | _4_ | _002-stripe-webhook-retry, 007-refund-rounding_ |
+
+## Tech Debt — Acknowledged
+
+Pieces of debt the team has agreed exist. Not to be cleaned up opportunistically without coordination — they may be load-bearing in ways that aren't obvious.
+
+| Area | Debt description | Why it stays | Cleanup trigger |
+|------|------------------|--------------|-----------------|
+| _e.g. `src/legacy/userMapper.ts`_ | _Two parallel field-mapping codepaths_ | _Awaiting v3 API migration_ | _Q3 2026 after vendor cutover_ |
+
+---
+
+**How to maintain this file:**
+
+- `/dw-analyze-project` rewrites this on each run. Hand-written entries between `<!-- preserved:start -->` and `<!-- preserved:end -->` markers are kept.
+- When a bugfix surfaces a new dangerous area, add it manually under Hot Spots and let the next analyze rerun confirm it.
+- Promote entries to `.dw/constitution.md` when they become non-negotiable rules ("never touch X without an ADR").

package/scaffold/en/templates/state-template.md

@@ -0,0 +1,59 @@
+---
+schema_version: "1.0"
+last_paused: ""
+last_resumed: ""
+---
+
+# Session State
+
+Cross-session working memory. Lightweight index of what is in flight, what was decided, what is parked. Updated by `/dw-pause` (consolidates) and read by `/dw-resume` (orients).
+
+Unlike per-PRD `MEMORY.md` (workflow memory for one feature) or ADRs (durable architectural records), this file lives at the project level and survives across PRDs, branches, and sessions. Edit it freely between pauses.
+
+## Open Loops
+
+What is currently in flight — work started but not finished. Each entry: short label + path/target + next concrete action.
+
+- _none_
+
+## Decisions
+
+Cross-cutting decisions that haven't been promoted to an ADR yet (because they don't warrant one, or because the formalization is deferred). Format: `YYYY-MM-DD — decision — context (1 line)`.
+
+- _none_
+
+## Blockers
+
+What's preventing forward motion. External (waiting on someone), internal (knowledge gap), or technical (broken tooling). Each entry: short label + what's blocked + owner / unblock condition.
+
+- _none_
+
+## Todos
+
+Small follow-ups that don't justify a full PRD or task file. One line each. Cleared as they get done or migrated to a PRD.
+
+- _none_
+
+## Deferred Ideas
+
+Ideas you considered but parked. Capture so they aren't lost; revisit when scope changes. Each entry: idea + reason it was parked + revisit trigger (if known).
+
+- _none_
+
+## Lessons
+
+Small lessons learned during recent work — patterns that worked, gotchas, "next time I'll …". Not architectural (those go to ADRs); operational.
+
+- _none_
+
+## Preferences
+
+Conventions agreed during work that affect how the agent should behave going forward. Examples: "always run `pnpm typecheck` before commit", "prefer named exports over default exports for utils".
+
+- _none_
+
+## Notes
+
+Free-form scratchpad. Optional.
+
+- _none_

package/scaffold/pt-br/agent-instructions.md

@@ -5,11 +5,27 @@ Este projeto usa [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@bru
 
 **Objetivo deste arquivo:** quando o usuário expressar uma intenção que casa com a Trigger Map abaixo, rode o comando `dw-*` correspondente **sem pedir permissão** — exceto se a mudança for genuinamente trivial (veja Escape Hatches).
 
+## Matriz de Auto-Sizing
+
+Antes de escolher um comando da Trigger Map, dimensione o escopo real da mudança. A mesma intenção ("conserta isso", "adiciona isso") pode significar quantidades muito diferentes de trabalho; a matriz nomeia quatro tamanhos e roteia cada um para uma entrada diferente. **Escolha o menor que cabe — sub-rotear desperdiça cerimônia, super-rotear esconde o escopo.**
+
+| Tamanho | Como se parece | Rotear para |
+|---------|----------------|-------------|
+| **Pequeno** | ≤3 arquivos, sem migration, sem novo endpoint, descritível em uma frase. Exemplos: typo, log message, config de uma linha, bump de dependência, version pin. | Faça inline. Nenhum comando `dw-*`. |
+| **Médio** | Feature ou bug claro, <10 tasks numeradas esperadas, único componente ou serviço, sem decisões arquiteturais. Exemplos: adicionar campo de form com validação, corrigir regressão em módulo conhecido, ligar novo endpoint num handler existente. | `/dw-bugfix` (bugs) ou `/dw-plan` (features) — direto, não via `/dw-autopilot`. |
+| **Grande** | Feature multi-componente, ≥10 tasks esperadas, toca múltiplos módulos, tem superfície UX user-visible E backend. Exemplos: adicionar nova entidade end-to-end (model + migration + API + UI), introduzir integração de terceiro, redesenhar fluxo. | `/dw-autopilot "<wish>"` — pipeline completo PRD → TechSpec → Tasks → Run → QA → Review → Commit → PR com três gates. |
+| **Complexo** | Domínio novo, requisitos ambíguos, decisão arquitetural exigida, superfície regulatória ou de compliance, ou escopo que cruza múltiplos PRDs. Exemplos: introduzir event sourcing, reconstruir auth, multi-tenancy, nova linha de produto. | `/dw-brainstorm "<ideia>"` primeiro (auto-dispatch de modos research/council), depois `/dw-plan --council` para a etapa de techspec rodar o debate multi-advisor. |
+
+**Safety valve:** se você começou em Pequeno ou Médio mas o trabalho revela que é Grande de fato (a listagem inline passa de 5 passos, ou `/dw-bugfix` dispara seu `Step 5.0`), PARE e escale. Não existe flag para bypass. Escalar é o desfecho correto.
+
+**Adaptado de** [`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). A matriz de quatro tamanhos é de lá; o mapeamento para comandos `dw-*` é específico do dev-workflow.
+
 ## Trigger Map
 
 | Intenção do usuário (literal ou parafraseada) | Auto-trigger |
 |------------------------------------------------|--------------|
 | "Implementa X" / "Cria Y" / "Adiciona feature Z" / "Preciso de..." | `/dw-autopilot "X"` |
+| "Autopilota esse PRD" / "Leva esse PRD pra PR" / continua escalação de bugfix autonomamente | `/dw-autopilot --from-prd <slug>` (PRD existente em `.dw/spec/<slug>/`) |
 | Erro colado / "X está quebrado" / "Bug em Y" / screenshot de teste falhando | `/dw-bugfix "X"` |
 | "Planeja essa feature" / "Escreve PRD + techspec + tasks" | `/dw-plan "X"` |
 | "Escreve PRD pra X" / "Especifica Y" | `/dw-plan prd "X"` |
@@ -18,17 +34,20 @@ Este projeto usa [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@bru
 | "Roda essa task" (com ID da task) | `/dw-run <ID>` |
 | "Roda todas as tasks pendentes" / "Executa o plano" | `/dw-run` |
 | "Continue de onde parei" | `/dw-run --resume` |
+| "Pausa o trabalho" / "Encerra a sessão" / "Salva onde paramos" | `/dw-pause` |
+| "Retoma" / "Onde paramos?" / "Volta de onde parei" | `/dw-resume` |
 | "QA dessa feature" / "Roda o test plan" | `/dw-qa` |
 | "Corrige os bugs do QA" | `/dw-qa --fix` |
 | "Avalia a feature AI" / "Testa o RAG / classifier" | `/dw-qa --ai` |
+| "Caminha comigo pela feature" / "UAT comigo" / "Vamos fazer um run-through manual" | `/dw-qa --uat` |
+| "Revisa esse bugfix" / "Code-review do fix `<slug>`" | `/dw-review --bugfix <slug>` |
+| "QA desse bugfix" / "Valida o fix `<slug>`" | `/dw-qa --bugfix <slug>` |
 | "Revisa meu PR" / "Checa qualidade" / "Tá pronto pra subir?" | `/dw-review` |
 | "Só checagem de cobertura PRD" | `/dw-review --coverage-only` |
 | "Só code review qualidade" | `/dw-review --code-only` |
 | "Hora de commitar" / mudanças validadas e prontas | `/dw-commit` |
 | "Abre um PR" / "Sobe isso" | `/dw-generate-pr` |
-| "Brainstorm X" / "Explora ideias" | `/dw-brainstorm "X"` |
-| "Research X" / "Compara A vs B com citações" | `/dw-brainstorm --research "X"` |
-| "Auditoria de saúde do código" / "Tech debt" / "Oportunidades de refactor" | `/dw-brainstorm --refactor` |
+| "Brainstorm X" / "Explora ideias" / "Research X" / "Auditoria de saúde do código" / "Tech debt" | `/dw-brainstorm "X"` (auto-dispatch dos modos grill / prototype / council / research / refactor-audit / onepager conforme os sinais) |
 | "Onde está X?" / "O que usa Y?" / "Como Z é estruturado?" | `/dw-intel "<pergunta>"` |
 | "Reconstrói o índice" / "Refresh do intel" | `/dw-intel --build` |
 | "Redesign dessa UI" / "Audita e entrega novo design" | `/dw-redesign-ui "<target>"` |
@@ -58,6 +77,12 @@ Quando qualquer destes se aplica, responda direto e **não** invoque comando `dw
 - Usuário diz explicitamente "faz direto" / "pula autopilot" / "não precisa de PRD" — honre.
 - A conversa já está dentro de um fluxo `dw-*` (você já está executando tasks; não inicie pipeline novo).
 
+## Padrão zoom-out (para áreas desconhecidas do código)
+
+Quando você cai numa área do codebase que não conhece e a orientação custa mais que a tarefa em si, **não mergulhe nos arquivos primeiro** — peça a um agente de exploração que produza um mapa. Passe o glossário de domínio do projeto (`.dw/rules/index.md`) e diga: "zoom out de um nível — me mostra os módulos relevantes, suas superfícies públicas, quem chama, e o fluxo de dados entre eles, usando o vocabulário do glossário de domínio." Pegue a visão geral, e só então mergulhe. Isso evita a armadilha de ler o arquivo mais profundo primeiro e reconstruir a arquitetura das folhas pra cima.
+
+Adaptado de [`mattpocock/skills/zoom-out`](https://github.com/mattpocock/skills/tree/main/zoom-out) (MIT).
+
 ## Referência de Workflow
 
 ```