@brunosps00/dev-workflow 2.2.0 → 2.3.0

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

@@ -87,7 +87,7 @@ Create `MEMORY.md` and `<N>_memory.md` on first use with the template below. Nev
 
 ## Workflow
 
-### 1. Load before editing code
+### 1. Load relevant task memory on start or resume
 - Read `MEMORY.md` and the current task's `<N>_memory.md` **before** any code change.
 - Treat these as mandatory context for the run, not optional notes.
 - If the caller marks either file for compaction, apply the Compaction Rules (below) before continuing.
@@ -116,34 +116,7 @@ Create `MEMORY.md` and `<N>_memory.md` on first use with the template below. Nev
 
 ## Promotion Decision Test
 
-Before promoting an item from `<N>_memory.md` to `MEMORY.md`, ask:
-
-1. Will another task need this to avoid a mistake or rediscovery?
-2. Is this fact durable across multiple runs, not just the current execution?
-3. Is this information NOT already obvious from the PRD, TechSpec, task files, or the repository itself?
-
-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")
-- An open risk future tasks must account for ("migration depends on schema v3 which is not yet deployed to staging")
-
-### Stays in task memory
-- Files touched during this task's implementation
-- Debugging steps taken to resolve a task-specific error
-- The current task's objective and acceptance criteria snapshot
-- A workaround applied only to the current task's scope
+For promotion decision test, read `references/promotion-decision-test-detail.md`. Load only when this part of the task applies.
 
 ## Compaction Rules
 
@@ -157,26 +130,7 @@ When flagged for compaction, apply inline:
 
 ## Context Budget
 
-Memory is part of a broader **context budget** the agent must respect during execution. A blown budget degrades reasoning before any output is produced — the model starts missing requirements, drops constraints, and reverts to averaged-over-training answers. Full guidance: [`references/context-budget.md`](references/context-budget.md).
-
-**Targets:**
-
-- **Total active context:** under **40k tokens** (rough working budget across PRD + TechSpec + tasks + MEMORY.md + per-task memory + open files).
-- **Reserve:** at least **120k tokens** of headroom for actual reasoning, tool output, and the model's response stream.
-- **Hard ceiling per memory file:** `MEMORY.md` ≤ 6KB; `<N>_memory.md` ≤ 3KB. Past those, compact instead of growing.
-
-**Anti-co-load rules** (apply on every load):
-
-1. Never load two PRD specs in the same context. If switching PRDs, drop the previous PRD's spec/techspec/tasks references from the active set.
-2. Never load multiple archived `.dw/bugfixes/` SUMMARY.md files together — load only what's needed for the active fix or query.
-3. Never load `.dw/intel/files.json` and `.dw/intel/deps.json` simultaneously when answering a single question — pick the primary per query shape (see `dw-codebase-intel/references/query-patterns.md`).
-4. Never load a design proposal AND the prior design's full text — if comparing, summarize the prior into 5-10 lines.
-
-**Monitoring signal:**
-
-If the agent finds itself reading large files repeatedly or summarizing the same fact across multiple turns, that's a budget signal. Compact memory and explicitly drop unrelated loaded context before proceeding. Note this in `MEMORY.md` under Handoff Notes so the next task starts lean.
-
-This budget is doctrine, not a hard gate. No command currently rejects work for exceeding 40k. The discipline lives here because future sessions read this skill first.
+For context budget, read `references/context-budget.md`. Load only when this part of the task applies.
 
 ## Error Handling
 
@@ -199,7 +153,7 @@ Ported from Compozy's `cy-workflow-memory` skill (`/tmp/compozy/.agents/skills/c
 
 - Paths are `.dw/spec/<prd-slug>/` instead of `.compozy/tasks/<name>/`.
 - Task-local file is `<N>_memory.md` next to `<N>_task.md` (mirrors the existing dev-workflow task layout).
-- Inline Compaction Rules (Compozy keeps them in `references/memory-guidelines.md`); the budget discipline was extracted to `references/context-budget.md` because it's about model behavior, not file management.
+- Inline Compaction Rules (Compozy keeps them in its upstream memory-guidelines reference); the budget discipline was extracted to `references/context-budget.md` because it's about model behavior, not file management.
 
 Credit: Compozy project (https://github.com/compozy/compozy).
 

package/scaffold/skills/dw-memory/references/context-budget.md

@@ -1,63 +1,15 @@
-# Context Budget — Discipline
+# Context and memory budget
 
-A working context window is finite. Past about 40k tokens of active content, model output quality degrades — the model starts to miss requirements, lose constraints, blur details across sources, and revert to training-set averages. This file codifies the discipline that keeps active context lean across a long dev-workflow session.
+Read when memory grows or repeated exploration obscures the active task. Context capacity and compaction behavior vary by host/model; do not assume a universal 40k active limit or 120k reserve. A model may expose telemetry; label estimates and unknown usage accurately.
 
-## The numbers
+Keep relevant requirements, constraints, decisions, pending work and evidence available. Read sections or query indexes when that answers the question. Comparing PRDs/designs or tracing source plus dependencies can require multiple sources; do not prohibit necessary co-loading. Avoid bulk-loading unrelated archived summaries or task memories.
 
-- **Target active load:** under **40k tokens** total — PRD, TechSpec, tasks, MEMORY.md, per-task memory, all open files together.
-- **Reasoning reserve:** **120k+ tokens** of headroom for tool output, model thinking, and response generation.
-- **Soft alert:** when active load crosses **30k tokens**, plan to compact before the next major task.
-- **Compaction threshold for `MEMORY.md`:** ≤ 6KB on disk.
-- **Compaction threshold for `<N>_memory.md`:** ≤ 3KB on disk.
+Use concise durable memory: target MEMORY.md at most 6KB and per-task memory at most 3KB, moving detailed logs to linked artifacts. These are project maintenance targets, not model capacity claims or task-completion gates. Preserve unresolved decisions, acceptance criteria, session identity and evidence when compacting.
 
-These are doctrine, not enforced by any hard gate. The cost of breaking them is degraded output, not a command failure. Catch it yourself; the framework can't.
+Repeated reads, growing summaries and confused task boundaries are reasons to inspect context use, not proof of exceeding a hidden token threshold. Update the checkpoint if context limits threaten continuity; otherwise continue authorized work. Do not promise to evict individual messages from a host's context.
 
-## The anti-co-load rules
+Use `../../dw-codebase-intel/references/query-patterns.md` for indexed queries when useful. Verification failures still require diagnosing actual code/environment; do not attribute them to context size without evidence.
 
-Each is a "do not load both simultaneously" pairing. Pick one; if you must consult the other, summarize it to 5–10 lines first and drop the full version.
+## Attribution
 
-1. **Two PRDs at once.** Working on `prd-foo`, then user asks about `prd-bar`? Finish `prd-foo`'s active turn first, drop its spec/techspec/tasks from active context, then load `prd-bar`. Never carry both spec sets.
-
-2. **Multiple archived bugfix SUMMARY.md files.** Bugfix history queries should go through `.dw/intel/bugfixes.json` (compact, indexed), not by reading 20 SUMMARY.md files. Read individual SUMMARY.md only when the user is acting on that specific fix.
-
-3. **Files.json + deps.json simultaneously.** They overlap. Each query has a primary file per `dw-codebase-intel/references/query-patterns.md`. Pick the primary; consult the secondary only if the primary returns nothing.
-
-4. **A design proposal AND its predecessor's full text.** When comparing two designs, summarize the older one to 5–10 lines (the deltas the new one addresses) and reference it that way. Don't carry both in full.
-
-5. **Per-task memories from non-adjacent tasks.** Only the current task's `<N>_memory.md` and the immediately-previous one (for handoff) belong in active context. Older `<N>_memory.md` files are durable storage — read them when explicitly handing back to an old task, not as part of routine loading.
-
-## The monitoring signal
-
-You will not see a token counter. You can't measure your own budget directly. But these are observable proxies that mean **you are over budget**:
-
-- You are reading the same file twice in the same session without it having changed.
-- You are summarizing the same fact across multiple turns to keep it in scope.
-- You are answering questions by re-deriving from the repo what a memory file would tell you in one line.
-- You are confusing details between two PRDs, tasks, or designs.
-- Your turn outputs are getting longer to compensate for context that is silently slipping out of the model's attention.
-
-When you notice any of these, stop:
-
-1. Compact `MEMORY.md` and the active `<N>_memory.md` per the Compaction Rules in `SKILL.md`.
-2. Explicitly state in chat what you are dropping from active context.
-3. Note the budget event in `MEMORY.md` under Handoff Notes ("compacted at task N — see this section for what was dropped").
-4. Resume the turn.
-
-## What is NOT a budget problem
-
-These look like budget problems but aren't — don't compact for them:
-
-- **A genuinely complex task.** Some features legitimately need many files. Read what you need; the alternative (working from partial context) is worse.
-- **A long verification report.** Verify output can be long. Don't summarize it before logging it to disk; truncate the chat surface, not the artifact.
-- **A long user message.** The user wrote what they wrote. Don't compact to shave their words.
-- **The first PRD load of a new feature.** First-load is fine; second-load of the same PRD in the same turn is the signal.
-
-## Integration with other skills
-
-- **`dw-memory` (this skill)**: compaction is the lever for memory files; this file describes when and why.
-- **`dw-codebase-intel`**: `query-patterns.md` defines the primary-vs-secondary rule that anti-co-load rule #3 references.
-- **`dw-verify`**: a budget-related degradation may show up as a verify regression. If verify keeps failing on facts the PRD already states, suspect budget before suspecting code.
-
-## Source
-
-Adapted from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). The 40k target, the anti-co-load principle, and the monitoring-signal framing come from there. The specific anti-co-load pairings, file-size ceilings, and the integration with `dw-memory`/`dw-codebase-intel` are dev-workflow-specific.
+The earlier context-budget guidance adapted tech-leads-club's [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). This revision retains scoped retrieval and durable handoffs; rejects universal token thresholds and unconditional anti-co-loading rules. See docs/skills-ecosystem-comparison.md in the package source for the modernization decision.

package/scaffold/skills/dw-memory/references/promotion-decision-test-detail.md

@@ -0,0 +1,30 @@
+## Promotion Decision Test
+
+Before promoting an item from `<N>_memory.md` to `MEMORY.md`, ask:
+
+1. Will another task need this to avoid a mistake or rediscovery?
+2. Is this fact durable across multiple runs, not just the current execution?
+3. Is this information NOT already obvious from the PRD, TechSpec, task files, or the repository itself?
+
+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")
+- An open risk future tasks must account for ("migration depends on schema v3 which is not yet deployed to staging")
+
+### Stays in task memory
+- Files touched during this task's implementation
+- Debugging steps taken to resolve a task-specific error
+- The current task's objective and acceptance criteria snapshot
+- A workaround applied only to the current task's scope

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

@@ -1,6 +1,6 @@
 ---
 name: dw-minimalism
-description: Pre-generation YAGNI gate. Before writing new code, infra, or abstractions, climb the decision ladder (need it? reuse? stdlib? native? installed dep? one line?) at the active lite/full/ultra intensity. Triggers from /dw-run, /dw-plan, /dw-review and any "add X / build Y" intent.
+description: Evaluate a proposed abstraction, module or dependency for unnecessary complexity during planning or a focused over-engineering review.
 allowed-tools:
   - Read
   - Grep
@@ -11,8 +11,7 @@ allowed-tools:
 # dw-minimalism — Write the Least Code That Solves the Problem
 
 The cheapest code to maintain is the code you never wrote. This skill runs a
-**pre-generation gate**: before producing a new function, file, dependency, or
-abstraction, justify it against a decision ladder. It is the missing rung
+**pre-generation gate**: when evaluating a proposed abstraction or module, assess its necessity against the task requirements. It is the missing rung
 between `dw-search-first` (which evaluates *external dependencies*) and
 `dw-simplification` (which cleans up code *after* it exists).
 
@@ -21,9 +20,9 @@ between `dw-search-first` (which evaluates *external dependencies*) and
 Read this skill when:
 
 - `/dw-plan` is about to specify new modules/services — pressure-test scope before tasks are written.
-- `/dw-run` is about to implement — climb the ladder before the first line of new code.
+- A task proposes an abstraction or module whose necessity is unclear.
 - `/dw-review` flags over-engineering (speculative generality, premature abstraction, unused options).
-- The user (or a task) says "add X", "build Y", "create a helper/wrapper/abstraction for Z".
+- The user asks to assess whether a helper, wrapper, abstraction or dependency is necessary.
 
 Do NOT use to:
 

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

@@ -34,60 +34,7 @@ Report only findings you are **>80% confident** are real. A style preference no
 
 ## The Five Rules
 
-### 1. De-duplicate before writing
-
-If the same pattern (e.g., missing null check, unhandled error, magic constant) appears in multiple files, **create one finding** for the most representative instance and list the other affected files inside its body. Do not create N identical findings for N files sharing one root cause.
-
-Example — wrong:
-```
-- [HIGH] src/a.ts:14 — missing null check on user
-- [HIGH] src/b.ts:22 — missing null check on user
-- [HIGH] src/c.ts:31 — missing null check on user
-```
-
-Example — right:
-```
-- [HIGH] Missing null check on `user` in 3 places.
-  Representative: src/a.ts:14
-  Also affects: src/b.ts:22, src/c.ts:31
-  Fix: add `if (!user) return` at function entry.
-```
-
-### 2. Severity-order the output
-
-Always present findings in this order: **critical → high → medium → low**. Inside each severity, order by impact or blast radius, not by file path.
-
-Severity definitions:
-- **critical** — correctness bug, security hole, data loss, unavailability.
-- **high** — material deviation from PRD/TechSpec, concurrency hazard, significant perf regression, missing error handling on a user path.
-- **medium** — maintainability cost that will hurt the next change, missing edge-case handling, inconsistent with project rules.
-- **low** — stylistic, naming, minor readability. Often omit unless pattern-level.
-
-### 3. Verify intent before flagging
-
-Before creating a finding, check whether the pattern is intentional:
-- adjacent comment explaining the choice?
-- ADR in `.dw/spec/*/adrs/` that justifies it?
-- test coverage that asserts the behavior?
-- rule in `.dw/rules/` that permits it?
-
-If the code looks suspicious but has a clear justification (e.g., `// intentionally ignoring close error on read-only handle`), do NOT create a finding. Only flag patterns that are genuinely problematic, not merely unconventional.
-
-### 4. Skip what linters already catch
-
-Before writing findings, ensure the project's linter/formatter has run. Anything the configured linter would flag is NOT a finding in this review — it is a linter task. Save human attention for issues linters cannot find (logic, architecture, security, requirements).
-
-If the linter cannot run (missing tooling, build errors), note that in the summary and proceed with the review.
-
-### 5. Signal over volume
-
-Aim for fewer, higher-quality findings.
-
-- Keep ALL `critical` and `high`.
-- If total findings exceed 20, prune `medium` and `low` to the most impactful ones.
-- A review with 8 precise findings is more useful than one with 30 that includes marginal concerns.
-
-**Also note well-implemented aspects.** They inform the summary and calibrate tone — but they do not produce findings.
+For the five rules, read `references/the-five-rules-detail.md`. Load only when this part of the task applies.
 
 ## Prior-Round Awareness
 

package/scaffold/skills/dw-review-rigor/references/the-five-rules-detail.md

@@ -0,0 +1,56 @@
+## The Five Rules
+
+### 1. De-duplicate before writing
+
+If the same pattern (e.g., missing null check, unhandled error, magic constant) appears in multiple files, **create one finding** for the most representative instance and list the other affected files inside its body. Do not create N identical findings for N files sharing one root cause.
+
+Example — wrong:
+```
+- [HIGH] src/a.ts:14 — missing null check on user
+- [HIGH] src/b.ts:22 — missing null check on user
+- [HIGH] src/c.ts:31 — missing null check on user
+```
+
+Example — right:
+```
+- [HIGH] Missing null check on `user` in 3 places.
+  Representative: src/a.ts:14
+  Also affects: src/b.ts:22, src/c.ts:31
+  Fix: add `if (!user) return` at function entry.
+```
+
+### 2. Severity-order the output
+
+Always present findings in this order: **critical → high → medium → low**. Inside each severity, order by impact or blast radius, not by file path.
+
+Severity definitions:
+- **critical** — correctness bug, security hole, data loss, unavailability.
+- **high** — material deviation from PRD/TechSpec, concurrency hazard, significant perf regression, missing error handling on a user path.
+- **medium** — maintainability cost that will hurt the next change, missing edge-case handling, inconsistent with project rules.
+- **low** — stylistic, naming, minor readability. Often omit unless pattern-level.
+
+### 3. Verify intent before flagging
+
+Before creating a finding, check whether the pattern is intentional:
+- adjacent comment explaining the choice?
+- ADR in `.dw/spec/*/adrs/` that justifies it?
+- test coverage that asserts the behavior?
+- rule in `.dw/rules/` that permits it?
+
+If the code looks suspicious but has a clear justification (e.g., `// intentionally ignoring close error on read-only handle`), do NOT create a finding. Only flag patterns that are genuinely problematic, not merely unconventional.
+
+### 4. Skip what linters already catch
+
+Before writing findings, ensure the project's linter/formatter has run. Anything the configured linter would flag is NOT a finding in this review — it is a linter task. Save human attention for issues linters cannot find (logic, architecture, security, requirements).
+
+If the linter cannot run (missing tooling, build errors), note that in the summary and proceed with the review.
+
+### 5. Signal over volume
+
+Aim for fewer, higher-quality findings.
+
+- Keep ALL `critical` and `high`.
+- If total findings exceed 20, prune `medium` and `low` to the most impactful ones.
+- A review with 8 precise findings is more useful than one with 30 that includes marginal concerns.
+
+**Also note well-implemented aspects.** They inform the summary and calibrate tone — but they do not produce findings.

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

@@ -30,64 +30,11 @@ Do NOT use when:
 
 ## The Five Rules
 
-### 1. Chesterton's Fence — understand BEFORE changing
-
-Before removing or rewriting any code, answer three questions:
-
-1. **What does it actually do?** Run/trace it; don't guess from the name.
-2. **Why was it added?** Check `git log --follow <file> --oneline` and look at the introducing commit's message + PR. Often there's a reason.
-3. **What breaks if it's gone?** Search for callers. Run the test suite to find what changes.
-
-If you can't answer all three, you're not ready to simplify. Get answers first.
-
-Concrete cases where Chesterton's Fence saves you:
-- A "redundant" early return that handles a race condition.
-- A "useless" type cast that fixes a compiler bug on a specific platform.
-- A "duplicated" check that exists for clarity at the API boundary.
-- A "dead" branch that runs only with a feature flag enabled in production.
-
-### 2. Preserve behavior exactly
-
-The test for "did I simplify or did I change?" is: do the existing tests still pass without modification? If yes, behavior is preserved. If you needed to update tests, you changed behavior — that's a refactor, not a simplification.
-
-When tests are inadequate to confirm behavior preservation, write tests FIRST that document current behavior, then simplify against them. This is the test characterization technique.
-
-### 3. Follow project conventions
-
-Match what the project already does. If files use 2-space indent and arrow functions, your simplified version uses 2-space indent and arrow functions — even if you'd prefer 4-space and `function`. Conventions matter more than personal preference; consistency is itself a form of clarity.
-
-Project conventions live in `.dw/rules/<module>.md` (from `/dw-analyze-project`). Read first.
-
-### 4. Prefer clarity over cleverness
-
-Rules of thumb:
-
-- A line of code that takes 30 seconds to understand is worse than three lines that take 5 seconds each.
-- A "neat trick" with comments is uglier than the boring obvious code without comments.
-- Optimization that costs readability needs measurement (`dw-performance` skill territory) — without numbers, prefer the readable version.
-- "Magic" that requires knowing a language feature most teammates haven't used is anti-clarity. Use it only when the alternative is genuinely worse.
-
-### 5. Scope to recent changes
-
-Don't go simplifying old code while you're "in there". The risk-to-benefit ratio of changing 5-year-old battle-tested code is bad. Limit simplification to:
-
-- Code you just wrote in this session.
-- Code your current task touches.
-- Code with explicit recent breakage (e.g., a bug just fixed that revealed bad structure).
-
-Out of scope: any other code, no matter how ugly. Open a task / ADR for those instead of fixing in-flight.
+For the five rules, read `references/the-five-rules-detail.md`. Load only when this part of the task applies.
 
 ## Pattern recognition
 
-Frequent simplification targets — but apply Rules 1-5 before acting:
-
-| Smell | Healthy refactor | When NOT to refactor |
-|-------|------------------|----------------------|
-| Deep nesting (4+ levels) | Early returns / guard clauses | When the nesting maps to a real domain hierarchy (e.g., visitor pattern) |
-| Long function (>50 lines) | Extract method | When the "natural" extraction would produce 3-4 single-call helpers — you're trading complexity for indirection |
-| Generic name (`data`, `info`, `helper`) | Rename to specific | When the function genuinely processes generic input (e.g., a serializer middleware) |
-| Duplication (same 5 lines twice) | Extract to function/constant | When the duplication is by design (e.g., independent business rules that may diverge) |
-| `if/elif/else` chain (5+ branches) | Strategy pattern / lookup table | When the branches are naturally exclusive states with branch-specific logic |
+For pattern recognition, read `references/pattern-recognition-detail.md`. Load only when this part of the task applies.
 
 ## Rule of 500 — automate large refactors
 

package/scaffold/skills/dw-simplification/references/pattern-recognition-detail.md

@@ -0,0 +1,11 @@
+## Pattern recognition
+
+Frequent simplification targets — but apply Rules 1-5 before acting:
+
+| Smell | Healthy refactor | When NOT to refactor |
+|-------|------------------|----------------------|
+| Deep nesting (4+ levels) | Early returns / guard clauses | When the nesting maps to a real domain hierarchy (e.g., visitor pattern) |
+| Long function (>50 lines) | Extract method | When the "natural" extraction would produce 3-4 single-call helpers — you're trading complexity for indirection |
+| Generic name (`data`, `info`, `helper`) | Rename to specific | When the function genuinely processes generic input (e.g., a serializer middleware) |
+| Duplication (same 5 lines twice) | Extract to function/constant | When the duplication is by design (e.g., independent business rules that may diverge) |
+| `if/elif/else` chain (5+ branches) | Strategy pattern / lookup table | When the branches are naturally exclusive states with branch-specific logic |

package/scaffold/skills/dw-simplification/references/the-five-rules-detail.md

@@ -0,0 +1,48 @@
+## The Five Rules
+
+### 1. Chesterton's Fence — understand BEFORE changing
+
+Before removing or rewriting any code, answer three questions:
+
+1. **What does it actually do?** Run/trace it; don't guess from the name.
+2. **Why was it added?** Check `git log --follow <file> --oneline` and look at the introducing commit's message + PR. Often there's a reason.
+3. **What breaks if it's gone?** Search for callers. Run the test suite to find what changes.
+
+If you can't answer all three, you're not ready to simplify. Get answers first.
+
+Concrete cases where Chesterton's Fence saves you:
+- A "redundant" early return that handles a race condition.
+- A "useless" type cast that fixes a compiler bug on a specific platform.
+- A "duplicated" check that exists for clarity at the API boundary.
+- A "dead" branch that runs only with a feature flag enabled in production.
+
+### 2. Preserve behavior exactly
+
+The test for "did I simplify or did I change?" is: do the existing tests still pass without modification? If yes, behavior is preserved. If you needed to update tests, you changed behavior — that's a refactor, not a simplification.
+
+When tests are inadequate to confirm behavior preservation, write tests FIRST that document current behavior, then simplify against them. This is the test characterization technique.
+
+### 3. Follow project conventions
+
+Match what the project already does. If files use 2-space indent and arrow functions, your simplified version uses 2-space indent and arrow functions — even if you'd prefer 4-space and `function`. Conventions matter more than personal preference; consistency is itself a form of clarity.
+
+Project conventions live in `.dw/rules/<module>.md` (from `/dw-analyze-project`). Read first.
+
+### 4. Prefer clarity over cleverness
+
+Rules of thumb:
+
+- A line of code that takes 30 seconds to understand is worse than three lines that take 5 seconds each.
+- A "neat trick" with comments is uglier than the boring obvious code without comments.
+- Optimization that costs readability needs measurement (`dw-performance` skill territory) — without numbers, prefer the readable version.
+- "Magic" that requires knowing a language feature most teammates haven't used is anti-clarity. Use it only when the alternative is genuinely worse.
+
+### 5. Scope to recent changes
+
+Don't go simplifying old code while you're "in there". The risk-to-benefit ratio of changing 5-year-old battle-tested code is bad. Limit simplification to:
+
+- Code you just wrote in this session.
+- Code your current task touches.
+- Code with explicit recent breakage (e.g., a bug just fixed that revealed bad structure).
+
+Out of scope: any other code, no matter how ugly. Open a task / ADR for those instead of fixing in-flight.

package/scaffold/skills/dw-source-grounding/SKILL.md

@@ -34,62 +34,7 @@ Do NOT use when:
 
 ## The Protocol — Detect → Fetch → Implement → Cite
 
-### 1. Detect — read the actual version first
-
-Before researching anything, read the project's manifest and identify the EXACT version of the library/framework that matters:
-
-| Stack | File | Field |
-|-------|------|-------|
-| Node/TS | `package.json` | `dependencies`, `devDependencies` |
-| Python | `pyproject.toml`, `requirements*.txt`, `Pipfile.lock` | each dep with version |
-| .NET | `*.csproj`, `packages.lock.json` | `PackageReference Version="..."` |
-| Rust | `Cargo.toml`, `Cargo.lock` | `[dependencies]` |
-
-Record the version. If a range (`^4.18.0`), note the lockfile-resolved version.
-
-If no manifest exists OR the dep is not yet in the manifest (e.g., choosing what to install), record "no version yet — choosing fresh".
-
-### 2. Fetch — pull the matching version's official docs
-
-Authority hierarchy:
-
-1. **Official docs** for the EXACT version (or nearest stable). E.g., `react.dev/reference/react?version=18` not `react.dev` default.
-2. **Official changelog / migration guide** when transitioning across versions.
-3. **Web standards** (MDN, RFCs, W3C) for cross-implementation behavior.
-4. **Compatibility tables** (caniuse, Compat data) for API support across runtimes.
-
-Forbidden as primary source:
-
-- Stack Overflow answers (use only as discovery, then verify via official).
-- Tutorial blogs (frequently outdated; never authoritative).
-- AI training data (your training is months/years stale).
-- README screenshots from random GitHub repos.
-
-Fetch via `WebFetch` or `mcp__context7__*` if available. If both fail, surface to the user that you're falling back to training-data knowledge AND mark the citation `[source: training-data, unverified]`.
-
-### 3. Implement — apply the documented pattern
-
-Use exactly the API the documented version provides. Don't mix patterns from multiple versions ("this useEffect example is from React 16; you're on 18.3"). When the doc shows multiple acceptable patterns, pick the simplest that matches the project's style.
-
-If the doc presents migration warnings (e.g., "deprecated in v5, use X instead"), follow the new path unless the project explicitly pins to the old version for a documented reason.
-
-### 4. Cite — record the source verifiably
-
-Every decision that depended on an external source ends with a citation block:
-
-```
-[source: <url>, version: <X.Y>, retrieved: <YYYY-MM-DD>]
-```
-
-Examples:
-
-```
-[source: https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2026-05-07]
-[source: https://docs.python.org/3.12/library/asyncio-task.html, version: 3.12, retrieved: 2026-05-07]
-[source: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html, version: SDK v3, retrieved: 2026-05-07]
-```
-
-When citing in PRDs, techspecs, decision logs, or deps-audit reports, the citation is mandatory adjacent to each claim. A future engineer reading the doc can click and verify.
+For the protocol — detect → fetch → implement → cite, read `references/the-protocol-detect-fetch-implement-cite-detail.md`. Load only when this part of the task applies.
 
 ## How `dw-create-techspec` uses this
 

package/scaffold/skills/dw-source-grounding/references/the-protocol-detect-fetch-implement-cite-detail.md

@@ -0,0 +1,58 @@
+## The Protocol — Detect → Fetch → Implement → Cite
+
+### 1. Detect — read the actual version first
+
+Before researching anything, read the project's manifest and identify the EXACT version of the library/framework that matters:
+
+| Stack | File | Field |
+|-------|------|-------|
+| Node/TS | `package.json` | `dependencies`, `devDependencies` |
+| Python | `pyproject.toml`, `requirements*.txt`, `Pipfile.lock` | each dep with version |
+| .NET | `*.csproj`, `packages.lock.json` | `PackageReference Version="..."` |
+| Rust | `Cargo.toml`, `Cargo.lock` | `[dependencies]` |
+
+Record the version. If a range (`^4.18.0`), note the lockfile-resolved version.
+
+If no manifest exists OR the dep is not yet in the manifest (e.g., choosing what to install), record "no version yet — choosing fresh".
+
+### 2. Fetch — pull the matching version's official docs
+
+Authority hierarchy:
+
+1. **Official docs** for the EXACT version (or nearest stable). E.g., `react.dev/reference/react?version=18` not `react.dev` default.
+2. **Official changelog / migration guide** when transitioning across versions.
+3. **Web standards** (MDN, RFCs, W3C) for cross-implementation behavior.
+4. **Compatibility tables** (caniuse, Compat data) for API support across runtimes.
+
+Forbidden as primary source:
+
+- Stack Overflow answers (use only as discovery, then verify via official).
+- Tutorial blogs (frequently outdated; never authoritative).
+- AI training data (your training is months/years stale).
+- README screenshots from random GitHub repos.
+
+Fetch via `WebFetch` or `mcp__context7__*` if available. If both fail, surface to the user that you're falling back to training-data knowledge AND mark the citation `[source: training-data, unverified]`.
+
+### 3. Implement — apply the documented pattern
+
+Use exactly the API the documented version provides. Don't mix patterns from multiple versions ("this useEffect example is from React 16; you're on 18.3"). When the doc shows multiple acceptable patterns, pick the simplest that matches the project's style.
+
+If the doc presents migration warnings (e.g., "deprecated in v5, use X instead"), follow the new path unless the project explicitly pins to the old version for a documented reason.
+
+### 4. Cite — record the source verifiably
+
+Every decision that depended on an external source ends with a citation block:
+
+```
+[source: <url>, version: <X.Y>, retrieved: <YYYY-MM-DD>]
+```
+
+Examples:
+
+```
+[source: https://react.dev/reference/react/useEffect, version: 18.3, retrieved: 2026-05-07]
+[source: https://docs.python.org/3.12/library/asyncio-task.html, version: 3.12, retrieved: 2026-05-07]
+[source: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html, version: SDK v3, retrieved: 2026-05-07]
+```
+
+When citing in PRDs, techspecs, decision logs, or deps-audit reports, the citation is mandatory adjacent to each claim. A future engineer reading the doc can click and verify.