@hegemonart/get-design-done 1.42.0 → 1.44.0

package/skills/debug/debug-feedback-loops.md

@@ -7,7 +7,7 @@ tags: [debug, feedback-loop, deterministic-signal, iterate-on-loop, mit-port, ma
 last_updated: 2026-05-18
 ---
 
-Source: mattpocock/skills (MIT) — engineering/diagnose Phase 1 — adapted with permission. See `../NOTICE` for the full attribution block.
+Source: mattpocock/skills (MIT) - engineering/diagnose Phase 1 - adapted with permission. See `../NOTICE` for the full attribution block.
 
 # Debug Feedback Loops
 
@@ -17,7 +17,7 @@ Build a feedback loop before any hypothesizing. A feedback loop is a determinist
 
 ## The 10 construction paths
 
-Listed in priority order — try the cheaper, faster paths first. Each entry: when to reach for it, the shape of the loop, and the verification snippet.
+Listed in priority order - try the cheaper, faster paths first. Each entry: when to reach for it, the shape of the loop, and the verification snippet.
 
 ### 1. Failing test
 
@@ -45,7 +45,7 @@ When to reach: the bug is visible only in a rendered browser context; DOM-level
 
 ### 5. Trace replay
 
-For bugs reproducible from a captured execution trace, replay the trace deterministically. `rr` on Linux for native binaries, record-and-replay plugins for some browsers, Chrome DevTools recording for web, or a captured production trace for distributed systems. Replays are bit-for-bit reproducible — the gold standard for non-deterministic bugs that have been captured once.
+For bugs reproducible from a captured execution trace, replay the trace deterministically. `rr` on Linux for native binaries, record-and-replay plugins for some browsers, Chrome DevTools recording for web, or a captured production trace for distributed systems. Replays are bit-for-bit reproducible - the gold standard for non-deterministic bugs that have been captured once.
 
 When to reach: the bug is hard to reproduce live but you have a captured trace; the trace runtime is available; bit-identical replay is achievable.
 
@@ -75,7 +75,7 @@ When to reach: a known-good reference implementation exists; the buggy code is s
 
 ### 10. HITL bash (Human In The Loop)
 
-Last resort. A documented sequence of bash commands a human runs that produces a pass/fail signal. Slower (human in the path), but better than no loop. The agent reads stdout/stderr; the human reads the screen and reports. Use only when no automatable signal is available — physical hardware, vendor portals, manual eyeball checks.
+Last resort. A documented sequence of bash commands a human runs that produces a pass/fail signal. Slower (human in the path), but better than no loop. The agent reads stdout/stderr; the human reads the screen and reports. Use only when no automatable signal is available - physical hardware, vendor portals, manual eyeball checks.
 
 When to reach: every other path is blocked by an unautomatable surface; the human cost is acceptable for the duration of the investigation; the loop will be retired or upgraded the moment any earlier path becomes possible.
 
@@ -86,20 +86,20 @@ The loop is a first-class artifact. Iterate on it before iterating on hypotheses
 - **Cache setup**: hoist expensive setup (DB seed, fixture load, container start) out of the loop body. Run the loop only on the fast inner part. Use `--no-rebuild`, persistent containers, or test-runner watch modes.
 - **Narrow scope**: if the loop runs the full test suite to verify one bug, narrow to just the failing test/group. Fewer side-effects, faster iterations. `pytest -k`, `jest -t`, `vitest --testNamePattern`, `go test -run` are your friends.
 - **Pin time**: when the bug is time-dependent, freeze the clock (`sinon.useFakeTimers`, `jest.useFakeTimers`, `freezegun`, `time-machine`). Removes wallclock as a variable.
-- **Seed RNG**: every random source gets a fixed seed in the loop. `Math.random`, `crypto.randomBytes`, `random.seed(...)`, `rand::SeedableRng`. Determinism over coverage — the loop must be bit-identical given the same code state.
+- **Seed RNG**: every random source gets a fixed seed in the loop. `Math.random`, `crypto.randomBytes`, `random.seed(...)`, `rand::SeedableRng`. Determinism over coverage - the loop must be bit-identical given the same code state.
 - **Isolate filesystem**: run in a `tmpdir`; reset between iterations. Avoids "fixed on my machine" via stale state. Bind-mount or copy fixtures into the tmpdir per iteration.
 - **Freeze network**: mock or record/replay all outbound calls (`nock`, `vcr`, `polly.js`, `mitmproxy --replay`). Real-network loops are non-deterministic by definition.
 
-The discipline: every iteration of the loop should be bit-identical given the same code state. If two iterations differ without a code change, the loop has a hidden input — find it and pin it before continuing.
+The discipline: every iteration of the loop should be bit-identical given the same code state. If two iterations differ without a code change, the loop has a hidden input - find it and pin it before continuing.
 
 ## Non-deterministic bugs
 
-Some bugs surface only sometimes. The goal is NOT a clean repro — the goal is to raise the reproduction rate to debuggable.
+Some bugs surface only sometimes. The goal is NOT a clean repro - the goal is to raise the reproduction rate to debuggable.
 
 - **Measure baseline rate**: run the loop N=20 times. Note pass/fail count. Record the rate so you can tell whether later changes helped.
 - **Raise stressors**: add concurrency, contention, memory pressure, network jitter (use `tc qdisc add dev lo root netem delay 100ms 50ms` on Linux, `Network Link Conditioner` on macOS). Re-measure.
 - **Target the suspect axis**: if you suspect a race, add a deterministic sleep at the suspect point and measure. If reproduction jumps to 100% with sleep, the race is in that region. If it stays at baseline, the race is elsewhere.
-- **A 30% reproduction rate is debuggable.** A 5% rate isn't — keep raising stressors until you cross 30%. At 30% you can iterate; at 5% you're guessing whether your fix helped or you got lucky.
+- **A 30% reproduction rate is debuggable.** A 5% rate isn't - keep raising stressors until you cross 30%. At 30% you can iterate; at 5% you're guessing whether your fix helped or you got lucky.
 
 ## When the loop is good enough
 
@@ -107,13 +107,13 @@ The loop is good enough when:
 
 - It runs in under a minute (preferably under 10 seconds).
 - It's deterministic (or, for non-determinism, reproduces at least 30% of the time).
-- It's automatable — no human in the inner loop except by explicit choice (Path 10).
+- It's automatable - no human in the inner loop except by explicit choice (Path 10).
 - A fresh agent could pick up the loop and run it without context.
 
 Only after the loop is good enough should you proceed to hypothesizing the fix. The hypothesis cycle is governed by `./debugger-philosophy.md` (one variable at a time, do not stop at first plausible cause, the bug is where you didn't look).
 
 ## Cross-references
 
-- `./debugger-philosophy.md` — companion framing; the hypothesis-cycle discipline that runs in Phase 2 once the loop is in place.
-- `../skills/debug/SKILL.md` — Phase 1 of the debug skill mandates this catalog before any hypothesis generation.
-- `../NOTICE` — full mattpocock/skills MIT attribution.
+- `./debugger-philosophy.md` - companion framing; the hypothesis-cycle discipline that runs in Phase 2 once the loop is in place.
+- `../skills/debug/SKILL.md` - Phase 1 of the debug skill mandates this catalog before any hypothesis generation.
+- `../NOTICE` - full mattpocock/skills MIT attribution.

package/skills/design/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: true
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint
 ---
 
-# Get Design Done — Design
+# Get Design Done - Design
 
 **Stage 4 of 5** in the get-design-done pipeline. Thin orchestrator. All design execution intelligence lives in `agents/design-executor.md`.
 
@@ -28,25 +28,25 @@ Detail: `./design-procedure.md` §Stage entry.
 
 - `--auto` -> `auto_mode=true` (no mid-stage prompts; architectural deviations stop the individual task but continue the rest).
 - `--parallel` -> `parallel_mode=true` (use worktree isolation for `Parallel: true` tasks).
-- `--variants N` -> `variants_mode` (default N=2): for tasks that build a user-facing surface, the executor emits **N competing, hypothesis-tagged variants** (`<variant id component pattern hypothesis>`) instead of one. Before generating, consult the `design_arms` posterior (`scripts/lib/ds-arms/design-arms-store.cjs`) to bias toward patterns that have won prior A/B / user-research outcomes — **advisory, never directive** (the user's explicit choice always wins). The tagged variants flow to A/B (LaunchDarkly/Statsig/GrowthBook) for outcome ingestion. Full schema + the outcome loop: `../../reference/design-variants.md`.
+- `--variants N` -> `variants_mode` (default N=2): for tasks that build a user-facing surface, the executor emits **N competing, hypothesis-tagged variants** (`<variant id component pattern hypothesis>`) instead of one. Before generating, consult the `design_arms` posterior (`scripts/lib/ds-arms/design-arms-store.cjs`) to bias toward patterns that have won prior A/B / user-research outcomes - **advisory, never directive** (the user's explicit choice always wins). The tagged variants flow to A/B (LaunchDarkly/Statsig/GrowthBook) for outcome ingestion. Full schema + the outcome loop: `../../reference/design-variants.md`.
 - **Directionally-open check** (skipped if `auto_mode`): scan DESIGN-PLAN.md for tasks whose criteria read "explore N directions" / "pick a visual approach" and suggest `/gdd:sketch` first.
-- **Project-local conventions**: include any `./.claude/skills/design-*-conventions.md` and `~/.claude/gdd/global-skills/*.md` in every executor's `<required_reading>` — global conventions inform but do not override project-local D-XX decisions.
+- **Project-local conventions**: include any `./.claude/skills/design-*-conventions.md` and `~/.claude/gdd/global-skills/*.md` in every executor's `<required_reading>` - global conventions inform but do not override project-local D-XX decisions.
 - **`.stories.tsx` stub**: after each new component file is created by the executor, emit a CSF stub alongside if `.storybook/` exists or `"storybook"` is in `package.json`, even with the dev server offline. Detail: `./design-procedure.md` §.stories.tsx Stub.
 
 ---
 
-## Step 1 — Parse DESIGN-PLAN.md
+## Step 1 - Parse DESIGN-PLAN.md
 
 Read `.design/DESIGN-PLAN.md`. Partition tasks by `## Wave N` heading. Within each wave, partition by `Parallel: true` vs `Parallel: false`. Compute `total_tasks` for the `task_progress` denominator. If resuming, skip tasks whose `.design/tasks/task-NN.md` already exists.
 
 ---
 
-## Step 2 — Wave-by-Wave Execution
+## Step 2 - Wave-by-Wave Execution
 
 For each wave in order:
 
 1. **Parallelism decision (per wave)**: read `.design/config.json` `parallelism`, collect candidates, check `Touches:` / `writes:` / `parallel-safe` / `typical-duration-seconds`, apply `reference/parallelism-rules.md` hard->soft. Overlapping `Touches:` split into sequential sub-waves. Record verdict via `mcp__gdd_state__update_progress` with `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"`.
-2. **Executor STATE.md protocol** (inlined verbatim into every `design-executor` prompt): executors update STATE.md ONLY via `gdd-state` MCP tools — `update_progress`, `add_blocker`, `resolve_blocker`. NEVER `Read`+`Write` `.design/STATE.md` directly. The MCP tools enforce the lockfile (Plan 20-01) and emit mutation events (Plan 20-06) so concurrent executors serialize safely.
+2. **Executor STATE.md protocol** (inlined verbatim into every `design-executor` prompt): executors update STATE.md ONLY via `gdd-state` MCP tools - `update_progress`, `add_blocker`, `resolve_blocker`. NEVER `Read`+`Write` `.design/STATE.md` directly. The MCP tools enforce the lockfile (Plan 20-01) and emit mutation events (Plan 20-06) so concurrent executors serialize safely.
 3. **Parallel batch** (when `parallel_mode=true` AND any `Parallel: true` tasks in wave): announce the partition, spawn all `Parallel: true` tasks via concurrent `Task("design-executor", ..., isolation: "worktree")` calls in ONE response, wait for all `## EXECUTION COMPLETE` markers, merge worktrees (non-overlapping `Touches:` guarantees no conflicts; surface any conflict to the user before continuing), then `update_progress` + `checkpoint`.
 4. **Sequential tail** (`Parallel: false` or `parallel_mode=false`): spawn one `design-executor` at a time (no worktree isolation), waiting for each `## EXECUTION COMPLETE` and emitting `update_progress` per task; `checkpoint` after the final task of the wave.
 
@@ -54,11 +54,11 @@ Full executor prompts (parallel + sequential variants) and the merge-worktrees p
 
 ---
 
-## Step 3 — Wave Checkpoint
+## Step 3 - Wave Checkpoint
 
 After each wave, unless `auto_mode=true`, prompt: "Ready for Wave [N+1]? (yes / review first)". Skip in `auto_mode`.
 
-## Step 4 — Handle Deviations
+## Step 4 - Handle Deviations
 
 Check task-NN.md files for `status: deviation`. If found: `mcp__gdd_state__get` -> read `state.blockers`, present affected task IDs + blocker descriptions, offer (a) stop, (b) continue. `auto_mode`: continue, log. When a blocker is later fixed by a follow-up task: `mcp__gdd_state__resolve_blocker`.
 
@@ -66,8 +66,8 @@ Check task-NN.md files for `status: deviation`. If found: `mcp__gdd_state__get`
 
 ## State Update (exit)
 
-1. `mcp__gdd_state__set_status` -> `"design_complete"` — marks the stage complete WITHOUT transitioning (verify owns its own `transition_stage` on entry).
-2. `mcp__gdd_state__checkpoint` — stamps `last_checkpoint`, appends `design_completed_at` to `<timestamps>`.
+1. `mcp__gdd_state__set_status` -> `"design_complete"` - marks the stage complete WITHOUT transitioning (verify owns its own `transition_stage` on entry).
+2. `mcp__gdd_state__checkpoint` - stamps `last_checkpoint`, appends `design_completed_at` to `<timestamps>`.
 
 ## After Completion
 
@@ -83,14 +83,14 @@ After all tasks finish, if STATE.md `<connections>` has `figma: available`, offe
 Do NOT transition to verify (or invoke `/gdd:verify`) until `.design/DESIGN-SUMMARY.md` is committed. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
 </HARD-GATE>
 
-## Rationalizations — Thought to Reality
+## Rationalizations - Thought to Reality
 
 The excuses an agent uses to cut corners during design implementation, and the cost of each:
 
 | Thought | Reality |
 |---------|---------|
 | "I can skip planning for this small task and just implement it." | Plan-skipped tasks blow scope per cycle telemetry; the gate is for the typical case, not the exception. |
-| "These two tasks touch nearby files but I'll run them in parallel anyway." | Overlapping `Touches:` in a parallel batch produce merge conflicts that silently drop one task's work — split into sequential sub-waves. |
+| "These two tasks touch nearby files but I'll run them in parallel anyway." | Overlapping `Touches:` in a parallel batch produce merge conflicts that silently drop one task's work - split into sequential sub-waves. |
 | "Hardcoding this value is faster than wiring the token." | A hardcoded value is a stub the verifier catches as drift from the design tokens; you pay for it twice. |
 | "I'll emit the `.stories.tsx` stub later when Storybook is back up." | The CSF stub must land with the component or the next cycle's visual-regression scope misses it entirely. |
 | "This deviation is minor, I won't record a blocker." | An unrecorded deviation can't be resolved by a follow-up task, so it leaks into verify as an unexplained gap. |

package/skills/design/design-procedure.md

@@ -7,8 +7,8 @@ tags: [design, procedure, extracted, pipeline-stage, execute, wave-coordination]
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/design/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
-The skill's load-bearing workflow stays in `../skills/design/SKILL.md`; this file holds the
+Source: extracted from `skills/design/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/design/SKILL.md`; this file holds the
 detail the agent reaches for when executing a specific step (agent spawn prompts, wave
 coordination, executor STATE.md protocol, figma-write dispatch).
 
@@ -16,7 +16,7 @@ coordination, executor STATE.md protocol, figma-write dispatch).
 
 Detailed procedure for the get-design-done `design` Stage 4 orchestrator. Companion to
 `../skills/design/SKILL.md`. Read this file when executing a specific design step; the
-SKILL.md keeps the load-bearing wave-iteration workflow + decision tree, this file holds
+SKILL.md keeps the essential wave-iteration workflow + decision tree, this file holds
 the full executor prompts and parallelism semantics.
 
 ---
@@ -25,7 +25,7 @@ the full executor prompts and parallelism semantics.
 
 1. Call `mcp__gdd_state__transition_stage` with `to: "design"`.
    - Gate failure surfaces `error.context.blockers` to the user; do not advance.
-   - If the transition succeeds and the prior stage was already `design` with `status: in_progress`, this is a RESUME — use `task_progress` numerator as source of truth and skip tasks that already have a corresponding `.design/tasks/task-NN.md` file.
+   - If the transition succeeds and the prior stage was already `design` with `status: in_progress`, this is a RESUME - use `task_progress` numerator as source of truth and skip tasks that already have a corresponding `.design/tasks/task-NN.md` file.
 2. Call `mcp__gdd_state__get` -> snapshot `state`; read `state.position.wave` to decide execution plan.
 
 Abort only if `.design/DESIGN-PLAN.md` is missing:
@@ -40,17 +40,17 @@ Abort only if `.design/DESIGN-PLAN.md` is missing:
 
 ---
 
-## Pre-execution — Directionally-open check
+## Pre-execution - Directionally-open check
 
-Scan DESIGN-PLAN.md for tasks marked as "directionally open" (exploration-appropriate — e.g., tasks whose acceptance criteria read "explore N directions" or "pick a visual approach"). If any are found, print:
+Scan DESIGN-PLAN.md for tasks marked as "directionally open" (exploration-appropriate - e.g., tasks whose acceptance criteria read "explore N directions" or "pick a visual approach"). If any are found, print:
 
-> "Tasks [IDs] appear directionally open — consider running `/gdd:sketch` first to explore variants before implementation."
+> "Tasks [IDs] appear directionally open - consider running `/gdd:sketch` first to explore variants before implementation."
 
 Skip if `auto_mode=true`.
 
-## Pre-execution — Project-local conventions
+## Pre-execution - Project-local conventions
 
-When spawning the executor, include any `./.claude/skills/design-*-conventions.md` files in `<required_reading>` so the executor sees project-local design conventions (typography, color, layout, motion, component, interaction decisions codified from prior sketch wrap-ups). Also include any `~/.claude/gdd/global-skills/*.md` files if the directory exists — global skills are cross-project conventions that inform but do not override project-local D-XX decisions.
+When spawning the executor, include any `./.claude/skills/design-*-conventions.md` files in `<required_reading>` so the executor sees project-local design conventions (typography, color, layout, motion, component, interaction decisions codified from prior sketch wrap-ups). Also include any `~/.claude/gdd/global-skills/*.md` files if the directory exists - global skills are cross-project conventions that inform but do not override project-local D-XX decisions.
 
 ---
 
@@ -58,12 +58,12 @@ When spawning the executor, include any `./.claude/skills/design-*-conventions.m
 
 After every new component file is created by the design-executor:
 
-Step 1 — Check project detection (does not require server running):
+Step 1 - Check project detection (does not require server running):
   Bash: ls .storybook/ 2>/dev/null || grep '"storybook"' package.json 2>/dev/null
   -> Found -> storybook_project: true
   -> Not found -> skip .stories.tsx emission
 
-Step 2 — When storybook_project: true, emit a CSF stub alongside the component:
+Step 2 - When storybook_project: true, emit a CSF stub alongside the component:
   File: `<same directory as component>/<ComponentName>.stories.tsx`
   Content follows CSF format (see `connections/storybook.md` for full template):
   - Import `Meta` and `StoryObj` from `@storybook/react`
@@ -77,7 +77,7 @@ the dev server is running. New components need stories even in offline/CI contex
 
 ---
 
-## Step 1 — Parse DESIGN-PLAN.md
+## Step 1 - Parse DESIGN-PLAN.md
 
 Read `.design/DESIGN-PLAN.md`. Partition tasks by `## Wave N` heading. Within each wave, partition by `Parallel: true` vs `Parallel: false`. Compute `total_tasks` for `task_progress` denominator.
 
@@ -91,23 +91,23 @@ For each wave:
 1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
 2. Collect candidates in the wave; check `Touches:`, `writes:`, `parallel-safe`, and `typical-duration-seconds` fields.
 3. Apply rules in order from `reference/parallelism-rules.md` (hard -> soft). Overlapping Touches split into sequential sub-waves.
-4. Record the parallelism decision for this wave via `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"` — the status string is the canonical carrier (mirrors the plan-stage convention from Plan 20-09; a dedicated tool may be added in a follow-on plan).
+4. Record the parallelism decision for this wave via `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"` - the status string is the canonical carrier (mirrors the plan-stage convention from Plan 20-09; a dedicated tool may be added in a follow-on plan).
 5. If `parallel`: spawn all candidates via concurrent `Task()` calls in one response. If `serial`: spawn sequentially.
 
 ### Executor prompt template (applies to every spawned design-executor)
 
 Every spawned executor receives the following STATE.md contract in its prompt:
 
-> **STATE.md mutation protocol** — When you complete a task in your assigned batch, update STATE.md ONLY via the `gdd-state` MCP tools. Specifically:
+> **STATE.md mutation protocol** - When you complete a task in your assigned batch, update STATE.md ONLY via the `gdd-state` MCP tools. Specifically:
 > - Report task progress: `mcp__gdd_state__update_progress` with your new `task_progress` fraction.
 > - Add blockers: `mcp__gdd_state__add_blocker` with `{ stage: "design", date: <today>, text: "..." }`.
 > - Resolve your own blockers on fix: `mcp__gdd_state__resolve_blocker` with the blocker id.
 >
-> Do NOT `Read` + `Write` `.design/STATE.md` directly — the MCP tools enforce the lockfile and emit mutation events. Direct writes corrupt parallel state.
+> Do NOT `Read` + `Write` `.design/STATE.md` directly - the MCP tools enforce the lockfile and emit mutation events. Direct writes corrupt parallel state.
 
 Inline this protocol block verbatim inside every design-executor prompt in both the parallel-batch and sequential-tail spawns below. Concurrent executors (Phase 10.1 parallel mode) each emit `update_progress` calls; the lockfile (Plan 20-01) and event stream (Plan 20-06) serialize them safely.
 
-## Step 2 — Wave-by-Wave Execution
+## Step 2 - Wave-by-Wave Execution
 
 For each Wave in order (Wave 1, Wave 2, ...):
 
@@ -160,7 +160,7 @@ Emit `## EXECUTION COMPLETE` when done.
 
 Wait for all parallel tasks to emit `## EXECUTION COMPLETE`.
 
-**Merge worktrees** (preserved from v2.1.0 — do not redesign):
+**Merge worktrees** (preserved from v2.1.0 - do not redesign):
 
 ```
 === Parallel batch complete ===
@@ -176,7 +176,7 @@ Merge each worktree branch back into the working directory. Each agent touched n
 After merge, roll up the batch's progress:
 
 - Call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallel_batch_complete"`.
-- Call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
+- Call `mcp__gdd_state__checkpoint` - records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
 
 ### Sequential tail (Parallel: false tasks, or all tasks if `parallel_mode=false`)
 
@@ -222,11 +222,11 @@ Emit `## EXECUTION COMPLETE` when done.
 
 After each task completes, call `mcp__gdd_state__update_progress` with the new `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_task_<NN>_complete"`.
 
-After the final sequential task of the wave, call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
+After the final sequential task of the wave, call `mcp__gdd_state__checkpoint` - records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
 
 ---
 
-## Step 3 — Wave Checkpoint
+## Step 3 - Wave Checkpoint
 
 After each wave (unless `--auto` flag was passed):
 
@@ -243,7 +243,7 @@ Skip checkpoint if `auto_mode=true`.
 
 ---
 
-## Step 4 — Handle Deviations
+## Step 4 - Handle Deviations
 
 After each wave, check task-NN.md files for `status: deviation`. If any found:
 
@@ -256,8 +256,8 @@ After each wave, check task-NN.md files for `status: deviation`. If any found:
 
 ## State Update (exit)
 
-1. Call `mcp__gdd_state__set_status` with `status: "design_complete"` — marks the stage completed without transitioning; verify calls `transition_stage` on its entry, keeping the transition atomic with the owning stage.
-2. Call `mcp__gdd_state__checkpoint` — stamps `last_checkpoint` and appends a `design_completed_at` entry to `<timestamps>`.
+1. Call `mcp__gdd_state__set_status` with `status: "design_complete"` - marks the stage completed without transitioning; verify calls `transition_stage` on its entry, keeping the transition atomic with the owning stage.
+2. Call `mcp__gdd_state__checkpoint` - stamps `last_checkpoint` and appends a `design_completed_at` entry to `<timestamps>`.
 
 ---
 

package/skills/discover/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[--auto]"
 user-invocable: true
 ---
 
-# Get Design Done — Discover
+# Get Design Done - Discover
 
 **Stage 1.5 of 4.** Produces `.design/DESIGN-CONTEXT.md`.
 
@@ -16,10 +16,10 @@ Full procedure detail: `./discover-procedure.md`.
 ## State Integration
 
 1. Read `.design/STATE.md`.
-   - **Missing** -> create minimal skeleton from `reference/STATE-TEMPLATE.md` (stage=discover, status=in_progress, task_progress=0/1) and log warning "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
+   - **Missing** -> create minimal skeleton from `reference/STATE-TEMPLATE.md` (stage=discover, status=in_progress, task_progress=0/1) and log warning "STATE.md not found - created fresh. If this is a resumed session, run /get-design-done:scan first."
    - **Present + stage==discover + status==in_progress** -> RESUME (continue interview; do not reset).
    - **Otherwise** -> normal transition: set frontmatter stage=discover, `<position>` stage=discover, status=in_progress, task_progress=0/1.
-2. Probe connection availability. ToolSearch runs FIRST (MCP tools may be in the deferred tool set). Run three probes — A (Figma, variant-agnostic with prefix tiebreaker), B (Refero, ToolSearch-only), C (Pinterest, ToolSearch-only). After all probes, write `<connections>` to STATE.md so the builder doesn't re-probe. Full probe specs: `./discover-procedure.md` §Connection Probes.
+2. Probe connection availability. ToolSearch runs FIRST (MCP tools may be in the deferred tool set). Run three probes - A (Figma, variant-agnostic with prefix tiebreaker), B (Refero, ToolSearch-only), C (Pinterest, ToolSearch-only). After all probes, write `<connections>` to STATE.md so the builder doesn't re-probe. Full probe specs: `./discover-procedure.md` §Connection Probes.
 3. Update `last_checkpoint`. Write STATE.md.
 
 ---
@@ -30,13 +30,13 @@ When `--auto` is passed to the builder: if `tailwind.config.{js,cjs,mjs,ts}` exi
 
 ---
 
-## Step 1 — Spawn design-context-builder
+## Step 1 - Spawn design-context-builder
 
 Spawn `design-context-builder` -> `.design/DESIGN-CONTEXT.md`. The agent auto-detects via grep/glob first and interviews only for areas where auto-detect returned no confident answer. Baseline audit directory chain: `src/` -> `app/` -> `pages/` -> `lib/` -> flag "layout unknown". Common gray areas to probe (Area 7): font-change risk, token-layer introduction risk, component rebuild-vs-restyle. Wait for `## CONTEXT COMPLETE`, then update STATE.md `task_progress = 0.5`. Full prompt: `./discover-procedure.md` §Step 1.
 
 ---
 
-## Step 1.75 — Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
+## Step 1.75 - Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
 
 Spawn the cheap Haiku gate `design-context-checker-gate` before the full checker. It applies the single-file heuristic (is `DESIGN-CONTEXT.md` in `git diff --name-only HEAD~1..HEAD`?) and emits JSON + `## GATE COMPLETE`. On `spawn: false`: append `lazy_skipped: true` telemetry row, skip Step 2, set STATE.md `<position>` as if checker passed. On `spawn: true`: proceed to Step 2. On first-run discover the gate always returns `spawn: true` (builder just wrote the file); the gate meaningfully short-circuits only on re-runs where the builder made no changes. Full prompt: `./discover-procedure.md` §Step 1.75.
 
@@ -44,13 +44,13 @@ Spawn the cheap Haiku gate `design-context-checker-gate` before the full checker
 
 ---
 
-## Step 2 — Spawn design-context-checker
+## Step 2 - Spawn design-context-checker
 
 Spawn `design-context-checker` with `<required_reading>` on STATE.md + DESIGN-CONTEXT.md. The agent validates DESIGN-CONTEXT.md across 6 dimensions and returns APPROVED or BLOCKED with per-dimension verdicts. Wait for `## CONTEXT CHECK COMPLETE`. Full prompt: `./discover-procedure.md` §Step 2.
 
 ---
 
-## Step 3 — Handle checker verdict
+## Step 3 - Handle checker verdict
 
 - **APPROVED** -> proceed to state update.
 - **BLOCKED** -> present blocked dimensions to user, offer fix-and-retry loop (re-spawn builder with specific fix instructions). Do not proceed to planning.

package/skills/discover/discover-procedure.md

@@ -7,8 +7,8 @@ tags: [discover, procedure, extracted, pipeline-stage, connection-probe, design-
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/discover/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
-The skill's load-bearing workflow stays in `../skills/discover/SKILL.md`; this file holds the
+Source: extracted from `skills/discover/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/discover/SKILL.md`; this file holds the
 detail the agent reaches for when executing a specific step (state integration, three
 connection probes, design-context-builder + design-context-checker agent prompts, lazy gate
 prompt, auto-mode CSS detection).
@@ -23,17 +23,17 @@ Detailed procedure for the get-design-done `discover` Stage 1.5 orchestrator. Co
 ## State Integration
 
 1. Read `.design/STATE.md`.
-   - If missing: create minimal skeleton from `reference/STATE-TEMPLATE.md` with stage=discover, status=in_progress, task_progress=0/1, and log warning: "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
-   - If present and stage==discover and status==in_progress: RESUME — continue existing interview; do not reset.
-   - Otherwise: normal transition — set frontmatter stage=discover, <position> stage=discover, status=in_progress, task_progress=0/1.
-2. **Probe connection availability** — ToolSearch runs FIRST because MCP tools may be in the deferred tool set. This is the canonical probe pattern (spec lives in `connections/connections.md`; copied inline because SKILL.md has no include mechanism — if the probe pattern changes, update all stages that copied it). See §Connection Probes below.
+   - If missing: create minimal skeleton from `reference/STATE-TEMPLATE.md` with stage=discover, status=in_progress, task_progress=0/1, and log warning: "STATE.md not found - created fresh. If this is a resumed session, run /get-design-done:scan first."
+   - If present and stage==discover and status==in_progress: RESUME - continue existing interview; do not reset.
+   - Otherwise: normal transition - set frontmatter stage=discover, <position> stage=discover, status=in_progress, task_progress=0/1.
+2. **Probe connection availability** - ToolSearch runs FIRST because MCP tools may be in the deferred tool set. This is the canonical probe pattern (spec lives in `connections/connections.md`; copied inline because SKILL.md has no include mechanism - if the probe pattern changes, update all stages that copied it). See §Connection Probes below.
 3. Update last_checkpoint. Write STATE.md.
 
 ---
 
 ## Connection Probes
 
-### A — Figma probe (variant-agnostic)
+### A - Figma probe (variant-agnostic)
 
 ```
 A1. ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
@@ -50,7 +50,7 @@ A4. Call {prefix}get_metadata:
       Error   -> figma: unavailable
 ```
 
-### B — Refero probe (ToolSearch presence is sufficient — no tool call needed)
+### B - Refero probe (ToolSearch presence is sufficient - no tool call needed)
 
 ```
 B1. ToolSearch({ query: "refero", max_results: 5 })
@@ -58,7 +58,7 @@ B2. Empty result  -> refero: not_configured
     Non-empty     -> refero: available
 ```
 
-### C — Pinterest probe (ToolSearch-only, same pattern as Refero)
+### C - Pinterest probe (ToolSearch-only, same pattern as Refero)
 
 ```
 C1. ToolSearch({ query: "mcp-pinterest", max_results: 5 })
@@ -66,9 +66,9 @@ C2. Empty result  -> pinterest: not_configured
     Non-empty     -> pinterest: available
 ```
 
-No live `pinterest_search` call at probe time — ToolSearch presence is sufficient. The synthesizer makes the actual search calls.
+No live `pinterest_search` call at probe time - ToolSearch presence is sufficient. The synthesizer makes the actual search calls.
 
-### D — Lazyweb probe (ToolSearch-only — free, discover Tier 1 per D-01)
+### D - Lazyweb probe (ToolSearch-only - free, discover Tier 1 per D-01)
 
 ```
 D1. ToolSearch({ query: "lazyweb", max_results: 5 })
@@ -76,7 +76,7 @@ D2. Empty result  -> lazyweb: not_configured
     Non-empty     -> lazyweb: available
 ```
 
-### E — Mobbin probe (ToolSearch-only — paid, discover Tier 2 per D-01)
+### E - Mobbin probe (ToolSearch-only - paid, discover Tier 2 per D-01)
 
 ```
 E1. ToolSearch({ query: "mobbin", max_results: 5 })
@@ -102,7 +102,7 @@ Auto Mode CSS detection (when `auto_mode: true` is passed to the builder):
 
 ---
 
-## Step 1 — Spawn design-context-builder
+## Step 1 - Spawn design-context-builder
 
 ```
 Task("design-context-builder", """
@@ -140,7 +140,7 @@ Wait for `## CONTEXT COMPLETE`. Update STATE.md task_progress = 0.5.
 
 ---
 
-## Step 1.75 — Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
+## Step 1.75 - Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
 
 Spawn the cheap Haiku gate before the full context-checker:
 
@@ -152,8 +152,8 @@ Spawn the cheap Haiku gate before the full context-checker:
     You are the design-context-checker-gate.
 
     Context:
-      diff_files: <git diff --name-only HEAD~1..HEAD>
-      diff_body: (not needed — single-file heuristic)
+      diff_files: <git diff `--name-only` HEAD~1..HEAD>
+      diff_body: (not needed - single-file heuristic)
       baseline_sha: <HEAD~1>
 
     Apply the heuristic (DESIGN-CONTEXT.md in diff_files?). Emit JSON + `## GATE COMPLETE`.
@@ -170,7 +170,7 @@ Wait for `## GATE COMPLETE`. Parse JSON:
 
 ---
 
-## Step 2 — Spawn design-context-checker
+## Step 2 - Spawn design-context-checker
 
 ```
 Task("design-context-checker", """
@@ -190,7 +190,7 @@ Wait for `## CONTEXT CHECK COMPLETE`.
 
 ---
 
-## Step 3 — Handle checker verdict
+## Step 3 - Handle checker verdict
 
 If APPROVED: proceed to state update.
 If BLOCKED: present dimensions that BLOCKED to user, offer fix-and-retry loop (re-spawn builder with specific fix instructions). Do not proceed to planning.

package/skills/discuss/SKILL.md

@@ -9,7 +9,7 @@ tools: Read, Write, Task
 
 **Role:** You are the `/gdd:discuss` command. You spawn the `design-discussant` agent with the right mode and context.
 
-## Step 1 — Read state
+## Step 1 - Read state
 
 Read `.design/STATE.md`. Note:
 - Current `cycle:` frontmatter value
@@ -17,7 +17,7 @@ Read `.design/STATE.md`. Note:
 
 If `.design/STATE.md` does not exist, tell the user to run `/gdd:brief` first and stop.
 
-## Step 2 — Parse arguments
+## Step 2 - Parse arguments
 
 Inspect `$ARGUMENTS`:
 - Free-text before flags → `<topic>`
@@ -25,7 +25,7 @@ Inspect `$ARGUMENTS`:
 - `--spec` → Socratic ambiguity scoring mode
 - `--cycle <name>` → scope decisions to that cycle
 
-## Step 3 — Spawn design-discussant
+## Step 3 - Spawn design-discussant
 
 ```
 Task("design-discussant", """
@@ -47,15 +47,15 @@ Emit `## DISCUSS COMPLETE` when done.
 
 Use only the modes the user actually passed. Missing flags → `<mode>normal</mode>`.
 
-## Step 4 — Inline glossary maintenance (CONTEXT.md)
+## Step 4 - Inline glossary maintenance (CONTEXT.md)
 
 When a fuzzy phrase is resolved into a sharper term, or a new domain concept is named
 during the interview: write to `./CONTEXT.md` IMMEDIATELY (do NOT batch). Use the schema
-in `./../../reference/context-md-format.md` — H2 heading per term, body paragraph,
+in `./../../reference/context-md-format.md` - H2 heading per term, body paragraph,
 optional `**Aliases:**` line for term-merging. Multi-context repos use `CONTEXT-MAP.md`
 plus per-area `<area>/CONTEXT.md`. CONTEXT.md is lazy-created on the first term write.
 
-## Step 5 — Session wrap: ADR-offer scan
+## Step 5 - Session wrap: ADR-offer scan
 
 For each decision recorded this session, check ALL three criteria from
 `./../../reference/adr-format.md`: (a) **hard-to-reverse**, (b) **surprising-without-context**,
@@ -63,7 +63,7 @@ For each decision recorded this session, check ALL three criteria from
 ANY criterion fails, the decision stays in STATE.md `<decisions>`. Routine choices are
 NEVER auto-promoted.
 
-## Step 6 — Report
+## Step 6 - Report
 
 Wait for `## DISCUSS COMPLETE`. Re-read STATE.md. Count new D-XX entries since Step 1. Print:
 
@@ -77,20 +77,20 @@ Cycle: <name or "default">
 
 ## Constraints
 
-- Do not run the interview yourself — always spawn the agent.
+- Do not run the interview yourself - always spawn the agent.
 - Do not touch files outside `.design/`.
 
-## Rationalizations — Thought to Reality
+## Rationalizations - Thought to Reality
 
 The shortcuts an agent takes during a discuss session, and what each one costs the decision record:
 
 | Thought | Reality |
 |---------|---------|
 | "I'll ask all eight questions at once to save time." | Batched questions overwhelm the user; one-at-a-time keeps each decision clean and prevents coupled answers. |
-| "I can run the interview inline instead of spawning the discussant." | The skill's contract is to always spawn the agent — running it yourself skips the discussant's mode handling and D-XX numbering. |
+| "I can run the interview inline instead of spawning the discussant." | The skill's contract is to always spawn the agent - running it yourself skips the discussant's mode handling and D-XX numbering. |
 | "This answer is good enough, I'll record it as a decision without follow-up." | A vague answer ("modern", "clean") recorded as a D-XX locks in an undecided premise; reject and re-ask once. |
 | "I'll batch all the new D-XX entries into STATE.md at the end." | Decisions written atomically per answer survive an interrupted session; batching loses everything if the session drops. |
-| "The glossary term can wait until I write the summary." | CONTEXT.md is written immediately per term — a deferred glossary entry is a naming inconsistency the next cycle inherits. |
-| "Every decision this session is worth an ADR." | ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely load-bearing ones. |
+| "The glossary term can wait until I write the summary." | CONTEXT.md is written immediately per term - a deferred glossary entry is a naming inconsistency the next cycle inherits. |
+| "Every decision this session is worth an ADR." | ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely essential ones. |
 
 ## DISCUSS COMMAND COMPLETE

package/skills/do/SKILL.md

@@ -40,6 +40,6 @@ Takes a free-form description, maps it to a `/gdd:*` command, confirms with the
 ## Do Not
 
 - Do not execute the target command without confirmation.
-- Do not invent new commands — if no intent matches, say so and list the closest options.
+- Do not invent new commands - if no intent matches, say so and list the closest options.
 
 ## DO COMPLETE