@brunosps00/dev-workflow 2.2.0 → 2.3.0

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
 

package/scaffold/skills/dw-llm-eval/references/agent-tool-use-evaluation-detail.md

@@ -0,0 +1,23 @@
+## 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 `agent-eval.md` for examples and the decision tree.

package/scaffold/skills/dw-llm-eval/references/anti-patterns-will-block-in-dw-review-code-only-detail.md

@@ -0,0 +1,9 @@
+## 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).

package/scaffold/skills/dw-llm-eval/references/consistency-run-to-run-stability-detail.md

@@ -0,0 +1,10 @@
+## 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.

package/scaffold/skills/dw-llm-eval/references/integration-with-dev-workflow-commands-detail.md

@@ -0,0 +1,6 @@
+## 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.

package/scaffold/skills/dw-llm-eval/references/the-oracle-ladder-detail.md

@@ -0,0 +1,15 @@
+## 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 `oracle-ladder.md` for examples per rung and the climbing decision tree.