@brunosps00/dev-workflow 2.1.0 → 2.3.0

package/scaffold/skills/dw-execute-phase/references/atomic-commits.md

@@ -1,6 +1,6 @@
-# Atomic commits — one commit per task, no exceptions
+# Scoped atomic commits
 
-Every task in a phase commits exactly once. This drives traceability (a task's diff is `git show <sha>`), revert safety (`git revert <sha>` undoes one task without affecting others), and PR clarity (`/dw-generate-pr` builds a clean changelog from the per-task commits).
+Formal tasks use atomic commits, with approved subtask milestones and final bookkeeping where specified. This drives traceability (a task's diff is `git show <sha>`), revert safety (`git revert <sha>` undoes one task without affecting others), and PR clarity (`/dw-generate-pr` builds a clean changelog from the per-task commits).
 
 ## Commit message format
 
@@ -80,17 +80,7 @@ Closes FR-7.2 (partial — full close on tasks.md completion).
 
 ## Verification before commit
 
-The executor MUST run, in order:
-
-1. **Linter** — project's lint command (`pnpm lint`, `ruff check`, `dotnet format --verify-no-changes`, `cargo clippy`).
-2. **Tests** — at minimum the tests touched by this task. Full suite if practical.
-3. **Build** — typecheck/compile (`pnpm tsc --noEmit`, `mypy`, `dotnet build`, `cargo check`).
-
-All three must pass. If any fails:
-- If the failure is in a test the task added → fix and retry (1 retry, then deviation)
-- If the failure is in unrelated code → deviation Rule 2 (ambiguity: does this task own the regression?)
-
-The executor does NOT commit unverified code. Period.
+Use `dw-verify`: complete applicable project-required checks and acceptance criteria. Reuse evidence only for equivalent inputs, environment and scope. After failure diagnose and fix in scope, rerun affected checks, and complete invalidated required gates. Do not invent lint/build scripts or repeat checks solely because a commit is next.
 
 ## Edit vs Write
 
@@ -102,13 +92,13 @@ When implementing the task:
 | Changing 1-30 lines | Replacing a file completely |
 | You have line context (the file is in your context) | The file is small and a Write is cleaner than 5 Edits |
 
-Never use `cat <<'EOF' > file` heredocs from Bash to create files. Always use Write tool.
+Use available file-editing tools safely; preserve content outside the task scope.
 
 ## Multi-file tasks
 
 If a task touches 5+ files, that's still one commit. Stage all files (`git add <list>`) then `git commit`. The body's `Files added:` / `Files modified:` lists must include every file.
 
-If a task should logically be split into separate commits (e.g., "create schema then wire it"), that's a sign the planner under-decomposed. The executor flags as Rule 2 deviation, not silently split.
+Use approved subtask commit milestones when specified. Propose only material changes to the intended task boundaries.
 
 ## Commit signing
 
@@ -121,7 +111,7 @@ If `git config commit.gpgsign true` is set, signing is on by default — let it
 - OS junk (`.DS_Store`, `Thumbs.db`)
 - Unrelated changes accidentally in the working tree (executor should `git status` before adding to confirm only the task's files)
 
-If unrelated changes are present, deviation Rule 2: pause and ask — the executor doesn't know if those are user's WIP or expected from a prior task.
+Preserve unrelated changes and stage only scoped files. Ask only when they conflict with the task or ownership cannot be determined; unrelated WIP alone is not a blocker.
 
 ## Deviation entry format (referenced from commits)
 
@@ -142,6 +132,6 @@ If unrelated changes are present, deviation Rule 2: pause and ask — the execut
 
 The plan-checker reads `deviations.md` from the previous run when re-verifying after revision — patterns of recurring Rule 1 deviations indicate the planner is missing a project convention that should be in `.dw/rules/`.
 
-## Final phase commit (handled by `/dw-commit`, not executor)
+## Final bookkeeping
 
-After all per-task commits, `/dw-generate-pr` (NOT the executor) reads them and builds the PR body. The executor never makes a "wrap-up" commit. If the phase needs a final commit (e.g., updating CHANGELOG.md), that should be the LAST task in `tasks.md` — atomic like every other.
+Record task status with the implementation, then store the resulting SHA in tasks.md/run-log. Include leftover bookkeeping in the next scoped commit or a final metadata commit through `/dw-commit`. Do not amend automatically, create empty commits, or change version/CHANGELOG without maintainer authorization. PR generation uses these commits; it is a separately authorized action.

package/scaffold/skills/dw-execute-phase/references/de-sloppify-pass-optional-cleanup-task-detail.md

@@ -0,0 +1,12 @@
+## De-Sloppify Pass (optional cleanup task)
+
+LLM implementers are thorough but leave slop — tests of framework/language behavior, defensive checks the type system already enforces, leftover `console.log`, over-handled impossible states. Constraining the implementer with "don't over-engineer" degrades its output unpredictably; a **separate cleanup pass in a fresh context** works better. Two focused agents beat one constrained agent.
+
+To request one, a task in `tasks.md` may carry `Cleanup After: <N>` in its frontmatter. The executor runs it as its own task (own commit) right after task N's wave lands, scoped to task N's diff:
+
+- Remove tests that assert language/framework behavior rather than business logic.
+- Remove type checks and guards the type system or a prior validation already guarantees.
+- Remove `console.log`/debug prints and commented-out code.
+- Keep every business-logic test and every real error path — when unsure, keep it.
+
+The cleanup task commits as `refactor(<scope>): de-slop <task N title>` and must leave the gate green (lint + tests + build) — it never changes behavior. Opt-in: no `Cleanup After:` means no cleanup task runs.

package/scaffold/skills/dw-execute-phase/references/deviation-rules-during-execution-detail.md

@@ -0,0 +1,8 @@
+# Deviations during execution
+
+Record material adjustments in deviations.md with task, reason, affected files and outcome.
+
+- Complete functionality needed to satisfy the approved requirements and applicable project constraints; do not broaden product scope.
+- Resolve discoverable ambiguity by inspecting code and previous decisions. Ask only when materially different product/architecture choices remain; block dependent work while continuing independent authorized work.
+- A conflict with a locked architectural decision requires the project's ADR/decision process. Do not silently override it.
+- Repair internal plan inconsistencies and split/reorder work within approved scope; larger estimates alone do not require approval.

package/scaffold/skills/dw-execute-phase/references/how-the-two-agents-compose-detail.md

@@ -0,0 +1,7 @@
+# Composing plan checks and execution
+
+`/dw-plan tasks` produces the task artifacts and execution assignments. Check requirement coverage, completeness, dependencies, artifact wiring, feasibility and constraints using the plan-checker protocol. The parent can perform this check locally or delegate to an approved independent reviewer; it is not a mandatory extra agent layer.
+
+After PASS, `/dw-run` executes the approved assignments in dependency order. Repair in-scope REVISE findings and recheck; surface material BLOCK decisions. Use executor profiles only when delegation helps and is available. Workers do not recursively dispatch implementation agents.
+
+After tasks, inspect/reuse a valid full review, run applicable QA, correct in-scope defects and repeat checks/review only when invalidated. `/dw-autopilot` continues this approved implementation flow without a forced second invocation. Planning-only requests end with the requested plan.

package/scaffold/skills/dw-execute-phase/references/plan-verification.md

@@ -1,158 +1,12 @@
-# Plan verification — the 6-dimension goal-backward analysis
+# Plan verification — six dimensions
 
-The `dw-plan-checker` agent verifies that a `tasks.md` will achieve the PRD goal BEFORE execution starts. This document details each dimension's checks, examples, and pass/fail criteria.
+Read when validating a planned execution. Verify expected outcomes, not literal headings or arbitrary task/file quotas. Relevant evidence may appear in the task, approved TechSpec sections or execution matrix.
 
-## Why pre-execution verification
+1. **Requirement coverage:** extract `<REQ-ID>` verbatim (`FR-N.M` in English, `RF-N.M` in Portuguese). Every required outcome must be addressed by one or more tasks; an existing implementation may satisfy it when explicitly verified.
+2. **Task completeness:** identify affected surfaces, intended behavior, verification and acceptance criteria. Schema 1.1 uses Implementation, Verification and success criteria, and Relevant files and decisions (or translated headings). These concepts are required; exact header spelling is not. Check the execution assignment and rationale, including concrete external model/effort and approved alternatives.
+3. **Dependencies:** validate `Depends on:` and execution-plan.json agree, all IDs exist, and the graph is acyclic. Queue ready tasks to respect at most 3 workers and actual host capacity. No synthetic dependencies to limit concurrency. One writer per worktree; dependent work sees dependency commits on its execution branch.
+4. **Artifact wiring:** produced services, endpoints, schemas and UI elements must be connected to their intended consumers or deliverable. Check the planned wiring, not just file existence.
+5. **Execution feasibility:** task packets should be bounded with relevant context and durable checkpoints. Large task/file counts are a reason to inspect feasibility, not an automatic failure. Parallelism is optional. Separate worktrees need an approved integration path before dependent work; otherwise execute serially on the shared execution branch.
+6. **Constraints:** check relevant project rules and locked architecture decisions within actual instruction precedence. Do not scan every skill. Security and constitution exceptions follow the project's established process.
 
-Mid-execution discovery of plan flaws is expensive: context burned, partial commits to revert, deviation logs to resolve. Pre-execution verification catches the same flaws at zero implementation cost. The trade-off: 1-2 minutes of plan-checker time vs. potentially 30+ minutes of mid-execution rework.
-
-## The 6 dimensions
-
-### 1. Requirement Coverage
-
-**Goal:** every PRD requirement (`<REQ-ID>`) has at least one task addressing it.
-
-<critical>`<REQ-ID>` is language-dependent: `FR-N.M` in English projects, `RF-N.M` in Portuguese ones. This skill is shared by both — extract the IDs verbatim from `prd.md` and match those exact strings downstream; never hardcode a prefix.</critical>
-
-**Steps:**
-1. Extract numbered requirements from `prd.md`. Pattern: `### <REQ-ID>` or `**<REQ-ID>:**` or numbered list under "Functional Requirements" / "Requisitos Funcionais".
-2. Build `Set<REQ-ID>` of expected requirements.
-3. Scan `tasks.md` and `<NN>_task.md` files for `Closes <REQ-ID>` / the `FRs`/`RFs` table column / `Requirement: <REQ-ID>` markers.
-4. Compute `uncovered = expected - addressed`.
-
-**Pass:** `uncovered` is empty.
-**Revise:** uncovered non-empty AND fixable by adding tasks.
-**Block:** PRD has no numbered requirements (`expected` is empty) — verifying intent is impossible.
-
-**Common failures:**
-- Planner forgot a non-obvious requirement (e.g., audit logging) buried in PRD prose
-- Compound requirement ("user can sign up AND verify email") only addressed for one half
-- Requirement covered indirectly but no task explicitly marks the closure
-
-### 2. Task Completeness
-
-**Goal:** each task has all four parts: files, action, verification, done criteria.
-
-**Steps:**
-For each task in `tasks.md`:
-- Open `<NN>_task.md` (or inline section)
-- Check for required sections:
-  - `## Files` (or `Files to create/modify:`) — explicit paths
-  - `## Action` (or `Implement:`) — what to do, concrete
-  - `## Verification` (or `Verify:`) — how to know it worked (linter, tests, build, manual)
-  - `## Done` (or `Done when:`) — criteria for marking `[x]`
-
-**Pass:** all four sections present in every task.
-**Revise:** ≥1 task missing one section.
-
-**Common failures:**
-- "Files: TBD" or "Files: see techspec" — too vague
-- No verification → executor can't decide when to commit
-- Done criteria absent → executor commits but can't mark `[x]` confidently
-
-### 3. Dependency Soundness
-
-**Goal:** `Depends on:` graph is acyclic, references valid, waves are reasonable.
-
-**Steps:**
-1. Parse every task's `Depends on:` field (none / comma-separated task numbers).
-2. Build directed graph (node = task, edge = depends-on relation).
-3. Topological sort:
-   - Cycle → BLOCK with the cycle path
-   - Reference to non-existent task number → REVISE with the dangling ref
-4. Compute wave widths. Any wave > 8 tasks → REVISE (split with synthetic barrier).
-
-**Pass:** topological sort succeeds, all refs valid, waves ≤ 8 wide.
-
-**Common failures:**
-- Bidirectional dependency (`02 depends on 03; 03 depends on 02`) — likely planner confusion; needs re-think
-- Typo in `Depends on: 02` when the task is actually numbered `2.5` or `03`
-- 10 independent test files all in wave 1 → split into smaller waves
-
-### 4. Artifact Wiring
-
-**Goal:** every artifact produced by a task is consumed by a downstream task OR is a leaf deliverable referenced in PRD's user stories.
-
-**Steps:**
-1. For each task, identify what it PRODUCES:
-   - New files (from `Files: + src/foo.ts`)
-   - New exports (from `Implement: export function bar()`)
-   - New endpoints (from `Action: add POST /api/baz`)
-2. For each downstream task (later in topo order), identify what it CONSUMES:
-   - Imports (from `Files: src/quux.ts (modify) — imports bar`)
-   - References (from `Action: call /api/baz`)
-3. Cross-reference: every produced artifact should be either consumed downstream OR explicitly mentioned in PRD as a user-facing deliverable.
-
-**Pass:** zero orphan artifacts.
-**Revise:** ≥1 artifact created without consumer or PRD reference — likely incomplete plan.
-
-**Common failures:**
-- Task creates a service but no task wires it into the router
-- Task creates a migration file but no task runs it (`prisma migrate deploy`)
-- Task creates a config but no task reads it
-
-### 5. Context Budget
-
-**Goal:** the phase fits in a practical execution window.
-
-**Steps:**
-1. Count tasks. Practical limit: 12 tasks per phase before quality degrades.
-2. Estimate aggregate file changes: sum of files mentioned in `Files:` across all tasks. Limit: 30 files per phase.
-3. Check parallelism setup: are wave-1 tasks running in parallel? (frontmatter `parallel: true` or default).
-
-**Pass:** ≤12 tasks, ≤30 aggregate files, wave 1 has parallel execution if multi-task.
-
-**Revise:** > 12 tasks → suggest splitting into 2 phases. > 30 files → reduce scope or split.
-
-**Common failures:**
-- Mega-phase with 20 tasks because the planner couldn't decompose
-- Single-task waves where parallelism was forgotten
-
-### 6. Constraint Compliance
-
-**Goal:** tasks honor locked decisions and project conventions.
-
-**Steps:**
-1. Read `.dw/rules/index.md` and `.dw/rules/<module>.md` for relevant modules.
-2. Read `CONTEXT.md` if exists; extract `## Decisions` (LOCKED) section.
-3. Read `./CLAUDE.md` for project hard constraints.
-4. For each task, check if its `Action` or `Files` violate:
-   - A locked decision
-   - A project rule (forbidden pattern, mandated tool)
-   - A CLAUDE.md directive
-
-**Pass:** zero violations.
-**Block:** ≥1 hard violation. The plan must change before execution.
-
-**Common failures:**
-- Locked decision says "framework: Fastify" but task says "use Express"
-- Project rules forbid raw SQL; task uses `pg.query()` directly
-- CLAUDE.md says "no env files committed"; task adds `.env.production`
-
-## Verdict resolution
-
-After running all 6 dimensions:
-
-| Outcome | Verdict |
-|---------|---------|
-| All 6 PASS | PASS — proceed to execution |
-| Any REVISE, no BLOCK | REVISE — re-plan |
-| Any BLOCK | BLOCK — surface to user, no auto-replan |
-
-`PASS` is the only state that allows `/dw-execute-phase` to proceed.
-
-## Bounded revision loop
-
-The plan-checker is part of a bounded quality loop:
-
-1. `/dw-plan tasks` produces v1 of `tasks.md`
-2. `/dw-plan-checker` runs → REVISE
-3. `/dw-plan tasks --revise` produces v2 (consumes plan-checker's issues as input)
-4. `/dw-plan-checker` runs → PASS or REVISE again
-5. After 3 revisions without reaching PASS → escalate to user (something fundamental is wrong)
-
-The escalation cap prevents infinite loops where the planner can't satisfy the verifier. At 3 strikes, the user sees the diff between PRD and the failing tasks.md and decides next step.
-
-## Time budget
-
-Plan-checker target: 1-2 minutes. The 6 dimensions are mostly file reads and grep operations; no heavy analysis. If plan-checker exceeds 5 minutes, it's a sign the agent is over-thinking — bias toward issuing REVISE for ambiguous cases rather than analyzing them deeply.
+Return PASS when all dimensions are supported; REVISE for fixable draft inconsistencies; BLOCK for unresolved material decisions, conflicts, cycles or unavailable required capabilities. The parent repairs REVISE findings within approved scope and rechecks affected dimensions. Do not restart product interviews for discoverable facts or repeat a valid plan check without changed inputs. At a real repeated impasse report evidence and the exact missing decision, preserving the draft.

package/scaffold/skills/dw-execute-phase/references/wave-coordination.md

@@ -1,102 +1,11 @@
-# Wave coordination — how the executor parallelizes tasks
+# Dependency scheduling
 
-Tasks within a phase have dependencies. Some can run in parallel; others must wait. The executor groups tasks into **waves** and runs each wave as parallel subagent dispatches, with sequential ordering between waves.
+Read for multi-task execution. Parse `Depends on:` from tasks.md and cross-check execution-plan.json. Topologically order tasks; reject cycles and missing task IDs. The installed workflow-contract helper can validate the JSON graph and return ready tasks.
 
-## Wave computation
+A wave is a set of ready tasks, not a requirement to spawn parallel agents. Run at most 3 approved workers per workstream, limited further by host capacity. Serialize writers sharing a worktree. Do not introduce fake dependencies to enforce a concurrency limit; queue ready work instead.
 
-Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task IDs).
+Dependent tasks use the same execution branch and see dependency commits before starting, even when successive tasks use different CLIs. Independent worktrees require a planned integration path before dependent work and authorization for that integration. Without it, run sequentially on the execution branch. Do not merge into the owner's branch solely to progress.
 
-Algorithm: topological sort.
+Each writer owns scoped task changes and its commit. Parent updates consolidated state after handoffs; avoid concurrent edits to shared tasks.md. Commit IDs need not follow numeric task order when tasks are independent. A failed task blocks its dependents; independent authorized tasks can continue.
 
-1. Build dependency graph: node per task, edge from each `Depends on:` to the dependent task.
-2. Cycle check: if a cycle exists → abort with `EXEC-FAILED: dependency cycle`.
-3. Wave assignment:
-   - Wave 1 = tasks with zero dependencies
-   - Wave N = tasks whose all dependencies are in waves 1..N-1
-4. Output: ordered list of waves, each wave a list of task IDs.
-
-## Example
-
-```
-tasks.md:
-- 1.0 Create user schema       Depends on: none
-- 2.0 Create user model        Depends on: 1.0
-- 3.0 Create order schema      Depends on: none
-- 4.0 Wire auth middleware     Depends on: 2.0
-- 5.0 Add login endpoint       Depends on: 4.0
-- 6.0 Add order endpoint       Depends on: 2.0, 3.0
-- 7.0 Wire validation rules    Depends on: 4.0, 6.0
-
-Computed waves:
-Wave 1: [1.0, 3.0]          (no deps; can run in parallel)
-Wave 2: [2.0]               (depends on 1.0)
-Wave 3: [4.0, 6.0]          (depend on wave 2)
-Wave 4: [5.0, 7.0]          (depend on wave 3)
-```
-
-## Parallel execution within a wave
-
-Within a wave, the executor dispatches tasks in parallel via subagent calls (one subagent per task). Each subagent:
-
-1. Reads its `<NN>_task.md`
-2. Implements
-3. Verifies (lint/tests/build)
-4. Commits atomically (per `atomic-commits.md`)
-5. Marks `[x]` in `tasks.md`
-6. Returns success or deviation status to the orchestrating executor
-
-The orchestrating executor:
-
-- Spawns N subagents in parallel (single message, N tool calls)
-- Waits for all to return
-- If all PASS → proceed to next wave
-- If ANY return deviation/blocked → resolve before next wave (see deviation rules in `agents/executor.md`)
-
-## Wave width limits
-
-Practical caps to keep context budget sane:
-
-- **Soft cap: 5 tasks per wave** — tested as the upper bound where parallel execution stays efficient
-- **Hard cap: 8 tasks per wave** — beyond this, the orchestrator's context fills with subagent results faster than tasks complete
-
-If a wave exceeds the hard cap, the planner should split: introduce a synthetic dependency to bisect the wave. Example: if Wave 3 has 10 independent tasks, force tasks 06-10 to depend on a "wave 3a barrier" so they go to Wave 3.5.
-
-The plan-checker (Dimension 5) flags wide waves before execution.
-
-## Cross-wave atomicity
-
-Each wave is a checkpoint:
-
-- After all tasks in a wave commit, run a `git status` check — should be clean (everything committed).
-- If any task in a wave failed permanently (Rule 3 deviation), abort BEFORE starting the next wave. Leave the partial work committed; surface to user via `EXEC-BLOCKED`.
-- Don't run waves N+1 with broken commits in wave N. The dependencies aren't satisfied.
-
-## Order within a wave
-
-Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task ID (1.0 commit before 2.0 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
-
-This means: subagents return their changes (files written, but NOT committed). The executor commits them in numeric order.
-
-(Alternative: subagents commit independently and accept commit interleaving. Pick this if commit-order doesn't matter for the project; the orchestrator sets a flag.)
-
-## When to NOT use waves
-
-Single-task changes (`/dw-quick`, `/dw-run`) bypass waves entirely. Waves are for `/dw-run` and `/dw-execute-phase` — phase-scale execution.
-
-## Verification of wave structure (pre-execution)
-
-The plan-checker (Dimension 3 in `plan-checker.md`) verifies:
-- Topological sort succeeds (no cycles)
-- All `Depends on:` references point to existing tasks
-- No wave exceeds the hard cap (8 tasks)
-
-If these fail, plan-checker returns REVISE before any code is touched.
-
-## Resume after checkpoint
-
-If the executor checkpoints mid-phase, `active-session.md` records:
-- `last_completed_task`
-- `last_wave_completed`
-- `remaining_tasks`
-
-`/dw-resume` reads this, recomputes waves from `tasks.md`, skips already-committed tasks, and resumes from the wave containing `last_completed_task + 1`.
+Resume from execution-state.json and actual completed commits, not `last_completed_task + 1`: tasks may finish out of order. Revalidate dependency/evidence state and preserve approved assignments. See `.dw/references/execution-contract.md` for session identity and bookkeeping.

package/scaffold/skills/dw-git-discipline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw-git-discipline
-description: Use when committing or opening a PR. Atomic commits (one intent), Conventional Commits, trunk-based pattern, branch hygiene. Triggers before /dw-commit, /dw-generate-pr, or any git operation.
+description: Use when committing or opening a PR. Atomic commits (one intent), Conventional Commits, trunk-based pattern, branch hygiene. Use for /dw-commit or /dw-generate-pr, not ordinary Git inspection.
 allowed-tools:
   - Read
   - Bash
@@ -54,7 +54,7 @@ See `references/branch-hygiene.md` for naming conventions and rebase-vs-merge gu
 When wired into `/dw-commit`, every commit must:
 
 1. Have a single logical intent (one feature, one fix, one refactor — not mixed).
-2. Pass lint + tests + build BEFORE the commit is created.
+2. Have valid evidence for applicable project-required checks before commit, using `dw-verify`; reuse equivalent evidence without repeating checks solely for a new stage.
 3. Use Conventional Commits format with correct type/scope.
 4. Have a body that explains WHY for non-trivial changes.
 5. NOT skip pre-commit hooks (`--no-verify` is forbidden unless user explicitly authorizes).

package/scaffold/skills/dw-grilling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw-grilling
-description: "Internal decision-tree interview protocol for the native Grill flow. Loaded by /dw-brainstorm (grill mode) and /dw-plan to stress-test a plan or PRD to shared understanding: build a dependency-ordered decision tree, ask exactly ONE unresolved decision per turn with a recommended answer plus rationale and a real alternative, discover facts from the repo/docs instead of asking, leave decisions to the user, and gate alignment on explicit confirmation. Pipeline-internal, never exported, never implements code."
+description: Internal decision-tree interview protocol for the native Grill flow.
 allowed-tools:
   - Read
   - Grep

package/scaffold/skills/dw-incident-response/SKILL.md

@@ -55,70 +55,7 @@ Before starting any phase:
 
 ## The five phases
 
-Each phase writes to `.dw/incidents/<YYYY-MM-DD>-<slug>/`. Slug is auto-generated from incident title (kebab-case, ≤30 chars).
-
-### Phase 1 — Detection & Triage
-
-**Output:** `.dw/incidents/<date>-<slug>/01-triage.md`
-
-Steps:
-1. Classify severity using the table above.
-2. Assess blast radius: which services, how many users affected, revenue impact if known.
-3. Identify immediate mitigation: rollback, feature flag toggle, traffic redirect.
-
-See `references/severity-and-triage.md` for diagnostic commands per stack (Kubernetes, Docker, generic HTTP).
-
-**Checkpoint:** present triage summary. Wait for user confirmation before moving to investigation.
-
-### Phase 2 — Investigation & Root Cause
-
-**Output:** `.dw/incidents/<date>-<slug>/02-investigation.md`
-
-Steps:
-1. Build timeline: when did it start? What changed?
-2. Correlate signals: metrics spike + deploy + error logs.
-3. Hypothesis testing: one theory at a time; verify each before moving on.
-4. Identify root cause: not the first symptom, but the underlying assumption that broke.
-
-Common forensic tools:
-- `git bisect` for regressions.
-- Recent deploy log: `git log --oneline --since="24 hours ago"`.
-- For live monitoring during investigation, `/dw-debug-protocol` flaky-investigation patterns apply.
-
-**Checkpoint:** present root-cause hypothesis. Wait for user confirmation before applying fix.
-
-### Phase 3 — Resolution & Recovery
-
-**Output:** `.dw/incidents/<date>-<slug>/03-resolution.md`
-
-Steps:
-1. Apply fix: hotfix branch → fast PR (via `/dw-generate-pr`) → deploy.
-2. Verify: health checks green, error rate back to baseline.
-3. Monitor 30 minutes post-fix for SEV-1/2 to confirm stability.
-
-**Checkpoint:** confirm full recovery before drafting communications.
-
-### Phase 4 — Communication
-
-**Output:** `.dw/incidents/<date>-<slug>/04-communication.md`
-
-Two communications generated using the templates in `references/communication-templates.md`:
-- **Initial notification** (sent during the incident; updated every 30 min for SEV-1/2).
-- **Resolution notification** (sent when phase 3 confirms recovery).
-
-### Phase 5 — Postmortem
-
-**Output:** `.dw/incidents/<date>-<slug>/05-postmortem.md`
-
-Generate a **blameless** postmortem using `references/postmortem-template.md`. Sections:
-- Summary (2–3 sentences).
-- Timeline (per-minute events from alert to all-clear).
-- Root cause (technical, no blame).
-- Impact (users affected, revenue, error-budget consumed).
-- What went well / What went wrong.
-- Action items (owner + due date + priority — see `references/blameless-discipline.md` for the quality bar).
-
-**Quality bar for action items:** see `references/blameless-discipline.md`. "Improve monitoring" does NOT count. "Add Datadog SLO alert at p99 > 800ms with on-call routing by 2026-06-01, owner: @bruno" counts.
+For the five phases, read `references/the-five-phases-detail.md`. Load only when this part of the task applies.
 
 ## Required reading by context
 

package/scaffold/skills/dw-incident-response/references/the-five-phases-detail.md

@@ -0,0 +1,66 @@
+## The five phases
+
+Each phase writes to `.dw/incidents/<YYYY-MM-DD>-<slug>/`. Slug is auto-generated from incident title (kebab-case, ≤30 chars).
+
+### Phase 1 — Detection & Triage
+
+**Output:** `.dw/incidents/<date>-<slug>/01-triage.md`
+
+Steps:
+1. Classify severity using the table above.
+2. Assess blast radius: which services, how many users affected, revenue impact if known.
+3. Identify immediate mitigation: rollback, feature flag toggle, traffic redirect.
+
+See `severity-and-triage.md` for diagnostic commands per stack (Kubernetes, Docker, generic HTTP).
+
+**Checkpoint:** present triage summary. Wait for user confirmation before moving to investigation.
+
+### Phase 2 — Investigation & Root Cause
+
+**Output:** `.dw/incidents/<date>-<slug>/02-investigation.md`
+
+Steps:
+1. Build timeline: when did it start? What changed?
+2. Correlate signals: metrics spike + deploy + error logs.
+3. Hypothesis testing: one theory at a time; verify each before moving on.
+4. Identify root cause: not the first symptom, but the underlying assumption that broke.
+
+Common forensic tools:
+- `git bisect` for regressions.
+- Recent deploy log: `git log --oneline --since="24 hours ago"`.
+- For live monitoring during investigation, `/dw-debug-protocol` flaky-investigation patterns apply.
+
+**Checkpoint:** present root-cause hypothesis. Wait for user confirmation before applying fix.
+
+### Phase 3 — Resolution & Recovery
+
+**Output:** `.dw/incidents/<date>-<slug>/03-resolution.md`
+
+Steps:
+1. Apply fix: hotfix branch → fast PR (via `/dw-generate-pr`) → deploy.
+2. Verify: health checks green, error rate back to baseline.
+3. Monitor 30 minutes post-fix for SEV-1/2 to confirm stability.
+
+**Checkpoint:** confirm full recovery before drafting communications.
+
+### Phase 4 — Communication
+
+**Output:** `.dw/incidents/<date>-<slug>/04-communication.md`
+
+Two communications generated using the templates in `communication-templates.md`:
+- **Initial notification** (sent during the incident; updated every 30 min for SEV-1/2).
+- **Resolution notification** (sent when phase 3 confirms recovery).
+
+### Phase 5 — Postmortem
+
+**Output:** `.dw/incidents/<date>-<slug>/05-postmortem.md`
+
+Generate a **blameless** postmortem using `postmortem-template.md`. Sections:
+- Summary (2–3 sentences).
+- Timeline (per-minute events from alert to all-clear).
+- Root cause (technical, no blame).
+- Impact (users affected, revenue, error-budget consumed).
+- What went well / What went wrong.
+- Action items (owner + due date + priority — see `blameless-discipline.md` for the quality bar).
+
+**Quality bar for action items:** see `blameless-discipline.md`. "Improve monitoring" does NOT count. "Add Datadog SLO alert at p99 > 800ms with on-call routing by 2026-06-01, owner: @bruno" counts.

package/scaffold/skills/dw-llm-eval/SKILL.md

@@ -26,19 +26,7 @@ If the feature is fully deterministic (no LLM in the loop), use `dw-testing-disc
 
 ## The oracle ladder
 
-Five rungs, climb from CHEAPEST/STRICTEST to MOST EXPENSIVE/SUBJECTIVE. Always start at the bottom; only climb when the lower rung can't cover the case.
-
-| Rung | What it checks | Cost | When to use |
-|------|----------------|------|-------------|
-| 1. **Exact match** | `output === expected` | ~free | Structured outputs (function calls, JSON with stable shape, classifications) |
-| 2. **Schema validation** | Output matches JSON schema / type contract | ~free | Output shape matters; specific values vary |
-| 3. **Outcome state** | Side effect produced the expected change (DB row, file written, tool called) | cheap | Agents, tool-use, RAG with concrete answers |
-| 4. **LLM-as-judge** | A different model grades the output against a rubric | medium ($$$) | Subjective quality (helpfulness, tone, faithfulness) where no rule can decide |
-| 5. **Human review** | Domain expert scores | expensive | Calibration of rung 4; high-stakes outputs; edge cases |
-
-**Rule:** never reach for rung 4 before checking if rungs 1-3 can cover the case. Every rung up costs an order of magnitude more (latency, money, calibration effort) — and adds entropy.
-
-See `references/oracle-ladder.md` for examples per rung and the climbing decision tree.
+For the oracle ladder, read `references/the-oracle-ladder-detail.md`. Load only when this part of the task applies.
 
 ## LLM-as-judge discipline (when rung 4 is needed)
 
@@ -68,14 +56,7 @@ See `references/reference-dataset.md` for case-design principles, sampling from
 
 ## Consistency (run-to-run stability)
 
-The oracle ladder measures whether an output is *correct*; it does not measure whether the feature is *stable*. Because LLMs are non-deterministic, a case that passes once may fail the next run. Measure it:
-
-- Re-run each case **N times** (default 3) against the same code + model + prompt.
-- Record `pass_rate` (e.g. `2/3`) and `consistency` (fraction agreeing with the majority verdict) per case in `runs/<YYYY-MM-DD>.jsonl`.
-- A case with pass_rate strictly between `1/N` and `(N-1)/N` is **flaky** — a signal, not a pass. A 2/3 pass hides a one-in-three production failure; investigate before shipping.
-- Sample at the **temperature the feature uses in production** — consistency measured at temp 0 lies about a temp-0.7 feature.
-
-Deterministic rungs (1–3) are usually stable; consistency matters most for rung 4 (LLM-as-judge) and agent trajectories. Record the run count `N` in the run log so later comparisons are apples-to-apples.
+For consistency (run-to-run stability), read `references/consistency-run-to-run-stability-detail.md`. Load only when this part of the task applies.
 
 ## RAG evaluation
 
@@ -91,27 +72,7 @@ Precision alone misses hallucination. Faithfulness alone misses retrieval failur
 
 ## Agent / tool-use evaluation
 
-Two questions distinguish good agent eval from bad:
-
-### Question 1: outcome or trajectory?
-
-| Approach | What it checks | Failure mode |
-|----------|---------------|--------------|
-| **Outcome-only** | Did the agent achieve the goal? Was the final state correct? | Misses "ghost actions" — agent did the right thing for the wrong reasons |
-| **Trajectory** | Did the agent take the expected sequence of steps / tool calls? | Punishes legitimate creativity — agent solved it via a different valid path |
-
-**Recommendation:** outcome-only with side-effect assertion as default. Trajectory match for cases where the path matters (e.g., "must call `get-user` before `update-user`").
-
-### Question 2: which trajectory match mode?
-
-When trajectory matching IS the right call, four modes are available:
-
-- **Strict** — same tool calls, same order, same arguments. Use when both sequence and parameters are part of the contract.
-- **Unordered** — same tool calls, any order. Use when concurrent calls are valid.
-- **Subset** — actual trajectory contains a subset of reference calls. Use to enforce "don't exceed expected tool use" (frugality / cost).
-- **Superset** — actual contains all reference calls plus possibly more. Use when specific tools are mandatory but extras are acceptable.
-
-See `references/agent-eval.md` for examples and the decision tree.
+For agent / tool-use evaluation, read `references/agent-tool-use-evaluation-detail.md`. Load only when this part of the task applies.
 
 ## Required reading by context
 
@@ -125,20 +86,11 @@ See `references/agent-eval.md` for examples and the decision tree.
 
 ## Anti-patterns (will block in `/dw-review --code-only`)
 
-- **LLM-as-judge without calibration evidence.** PR adds LLM-as-judge but the calibration Spearman score is missing or < 0.80. REJECTED.
-- **Same-model judge.** Judge model is the same as the system under test. REJECTED unless explicitly documented (and even then, results are suspect).
-- **Single-rung eval.** Feature ships with only LLM-as-judge; no rung 1-3 grounding. REJECTED — the cheap rungs catch the loud failures.
-- **Synthetic-only dataset.** No traceable production-failure source for any case. REJECTED — confirm at least 20% of cases come from real user inputs.
-- **"Looks good to me" QA.** No reference dataset, no metric, no rubric — just sampling output and calling it good. REJECTED.
-- **Coverage as metric.** Quoting "we tested 50 prompts" without saying what was measured. The number is meaningless without the metric.
-- **Single-run eval on a non-deterministic feature.** Each case run once at production temperature; a lucky pass reported as a pass. REJECTED — report `pass_rate` over N runs (see Consistency).
+For anti-patterns (will block in `/dw-review --code-only`), read `references/anti-patterns-will-block-in-dw-review-code-only-detail.md`. Load only when this part of the task applies.
 
 ## Integration with dev-workflow commands
 
-- `/dw-plan tasks`: when the PRD has an AI feature requirement, an eval-plan subtask is mandatory. The task references this skill's oracle ladder.
-- `/dw-review --code-only`: AI feature PRs require a reference dataset + ≥2 oracle rungs (lower rungs FIRST). The constitution gate also applies — if the project has principles about AI feature reliability, they're enforced here.
-- `/dw-qa --ai`: new mode (when this skill is bundled) — runs the reference dataset against the current implementation, logs to `QA/logs/ai/<feature>-<date>.jsonl`, computes precision@k / faithfulness / outcome accuracy per the feature type.
-- `/dw-bugfix` when the bug is an AI failure mode (hallucination, tool misuse, classification error): adds the failing case to the reference dataset BEFORE fixing — the case is now a regression test forever.
+For integration with dev-workflow commands, read `references/integration-with-dev-workflow-commands-detail.md`. Load only when this part of the task applies.
 
 ## When the discipline bends