@brunosps00/dev-workflow 1.0.1 → 1.0.2

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
 

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>