@brunosps00/dev-workflow 1.4.0 → 1.6.0

package/scaffold/skills/dw-domain-modeling/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: dw-domain-modeling
+description: "Internal domain-vocabulary protocol for the native Grill flow. Loaded by /dw-brainstorm (grill mode) and referenced by /dw-analyze-project to keep canonical vocabulary: challenge fuzzy or overloaded terms, propose precise canonical names, stress-test with concrete edge-case scenarios, cross-check terms against the code, and persist resolved terms safely and lazily into .dw/domain (glossary for a single context, context-map plus per-context files for many). Rare ADR policy. Pipeline-internal, never exported, never implements code."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+---
+
+# dw-domain-modeling — canonical vocabulary, kept in .dw/domain
+
+The vocabulary layer of the native Grill flow. It keeps the language of the domain sharp: one canonical term per
+concept, fuzzy language challenged, overloaded terms split, every term cross-checked against the code. Resolved
+terms persist to `.dw/domain/**` — **never** to root `CONTEXT.md` and **never** into the auto-generated
+`.dw/rules/` module files (those describe what the code IS; the glossary is human-curated vocabulary).
+
+> **Internal protocol.** Loaded by `/dw-brainstorm --mode=grill`; read and linked (never regenerated) by
+> `/dw-analyze-project`. Not standalone, not exported to the à-la-carte plugin.
+
+## The disciplines
+
+1. **Canonical vocabulary — one term per concept.** When several words compete for the same idea, pick the best
+   and record the rest as discouraged synonyms. The glossary's job is to end the debate, not catalogue it.
+2. **Challenge fuzzy / overloaded terms.** When the user says "the user thing" or uses one word for two
+   concepts (`User` the account vs `User` the person), stop and propose precise names. Don't pretend to
+   understand — push back until the term is sharp.
+3. **Stress-test with concrete scenarios.** Force precision with edge cases: *"A guest checks out without an
+   account — is that a Customer or a Visitor?"* Vague answers become the next grill question.
+4. **Cross-check against the code.** Before recording a term, confirm it against the codebase. Surface
+   contradictions with the file and line: *"You call it `Subscription`, but `src/billing/plan.ts:12` models it
+   as `Plan`. Which is canonical?"* Don't argue from generalities.
+5. **Persist safely, lazily, and only when authorized.** Create a `.dw/domain/**` file only **after** a term is
+   resolved AND the Grill flow has write authorization. No speculative files; no writing an unresolved term.
+6. **Route single vs multi context.** One bounded context → one flat `.dw/domain/glossary.md`. Multiple contexts
+   (the same word means different things in billing vs shipping) → `.dw/domain/context-map.md` plus one
+   `.dw/domain/contexts/<slug>.md` per context. Full routing + format: `references/glossary-format.md`.
+7. **ADR rarely, and only on approval.** Vocabulary decisions are not ADRs. Reach for an ADR only on the
+   three-criterion test, and only with separate explicit user approval — see `references/adr-policy.md`.
+
+## Native artifacts
+
+| Path | When |
+|---|---|
+| `.dw/domain/glossary.md` | Single bounded context — the default. |
+| `.dw/domain/context-map.md` | Two or more contexts — names the contexts and the terms that cross or clash. |
+| `.dw/domain/contexts/<slug>.md` | Per-context glossary, one file per context. |
+
+All created **lazily**: the directory and file appear only when the first term in that context is resolved and
+authorization exists. `/dw-analyze-project` **reads and links** these when present and must **preserve** them —
+never regenerate or overwrite `.dw/domain/**`.
+
+## What a glossary entry is (and is not)
+
+A definition is **one or two sentences** that say what the domain term **is**, plus a short list of discouraged
+synonyms. It **excludes** implementation details (classes, files, tables), requirements ("must load in 200ms"),
+scratch notes, and general programming concepts (timeouts, retries, DTOs) — even when the project uses them
+heavily. The test: *is this concept unique to this domain, or general programming?* Only the former belongs.
+Format and examples: `references/glossary-format.md`.
+
+## Anti-patterns
+
+- Writing vocabulary into `.dw/rules/<module>.md` or a root `CONTEXT.md` instead of `.dw/domain/**`.
+- Creating a glossary file for a term that is not yet resolved, or before write authorization exists.
+- Definitions that describe the code ("a `Repository` class in `src/`") instead of the concept.
+- Listing every synonym as equal — pick one canonical term, discourage the rest.
+- Splitting into multiple contexts prematurely — a single flat glossary is right until a word genuinely clashes
+  across contexts.
+- Regenerating or overwriting `.dw/domain/**` from `/dw-analyze-project`.
+
+## Structured Return
+
+- **Status:** `PASS` · `FINDINGS` · `BLOCKED` · `NOT_APPLICABLE` — `PASS` when the terms in scope are resolved,
+  cross-checked against the code, and (when authorized) persisted to the correct `.dw/domain/**` path; `FINDINGS`
+  when terms remain fuzzy, a code contradiction is open, or authorization is missing so nothing was written;
+  `BLOCKED` when the caller supplied no vocabulary to resolve or the code cross-check cannot run;
+  `NOT_APPLICABLE` when there is no domain vocabulary at stake.
+- **Scope:** the terms examined, single- vs multi-context routing, and the target `.dw/domain/**` path(s).
+- **Evidence:** the code cross-checks (file:line) and scenarios used to sharpen each term.
+- **Artifacts:** the glossary / context-map / per-context files written or proposed, with paths.
+- **Decisions:** each canonical term chosen, the discouraged synonyms, and the routing decision.
+- **Risks:** unresolved fuzziness, open code contradictions, or vocabulary written without authorization.
+- **Next Step:** resolve the remaining terms, request write authorization, or hand the canonical vocabulary back
+  to the grill / one-pager.

package/scaffold/skills/dw-domain-modeling/references/adr-policy.md

@@ -0,0 +1,48 @@
+# ADR policy — rare, three-criterion, approval-gated
+
+Most decisions surfaced during a grill are **not** ADRs. Vocabulary choices, scope calls, and reversible
+decisions belong in the glossary or the one-pager, not the ADR log. An ADR is for the rare decision that is
+expensive to unwind and non-obvious to a future reader.
+
+## The three-criterion test (all must hold)
+
+| Criterion | Test |
+|---|---|
+| **Hard to reverse** | If we change this in 6 months, does it cost meaningfully more than a day — a migration, a re-architecture, a contract change? |
+| **Surprising without context** | Would a competent new contributor reasonably reach a *different* decision, absent this record? |
+| **Genuine trade-off** | Was there a real alternative we considered and chose against — a rejection worth remembering? |
+
+If any criterion fails, **do not** write an ADR. Record the decision where it belongs (glossary, one-pager, PRD)
+and move on. ADR-ing every casual decision turns the log into noise.
+
+## Approval is always separate
+
+Even when all three criteria hold, **creating an ADR needs a separate, explicit user approval.** A resolved grill
+decision authorizes the glossary/alignment update — it does **not** authorize an ADR. Offer the ADR, state which
+criteria it meets, and wait for the user to approve before anything is written.
+
+## Routing — repo vs prd scope
+
+ADRs are created via `/dw-adr`, which routes by `--scope`:
+
+- **`--scope=repo`** → `.dw/adrs/adr-NNN.md`. Repo-wide decisions, and any decision made **before a PRD exists**
+  (a greenfield grill naturally produces repo-scoped ADRs).
+- **`--scope=prd`** → `.dw/spec/<prd>/adrs/adr-NNN.md`. Decisions bound to a specific active PRD.
+
+Default resolution when scope is unspecified (`--scope=` is always authoritative): the uniquely **active** PRD →
+`prd`; no active PRD → `repo`; several active PRDs (ambiguous) → **ask**, don't guess. `NNN` is sequential within
+the chosen scope's ADR directory.
+
+**Active vs historical PRD** — deterministic and conservative, reading only evidence the repo already records
+(never guessing): a PRD directory is a candidate only when it is **not terminal** (its `prd.md` status is not
+shipped/merged/delivered/done/archived/superseded/cancelled). Choose the active one by precedence — an **explicit
+target** (named PRD or `PRD_PATH`) → the **active session** (`.dw/STATE.md`) → the **current `feat/prd-<slug>`
+branch**. If more than one non-terminal PRD survives with no disambiguating signal, **ask**. The authoritative
+rule lives in the `/dw-adr` "Active PRD" section.
+
+## What qualifies
+
+Architectural shape, integration patterns between components, high-lock-in technology choices, bounded-context
+boundaries, deliberate deviations from convention, non-visible constraints, and non-obvious rejected
+alternatives. A vocabulary decision — "we call it `Tenant`, not `Org`" — does **not** qualify; it is a glossary
+entry.

package/scaffold/skills/dw-domain-modeling/references/glossary-format.md

@@ -0,0 +1,66 @@
+# Glossary format and context routing
+
+Where domain vocabulary lives, what an entry looks like, and how to decide between a single flat glossary and a
+multi-context map.
+
+## Paths (created lazily)
+
+| Path | Purpose |
+|---|---|
+| `.dw/domain/glossary.md` | The single-context default. One flat glossary for the whole project. |
+| `.dw/domain/context-map.md` | Multi-context index: names each bounded context and the terms that cross or clash between them. |
+| `.dw/domain/contexts/<slug>.md` | One glossary per bounded context (`<slug>` = kebab-case context name). |
+
+Never write vocabulary to root `CONTEXT.md` or to `.dw/rules/<module>.md`. The `.dw/rules/` files are
+auto-generated analysis of what the code IS; the glossary is human-curated vocabulary and must survive
+`/dw-analyze-project` runs untouched.
+
+Create files only when a term is **resolved** and the Grill flow has **write authorization**. Do not scaffold
+empty files or write an unresolved term.
+
+## Entry format
+
+Each term is a short entry:
+
+```markdown
+### Order
+A customer's committed request to buy one or more items, in one of: pending, paid, shipped, delivered, refunded.
+
+_Avoid:_ Purchase, Cart, Transaction
+```
+
+Rules for an entry:
+
+- **One or two sentences.** Define what the term **is**, not what a class does. If it needs a paragraph, the
+  concept is probably two concepts — split it.
+- **`_Avoid:_` line** lists the discouraged synonyms. Pick one canonical term; every competing word goes here so
+  the debate does not reopen.
+- **Exclude** implementation detail (files, classes, tables, endpoints), requirements/NFRs, scratch notes, and
+  general programming concepts (timeout, retry, DTO, cache) even if heavily used.
+- **Inclusion test:** *is this concept unique to this domain, or is it general programming?* Only the former is a
+  glossary term. `Order`, `Tenant`, `Dunning` — yes. `Timeout`, `Repository`, `Idempotency key` — no.
+
+Group entries under `##` subheadings when natural clusters emerge; a flat list of `###` terms is fine for a small
+glossary.
+
+## Single vs multi context — how to route
+
+Start with **one flat `.dw/domain/glossary.md`**. It is the right default and stays right until a word genuinely
+means different things in different parts of the system.
+
+Split to multi-context only when a term **clashes across bounded contexts** — e.g. `Account` means a login in
+Identity but a ledger in Billing. Then:
+
+1. Create `.dw/domain/context-map.md`. List each context (Identity, Billing, Shipping…), a one-line description,
+   and the **shared or clashing terms** with the context each meaning belongs to.
+2. Move each context's terms into `.dw/domain/contexts/<slug>.md` (e.g. `contexts/billing.md`).
+3. In the context map, note translations: "Billing `Account` ≈ Identity `Organization`, not Identity `Account`."
+
+Do not split pre-emptively. A single clean glossary beats three thin ones. When in doubt, stay single-context and
+record the tension as a grill decision rather than forking files.
+
+## Interaction with /dw-analyze-project
+
+`/dw-analyze-project` must, when `.dw/domain/**` exists: read it, link it from `.dw/rules/index.md` (so
+downstream commands find the canonical vocabulary), and **preserve it verbatim** — never regenerate, merge, or
+overwrite. The analyzer owns `.dw/rules/**`; the Grill flow owns `.dw/domain/**`.

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -94,6 +94,19 @@ Closes RF-XX (partial — see tasks.md).
 
 The commit message format is consistent across waves so `/dw-generate-pr` can build a clean PR body. See `references/atomic-commits.md`.
 
+## 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.
+
 ## Checkpoint Protocol
 
 If the executor exhausts its context budget mid-phase OR the user signals stop:

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

@@ -78,6 +78,7 @@ When wired into `/dw-generate-pr`, every PR must:
 | Branch is 5 days old, tons of conflicts | Rebase from main daily; don't let drift compound |
 | PR has 2,000 lines | Split. Identify natural seams: schema, backend, frontend, tests |
 | Stuck mid-merge with conflicts | Resolve, don't `git checkout --theirs` blindly. The conflict is information |
+| Rebase or merge to integrate? | Local-only branch → **rebase** onto `main` (linear history). Shared/pushed branch → **merge** (never rebase history others have pulled) |
 
 ## What this skill does NOT do
 

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

@@ -0,0 +1,98 @@
+---
+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."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# dw-grilling — interview to shared understanding, one decision at a time
+
+A relentless-but-disciplined interview that sharpens a plan/PRD until author and reviewer reach a
+**shared understanding** — the alignment layer of the native Grill flow. It walks the design tree branch by
+branch, resolving dependencies one at a time. It does not brainstorm options and it does not implement; it
+converges decisions. Persistence (glossary, one-pager, PRD) is delegated — see `dw-domain-modeling` for
+vocabulary and the calling command for the idea one-pager / PRD.
+
+> **Internal protocol.** Loaded by `/dw-brainstorm --mode=grill` and by `/dw-plan` when it consumes an aligned
+> handoff. Not a standalone skill, not exported to the à-la-carte plugin. If no calling command supplied the
+> Grill context (target artifact + write authorization state), return `NOT_APPLICABLE`.
+
+## Hard rules (non-negotiable)
+
+1. **Exactly one unresolved decision per turn, then wait.** Never dump a list of questions — a batch is
+   bewildering and lets the reviewer skim instead of decide. Ask, wait, integrate the answer, ask the next.
+2. **Every question carries a recommendation.** Structure: *evidence (when available) → the decision →
+   recommended answer → one-line rationale → a meaningful alternative and its trade-off.* A question with no
+   recommended answer is not ready to ask. See `references/interview-loop.md`.
+3. **Facts are discovered, decisions are asked.** If the answer can be found in the codebase, rules, intel,
+   or docs, look it up and state it — do not ask the user a question the repo already answers. Only genuine
+   **decisions** (choices with no single correct answer) go to the user.
+4. **Decisions belong to the user.** Recommend, argue, push back on vague language — but the user chooses.
+   Never answer your own decision question and move on.
+5. **No implementation, ever.** Grill never edits source code. It produces alignment, not commits.
+6. **Alignment is gated on explicit confirmation.** Do not declare shared understanding (or `status: aligned`)
+   until every dependency branch is resolved, glossary/code contradictions are closed, no blocking decision
+   remains, AND the user explicitly confirms. Otherwise persist a draft/paused state and stop.
+
+## Before the first question — build the decision tree
+
+Inspect project facts and open questions, then order them by dependency (never ask a downstream decision before
+its blocker is resolved):
+
+1. Read what already exists: `.dw/rules/`, `.dw/intel/` (via `/dw-intel` when present), `.dw/constitution.md`,
+   `.dw/domain/**` (glossary / context-map), current PRDs/TechSpecs, recent git activity.
+2. Extract the open decisions the plan/PRD implies. Fold in vocabulary tension surfaced by `dw-domain-modeling`
+   (fuzzy or overloaded terms are decisions too).
+3. Order them into a **dependency tree**: a node that constrains others comes first. Record it so a later turn
+   (or `/dw-plan`) can resume. Full method + the shared-understanding gate: `references/decision-tree.md`.
+
+## The loop
+
+For each unresolved node, in dependency order:
+
+1. **Discover** every fact the node needs (repo/docs). State the facts and their source.
+2. **Frame the decision** and give the recommended answer + rationale + one real alternative/trade-off.
+3. **Ask** — one decision, then wait.
+4. **Integrate** the answer. A resolved answer authorizes the matching glossary/alignment update (delegated to
+   `dw-domain-modeling`; the caller persists to the one-pager/PRD). ADR creation still needs a separate explicit
+   approval — never auto-create one.
+5. **Re-walk** the tree: the answer may unlock or reshape downstream nodes.
+
+When the tree is exhausted and contradictions are closed, present the shared-understanding summary and ask the
+user to confirm. Only then is the session `aligned`.
+
+## Allowed writes (only when the caller authorized them)
+
+Grill is read-first. The only stateful writes the flow may make, and only after the corresponding decision is
+resolved and write authorization exists, are: `.dw/domain/**` (via `dw-domain-modeling`), the active
+`.dw/spec/ideas/<slug>.md`, an explicitly active PRD/TechSpec **after showing the proposed change**, and routed
+ADR paths (after separate approval). Never source code. If authorization is absent, keep interviewing and report
+what you *would* persist.
+
+## Anti-patterns
+
+- Asking two or more decisions in one turn — the batch defeats the protocol.
+- Asking a question the codebase already answers — that is a fact, look it up.
+- Recommending nothing ("what do you want to do about X?") — always bring a recommended answer.
+- Declaring alignment without the user's explicit confirmation.
+- Writing any artifact before its decision is resolved and authorization exists.
+- Generating an option matrix here — that is `option-matrix`, a separate and mutually exclusive phase.
+
+## Structured Return
+
+- **Status:** `PASS` · `FINDINGS` · `BLOCKED` · `NOT_APPLICABLE` — `PASS` when the tree is fully resolved,
+  contradictions closed, and the user explicitly confirmed shared understanding (session `aligned`); `FINDINGS`
+  when decisions were resolved but blocking questions, unclosed contradictions, or a pending confirmation remain
+  (draft/paused); `BLOCKED` when the caller supplied no target artifact or write-authorization state, or the
+  interview cannot proceed; `NOT_APPLICABLE` when invoked without Grill context (no plan/PRD to sharpen).
+- **Scope:** the artifact under grill (one-pager / PRD / TechSpec), the decision tree size, and how many nodes
+  are resolved vs open.
+- **Evidence:** the facts discovered from repo/rules/intel/docs (with sources) that were used instead of asking.
+- **Artifacts:** decision tree, resolved decisions with the recommended answer and the user's choice, and any
+  authorized `.dw/domain/**` / one-pager / PRD updates (with paths).
+- **Decisions:** each resolved decision, the alternative rejected, and why.
+- **Risks:** open decisions, unclosed glossary/code contradictions, and any decision made without full evidence.
+- **Next Step:** either "user to confirm shared understanding" (with the remaining nodes) or "aligned — hand off
+  to /dw-plan" — never implement here.

package/scaffold/skills/dw-grilling/references/decision-tree.md

@@ -0,0 +1,56 @@
+# Decision tree — build, order, gate, resume
+
+Grill is not a flat questionnaire. It is a walk down a **dependency-ordered decision tree**, so an upstream
+decision is never asked after the downstream decision it constrains.
+
+## Build the tree (before the first question)
+
+1. **Gather open decisions.** Read the plan/PRD and the project's durable facts (`.dw/rules/`, `.dw/intel/` via
+   `/dw-intel`, `.dw/constitution.md`, `.dw/domain/**`, current PRDs/TechSpecs, recent git activity). List every
+   decision the artifact leaves open. Fold in vocabulary tension from `dw-domain-modeling` — an overloaded or
+   fuzzy term is a decision node.
+2. **Separate facts from decisions.** Discard anything the repo already answers (those are facts to state, not
+   ask). What remains is the decision set.
+3. **Draw dependencies.** For each decision, mark which other decisions must be settled first. "Is refund a
+   state or a flag?" blocks "which events transition into it?". A node that constrains others is a **parent**.
+4. **Topologically order.** Ask parents before children. Independent branches can be walked in any order, but
+   within a branch always resolve the blocker first.
+
+Record the tree (nodes, dependencies, resolved/open) so the session — or a later `/dw-plan` handoff — can resume
+exactly where it stopped.
+
+## Walk the tree
+
+Resolve nodes in dependency order using the per-turn contract (`interview-loop.md`). After each answer, **re-walk
+the tree**: a resolved parent may add, remove, or reshape child nodes. New tension discovered mid-walk becomes a
+new node, inserted in dependency order — not asked immediately if a blocker is still open.
+
+## The shared-understanding gate
+
+Declare alignment (and let the caller set the one-pager to `status: aligned`) only when **all** hold:
+
+- Every dependency branch is resolved — no open decision node remains.
+- Every glossary/code contradiction surfaced during the grill is closed (a canonical term chosen, or the code
+  discrepancy explained).
+- No blocking open decision remains (a non-blocking "revisit later" may be recorded as a remaining decision).
+- The user has **explicitly confirmed** shared understanding — not "sounds good", but an explicit yes to the
+  summary of resolved decisions and canonical vocabulary.
+
+Present a shared-understanding summary before asking for confirmation: the resolved decisions, the canonical
+terms, and the remaining (non-blocking) decisions with their owners.
+
+## Paused / draft state
+
+If the gate is not met — blocking decision open, contradiction unclosed, or the user not yet confirming — **do
+not** declare alignment. Persist a draft/paused state:
+
+- Keep the one-pager (or PRD) at its draft/paused status with the decision tree, resolved decisions, and the
+  remaining open nodes recorded (the caller performs the write, only if authorized).
+- Return `FINDINGS` with the open nodes as the Next Step, so the next turn resumes the same tree.
+
+## Handoff to /dw-plan
+
+An `aligned` session is a handoff contract: the resolved product decisions, their evidence, and the canonical
+vocabulary links. `/dw-plan` consumes this **without re-asking** the resolved decisions — it credits the aligned
+evidence in its coverage matrices and asks only decisions the Grill did not cover (technical decisions may still
+surface during TechSpec). Never re-litigate a decision the user already settled in the grill.

package/scaffold/skills/dw-grilling/references/interview-loop.md

@@ -0,0 +1,52 @@
+# Interview loop — the per-turn contract
+
+The unit of a grill is **one turn = one unresolved decision**. This file specifies the exact shape of a turn and
+the fact-vs-decision discipline that keeps the interview honest.
+
+## Question template
+
+Every question is presented in this order. Skipping any part means the question is not ready to ask.
+
+1. **Evidence (when available).** The facts you discovered from the repo/rules/intel/docs that bound this
+   decision, each with its source: `` src/orders/state.ts:42 defines OrderStatus = pending | paid | shipped ``.
+   If there is no evidence yet, discover it first — do not open with an unbounded question.
+2. **The decision.** State the single choice on the table in one sentence.
+3. **Recommended answer.** Your pick. Not "it depends" — commit to a default and let the user overrule it.
+4. **Rationale.** One line on why the recommendation wins in *this* project's context.
+5. **Alternative + trade-off.** At least one real alternative and what it costs — so the user is choosing, not
+   rubber-stamping. A recommendation with no stated alternative hides the trade-off.
+
+Then **stop and wait.** Do not ask the next decision, do not preview the rest of the tree, do not answer your own
+question. Integrate the reply, then move to the next node.
+
+## Fact vs decision
+
+The single most important discrimination in a grill:
+
+- **Fact** — has one correct answer discoverable from the codebase, rules, intel, migrations, config, or
+  authoritative docs. *Look it up. Never ask.* Asking a fact wastes the user's turn and signals you did not read.
+  Example: "does the API already return `order_id` or `orderId`?" → grep, don't ask.
+- **Decision** — has no single correct answer; it is a choice among viable options with a trade-off. *This is
+  what you ask*, one at a time, always with a recommendation. Example: "should a partially-refunded order be a
+  distinct state or a flag on `refunded`?"
+
+When a "fact" turns out to be contested (the code says one thing, the user says another), that contradiction
+itself becomes a decision — surface it: *"You said the API returns `OrderId`, but `src/api/orders.ts:42` returns
+`{ order_id, status }`. Which is canonical?"*
+
+## Recommendation discipline
+
+- Recommend from evidence, not taste. Tie the pick to a rule, a code pattern, a constraint, or a prior decision.
+- Make the recommendation falsifiable: state the one condition that would flip it.
+- If you genuinely cannot recommend (truly balanced, user-values-dependent), say so explicitly and present the
+  two options with their trade-offs — but this should be rare. Defaulting to "no recommendation" is the failure
+  mode this protocol exists to prevent.
+
+## Anti-patterns
+
+- **Batching.** Five questions in one message. The reviewer skims and half go unanswered.
+- **Interrogating facts.** Asking what the repo already states — reads as not having done the homework.
+- **Empty questions.** "What should we do about caching?" with no recommendation and no alternative.
+- **Leading past the answer.** Recommending, then implementing the recommendation before the user replies.
+- **Vague acceptance.** Taking "sure, sounds good" to a bundle of decisions as alignment. One decision, one
+  explicit answer.

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

@@ -66,6 +66,17 @@ Structure:
 
 See `references/reference-dataset.md` for case-design principles, sampling from production, and when to expand the set.
 
+## 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.
+
 ## RAG evaluation
 
 Three orthogonal metrics — measure all three, not just one:
@@ -120,6 +131,7 @@ See `references/agent-eval.md` for examples and the decision tree.
 - **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).
 
 ## Integration with dev-workflow commands
 

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

@@ -52,7 +52,7 @@ Create `MEMORY.md` and `<N>_memory.md` on first use with the template below. Nev
 - Branch: <branch-name>
 
 ## Durable Decisions
-- <decision 1> — <one-line rationale>
+- <decision 1> — <one-line rationale> — [confidence: 0.7; seen in tasks 1,3]
 
 ## Cross-Task Constraints
 - <constraint discovered during implementation that affects multiple tasks>
@@ -124,6 +124,16 @@ Before promoting an item from `<N>_memory.md` to `MEMORY.md`, ask:
 
 All three must be "yes" to promote. If any is "no", the item stays in task memory.
 
+### Confidence signal
+
+Tag each durable decision with a confidence in `[0.3–0.9]` plus the tasks that confirmed it — `… — [confidence: 0.7; seen in tasks 1,3,5]`:
+
+- Confirmed in **≥2 of the last 3 tasks** with no contradiction → **≥0.7** (trust it; safe to act on without re-deriving).
+- Confirmed once, or inferred but not yet reused → **0.3–0.5** (tentative; gather more signal before relying).
+- Contradicted by a later task or the repo → lower it or drop the decision (see Error Handling).
+
+Confidence makes cross-task learning explicit and is the signal `/dw-learn` reads to promote high-confidence decisions into durable instincts, constitution principles, or rules.
+
 ### Belongs in shared memory
 - A discovered constraint affecting multiple tasks ("the Stripe API rate-limits to 100 req/s — batch operations must respect this")
 - A cross-cutting architectural decision made during implementation ("chose React Server Components for data fetching across the whole feature")
@@ -179,6 +189,7 @@ This budget is doctrine, not a hard gate. No command currently rejects work for
 - `/dw-run` — reads memory before coding; updates `<N>_memory.md` during; runs promotion test + updates `MEMORY.md` at the end.
 - `/dw-run` — runs promotion + compaction between tasks, so each task starts with clean shared state.
 - `/dw-autopilot` — threads memory through every phase (brainstorm → PRD → techspec → tasks → execution); on re-invocation reads `MEMORY.md` first to reconstitute cross-session context.
+- `/dw-learn` — synthesizes confidence-tagged decisions here (plus bugfixes, deviations, git history) into atomic **instincts** in `.dw/memory/instincts/`; format, confidence rules, and promotion path in `references/instincts.md`.
 
 Callers should mention this skill in their "Skills Complementares" section.
 

package/scaffold/skills/dw-memory/references/instincts.md

@@ -0,0 +1,45 @@
+# Instincts — promoting durable memory into reusable behavior
+
+An instinct is a small, atomic, confidence-weighted behavior learned from THIS project's work, promotable
+into a constitution principle or rule. Instincts live in `.dw/memory/instincts/*.md` and are proposed and
+curated by `/dw-learn` — never written without explicit approval. There is no always-on observer; instincts
+are synthesized on demand from what the project already recorded (see `/dw-learn` sources).
+
+## File format (`.dw/memory/instincts/<slug>.md`)
+
+```markdown
+---
+id: prefer-result-type-in-services
+trigger: when writing a service method that can fail
+confidence: 0.7          # 0.3 tentative … 0.9 near-certain (same scale as durable decisions)
+domain: error-handling   # code-style | testing | error-handling | git | workflow | security
+scope: project           # project | global
+evidence:
+  - "MEMORY.md decision (seen in tasks 3,5)"
+  - "bugfix 004-null-order — same root cause"
+---
+
+# Prefer Result type in services
+
+## Action
+Return a typed Result/union from fallible service methods instead of throwing across layers.
+
+## Why
+Two bugfixes traced to exceptions swallowed between layers; the confidence-tagged decision in MEMORY.md
+already prefers this.
+```
+
+## Confidence (reuse the promotion signal)
+
+Same scale and rule as durable decisions (see the **Confidence signal** section of this skill): ≥2
+independent confirmations in recent work → ≥0.7. Lower it when a later task contradicts the instinct; drop
+it when it stops being true.
+
+## Promotion path
+
+- **≥0.7, project scope** → propose as a `.dw/constitution.md` principle (via the `/dw-analyze-project`
+  Step 8 flow) or a note on the relevant `.dw/rules-library/<stack>.md`.
+- **Seen across multiple projects** → mark `scope: global` (a candidate for a shipped rule/skill).
+
+High-confidence instincts (≥0.7) whose `trigger` matches the current work are loaded on demand by `/dw-run`
+and `/dw-plan` — the same lazy pattern as `.dw/rules/concerns.md`. Never bulk-load the whole instinct set.

package/scaffold/skills/dw-review-rigor/SKILL.md

@@ -21,6 +21,17 @@ By `/dw-review --code-only`, `/dw-review --coverage-only`, `/dw-refactor`, and `
 - The scope the caller is reviewing (file paths, directories, or PR diff).
 - Optional: prior review reports in `.dw/spec/prd-*/reviews/` — so this round only surfaces NEW findings.
 
+## Pre-Report Gate
+
+Before writing ANY finding, clear four checks — if any is "no"/"unsure", downgrade or drop it (an unactionable finding is noise):
+
+1. **Location** — exact file and line?
+2. **Failure mode** — a concrete input/state and the bad outcome it produces?
+3. **Context** — read the surrounding code (callers, imports, tests), not just the flagged line?
+4. **Severity** — defensible against Rule 2's definitions? (a missing JSDoc is never HIGH)
+
+Report only findings you are **>80% confident** are real. A style preference no rule backs is not a finding. See `references/false-positives.md` for patterns LLM reviewers habitually mis-flag.
+
 ## The Five Rules
 
 ### 1. De-duplicate before writing
@@ -111,6 +122,7 @@ The caller emits:
 2. **Counts** — critical / high / medium / low.
 3. **Findings** — ordered by severity, each in the format above.
 4. **Well-implemented aspects** — short bulleted list, calibrates tone.
+5. **Self-score** — rate the report on the five axes in `references/self-eval-rubric.md`; any axis below top cites the gap, then fix (<30s) or flag.
 
 ## Critical Rules
 

package/scaffold/skills/dw-review-rigor/references/false-positives.md

@@ -0,0 +1,21 @@
+# False Positives — patterns LLM reviewers habitually mis-flag
+
+Loaded on demand by the Pre-Report Gate. Skip these unless you have evidence **specific to this codebase**
+(a failing test, a real caller that doesn't guard, a project rule that forbids it). Flagging them anyway is
+the most common way an AI review drowns real findings in noise.
+
+| Tempting finding | Why it's usually wrong |
+|---|---|
+| "Add error handling here" | The error path is already handled by the caller or the framework — Express/Koa middleware, a React error boundary, a top-level `catch`, or a job runner that retries. Trace one level up before flagging. |
+| "Missing input validation" | The function is internal and every caller already validated at the boundary. Validation belongs at the trust boundary, not on every hop. |
+| "Magic number" | Well-known constants are self-documenting: HTTP codes (200/404/500), `1000`/`60`/`24`/`1024`, array index `0`/`-1`, `100` for percent. Only flag opaque domain numbers with no name. |
+| "Function too long" | Length ≠ complexity. Exhaustive `switch`, config/lookup objects, test tables, and generated code are long *and* simple. Flag high branching/nesting, not line count. |
+| "Missing JSDoc/docstring" | Internal helpers whose name and signature are self-describing don't need docs. Reserve for public API or non-obvious contracts. |
+| "Possible null dereference" | A preceding line already narrowed the type or an `if` guard is in scope. Read the few lines above before asserting. |
+| "Use `const` / style nit" | The linter/formatter already enforces this (Rule 4). It is a linter task, not a review finding. |
+| "This could be a race condition" | Only real if there is actual shared mutable state across concurrent paths. A single-threaded request handler touching a local variable is not a race. |
+| "Add a test for this" | Valid only if the behavior is untested AND load-bearing. Don't demand tests for trivial getters or framework glue. |
+| "Extract this into a helper (DRY)" | Two similar lines are not duplication worth an abstraction. Premature extraction couples unrelated call sites — see `dw-minimalism`. |
+
+**Rule of thumb:** if the "fix" would be rejected by a competent maintainer as busywork, it is a false
+positive. When unsure whether a pattern is intentional, apply Rule 3 (verify intent) before writing it.

package/scaffold/skills/dw-review-rigor/references/self-eval-rubric.md

@@ -0,0 +1,38 @@
+# Self-Evaluation Rubric — five axes, evidence required
+
+A structured way for an agent to rate its own output **before** handing it over, without waiting for user
+feedback. Used by `dw-review-rigor` (score the review itself) and cited by `dw-cli-run` (the 0–10 delivery
+gate applies the same evidence discipline). Adapted from the ECC `agent-self-evaluation` skill.
+
+## The five axes (score each 1–5)
+
+| Axis | Question | What a low score catches |
+|---|---|---|
+| **Accuracy** | Are the facts, claims, and code correct? | Hallucinated APIs, wrong file paths, syntax errors, unverified assertions |
+| **Completeness** | Did it cover everything the request asked? | Missed edge cases, skipped subtasks, unhandled error paths |
+| **Clarity** | Is it understandable and well-structured? | Confusing explanations, jargon, rambling, missing context |
+| **Actionability** | Can the user act on it immediately? | Vague suggestions, missing steps, "you should X" without showing how |
+| **Conciseness** | Is it the minimum needed to be complete? | Redundancy, over-explanation, filler, restating the question |
+
+Scale: **5** = no reasonable improvement · **4** = minor nits · **3** = one notable weakness · **2** = a clear
+gap that hurts usability · **1** = fundamentally misses the request.
+
+## The one hard rule: evidence for every score below 5
+
+A score under 5 **must cite the specific gap** — quote the line, name the missing case, point at the
+redundancy. "Completeness: 3 — doesn't handle the empty-array case in `parse()`" is a real score;
+"Completeness: 3 — could be more thorough" is hand-waving and not allowed.
+
+## What to do with the scores
+
+1. Score each axis independently (don't average away a real weakness).
+2. If any axis is **≤ 3**: fix it now when the fix is under ~30 seconds; otherwise flag it explicitly in the
+   output so the user knows the gap exists.
+3. Keep the self-score short — a few lines, not a second report.
+
+## Anti-patterns
+
+- **"Everything is a 5"** with no evidence — the most common failure; it means you didn't actually evaluate.
+- **Over-penalizing scope** — grade only what was requested, not scope you invented.
+- **Re-litigating decisions** — evaluate execution quality, not whether a settled decision was right.
+- **Personal preference as a gap** — a nit the linter doesn't enforce and no rule backs is not a real deduction.