@hegemonart/get-design-done 1.42.0 → 1.44.0

package/skills/explore/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: gdd-explore
-description: "Stage 2 of 5 — unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after /gdd:brief to map the existing system and lock decisions before planning."
+description: "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after /gdd:brief to map the existing system and lock decisions before planning."
 argument-hint: "[--skip-interview] [--skip-scan]"
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision
 ---
 
-# Get Design Done — Explore
+# Get Design Done - Explore
 
 **Role:** You are the Explore stage. Stage 2 of 5 in the get-design-done pipeline.
 
@@ -17,33 +17,33 @@ Full procedure detail: `./explore-procedure.md`.
 
 ## Stage entry
 
-All STATE.md persistence goes through `gdd-state` MCP tools — no direct edits. Plain design docs (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) use `Write`.
+All STATE.md persistence goes through `gdd-state` MCP tools - no direct edits. Plain design docs (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) use `Write`.
 
 1. `mcp__gdd_state__transition_stage` with `to: "explore"`. On gate failure: print blockers from `error.context.blockers` verbatim, do not advance.
 2. `mcp__gdd_state__get` (no args) -> snapshot `state` for downstream steps.
 
 ---
 
-## Step 1 — Connection probe
+## Step 1 - Connection probe
 
 Probe six connections, then batch-write results via ONE `mcp__gdd_state__probe_connections` call (unspecified connections keep their existing value):
 
-- **A — Figma** (variant-agnostic): ToolSearch + regex parse of `get_metadata` / `use_figma` prefixes -> tiebreaker selection (`both-sets > reads-only`, `figma > others`, `non-figma-desktop`, alphabetical) -> live `{prefix}get_metadata` call -> `available` / `unavailable` / `not_configured` (with `prefix=` + `writes=`).
-- **B — Refero**: ToolSearch presence sufficient.
-- **C — 21st.dev**: ToolSearch `mcp__21st` presence.
-- **D — Magic Patterns**: ToolSearch `mcp__magic_patterns` presence.
-- **E — paper.design**: ToolSearch `mcp__paper` + live `get_selection` call.
-- **F — pencil.dev**: `find . -name "*.pen"` file-presence.
+- **A - Figma** (variant-agnostic): ToolSearch + regex parse of `get_metadata` / `use_figma` prefixes -> tiebreaker selection (`both-sets > reads-only`, `figma > others`, `non-figma-desktop`, alphabetical) -> live `{prefix}get_metadata` call -> `available` / `unavailable` / `not_configured` (with `prefix=` + `writes=`).
+- **B - Refero**: ToolSearch presence sufficient.
+- **C - 21st.dev**: ToolSearch `mcp__21st` presence.
+- **D - Magic Patterns**: ToolSearch `mcp__magic_patterns` presence.
+- **E - paper.design**: ToolSearch `mcp__paper` + live `get_selection` call.
+- **F - pencil.dev**: `find . -name "*.pen"` file-presence.
 
 Full probe specs + commit-results JSON shape: `./explore-procedure.md` §Step 1.
 
-## Step 1.5 — 21st.dev Prior-Art Check (when `21st-dev: available`)
+## Step 1.5 - 21st.dev Prior-Art Check (when `21st-dev: available`)
 
 For each greenfield component in scope: `21st_magic_component_search(component_name, limit: 3)`. Fit >= 80% -> add `<prior-art>` block to DESIGN.md recommending adoption; fit < 80% -> note as reference, build custom. If `svgl_get_brand_logo` available and brand assets are in scope, call per logo and save SVGs to `.design/assets/`. Skip entirely if no greenfield components in scope. Detail: `./explore-procedure.md` §Step 1.5.
 
 ---
 
-## Step 2 — Inventory scan (unless `--skip-scan`)
+## Step 2 - Inventory scan (unless `--skip-scan`)
 
 **Map pre-check**: if `.design/map/` exists with all 5 files (`tokens.md`, `components.md`, `visual-hierarchy.md`, `a11y.md`, `motion.md`) fresher than `src/`, consume them and skip the grep pass. Otherwise grep and, after Step 4, suggest `/gdd:map` for the next cycle.
 
@@ -51,9 +51,9 @@ For each greenfield component in scope: `21st_magic_component_search(component_n
 
 Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): component detection (Glob `**/*.{tsx,jsx,vue,svelte}`), color extraction (hex / rgb / hsl / Tailwind arbitrary), typography scan (font-family / Tailwind `font-*` / `text-*`), motion scan (`transition` / `animate-` / `@keyframes` / `framer-motion`), token detection (tailwind.config / CSS custom properties / token JSON), layout detection (ordered fallback `src/` -> `app/` -> `pages/` -> `lib/` -> unknown). Write `.design/DESIGN.md` + `.design/DESIGN-DEBT.md`. Then `mcp__gdd_state__update_progress` for scan progress. Detail: `./explore-procedure.md` §Step 2.
 
-**Step 2.x — i18n readiness probe (informational, per D-04)**: check `package.json` deps against `{react-intl, next-intl, i18next, vue-i18n, formatjs, lingui}` -> `framework-managed`; else grep `Intl.(DateTimeFormat|NumberFormat|...)` in `src/` -> `partial`; else `none`. Emit single line `Localization readiness: <state>` in the report. NO gate, NO blocking — surface signal only (D-07). Detail: `./explore-procedure.md` §Step 2.x.
+**Step 2.x - i18n readiness probe (informational, per D-04)**: check `package.json` deps against `{react-intl, next-intl, i18next, vue-i18n, formatjs, lingui}` -> `framework-managed`; else grep `Intl.(DateTimeFormat|NumberFormat|...)` in `src/` -> `partial`; else `none`. Emit single line `Localization readiness: <state>` in the report. NO gate, NO blocking - surface signal only (D-07). Detail: `./explore-procedure.md` §Step 2.x.
 
-## Step 2.5 — Detect prior sketches and project-local conventions
+## Step 2.5 - Detect prior sketches and project-local conventions
 
 - **Sketches**: list `.design/sketches/*` slugs, group by `WINNER.md` present (completed) vs absent (pending). Record via `mcp__gdd_state__set_status: "explore_sketches_present"`. Include in DESIGN.md "Prior Explorations" section.
 - **Project-local skills**: read `./.claude/skills/design-*-conventions.md` -> include in DESIGN-CONTEXT.md `<project_conventions>` (these override defaults).
@@ -61,9 +61,9 @@ Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): c
 
 ---
 
-## Step 3 — Design interview (unless `--skip-interview`)
+## Step 3 - Design interview (unless `--skip-interview`)
 
-**Run inline — NEVER spawn `design-discussant` as a subagent.** `AskUserQuestion` only renders the native picker from the top-level skill context; spawning degrades to plain markdown (broken in Claude Desktop).
+**Run inline - NEVER spawn `design-discussant` as a subagent.** `AskUserQuestion` only renders the native picker from the top-level skill context; spawning degrades to plain markdown (broken in Claude Desktop).
 
 - **3.a Pre-load context**: state.decisions snapshot -> BRIEF.md -> DESIGN.md -> DESIGN-CONTEXT.md `<gray_areas>` -> project conventions. If `figma: available`, call `{prefix}get_variable_defs` and draft tentative D-XX entries.
 - **3.b Identify question set**: skip areas already covered by D-XX or project convention. Default coverage: cycle goal, audience, brand direction (if no tokens), color/typography/spacing primitives (if undetected), motion preferences, gray areas from DESIGN-CONTEXT.md.
@@ -75,10 +75,10 @@ Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
 
 ---
 
-## Step 4 — Close out explore
+## Step 4 - Close out explore
 
 - If the synthesizer / mapper batch ran in Step 2: `mcp__gdd_state__update_progress` with `task_progress: "<done>/<total>"`, `status: "explore_mappers_done"`.
-- `mcp__gdd_state__checkpoint` — bumps `last_checkpoint`.
+- `mcp__gdd_state__checkpoint` - bumps `last_checkpoint`.
 - Stage advance to `plan` happens at the next stage's entry (plan owns its own `transition_stage`); do not edit frontmatter directly.
 
 ## After Writing
@@ -89,16 +89,16 @@ Print: "=== Explore complete ===\nSaved: .design/DESIGN.md, .design/DESIGN-DEBT.
 Do NOT transition to plan (or invoke `/gdd:plan`) until BOTH `.design/DESIGN.md` AND `.design/DESIGN-CONTEXT.md` are committed AND the user has approved them. If this project uses a custom `.design` location, read the artifact paths from `.design/STATE.md` rather than assuming the default.
 </HARD-GATE>
 
-## Rationalizations — Thought to Reality
+## Rationalizations - Thought to Reality
 
 The shortcut excuses an agent reaches for during explore, and the drift each one introduces:
 
 | Thought | Reality |
 |---------|---------|
-| "I already know this codebase, I can skip the inventory scan." | An unscanned codebase hides the tokens/components you'll duplicate — the grep pass exists to stop you reinventing what's there. |
+| "I already know this codebase, I can skip the inventory scan." | An unscanned codebase hides the tokens/components you'll duplicate - the grep pass exists to stop you reinventing what's there. |
 | "The six connection probes are noise, I'll assume Figma is off." | A skipped probe means a wrong connection assumption silently breaks the design stage's tool dispatch. |
 | "`--skip-interview` is fine, the brief covered it." | The interview locks the gray areas the brief left fuzzy; skipping it ships undecided D-XX into planning. |
-| "I'll batch all the interview questions to save round-trips." | Batched questions overwhelm the user and smuggle in coupled assumptions — one-at-a-time keeps each decision clean. |
+| "I'll batch all the interview questions to save round-trips." | Batched questions overwhelm the user and smuggle in coupled assumptions - one-at-a-time keeps each decision clean. |
 | "DESIGN-DEBT.md is optional, the scan was clean enough." | Unrecorded debt resurfaces as an unexplained constraint three stages later with no provenance. |
 | "Prior sketches and project conventions don't apply this cycle." | Ignored conventions get overridden by defaults, producing inconsistency the audit will flag against the rest of the system. |
 

package/skills/explore/explore-procedure.md

@@ -7,8 +7,8 @@ tags: [explore, procedure, extracted, pipeline-stage, connection-probe, design-i
 last_updated: 2026-05-18
 ---
 
-Source: extracted from `skills/explore/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
-The skill's load-bearing workflow stays in `../skills/explore/SKILL.md`; this file holds the
+Source: extracted from `skills/explore/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/explore/SKILL.md`; this file holds the
 detail the agent reaches for when executing a specific step (six connection probes, 21st.dev
 prior-art check, inventory scan grep, design interview protocol, i18n probe, decision
 recording).
@@ -17,26 +17,26 @@ recording).
 
 Detailed procedure for the get-design-done `explore` Stage 2 orchestrator. Companion to
 `../skills/explore/SKILL.md`. Read this file when executing a specific step; the SKILL.md
-keeps the load-bearing workflow + decision tree, this file holds the deep methodology.
+keeps the essential workflow + decision tree, this file holds the deep methodology.
 
 ---
 
 ## Stage entry
 
-All STATE.md persistence in this skill goes through `gdd-state` MCP tools — no direct edits. The skill writes to `.design/STATE.md` (connections, decisions, progress, checkpoint) via those tools, and to plain design docs (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) via `Write`.
+All STATE.md persistence in this skill goes through `gdd-state` MCP tools - no direct edits. The skill writes to `.design/STATE.md` (connections, decisions, progress, checkpoint) via those tools, and to plain design docs (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) via `Write`.
 
 1. Call `mcp__gdd_state__transition_stage` with `to: "explore"`.
    - On success: proceed to probes.
    - On gate failure: emit blockers to the user (do not advance). Each blocker is a line in the `error.context.blockers` array; print them verbatim.
-2. Call `mcp__gdd_state__get` with no arguments — snapshot the parsed state into a local `state` variable for downstream steps.
+2. Call `mcp__gdd_state__get` with no arguments - snapshot the parsed state into a local `state` variable for downstream steps.
 
 ---
 
-## Step 1 — Connection probe
+## Step 1 - Connection probe
 
-Probe connection availability (the batched write lands at the end of this step — see "Commit probe results" below):
+Probe connection availability (the batched write lands at the end of this step - see "Commit probe results" below):
 
-**A — Figma probe (variant-agnostic):**
+**A - Figma probe (variant-agnostic):**
 ```
 ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
 Parse tool names matching /^mcp__([^_]*figma[^_]*)__(get_metadata|use_figma)$/i
@@ -52,35 +52,35 @@ Then call {prefix}get_metadata:
   error   -> figma: unavailable
 ```
 
-**B — Refero probe:**
+**B - Refero probe:**
 ```
 ToolSearch({ query: "refero", max_results: 5 })
 Empty -> refero: not_configured
 Non-empty -> refero: available
 ```
 
-**C — 21st.dev probe:**
+**C - 21st.dev probe:**
 ```
 ToolSearch({ query: "mcp__21st", max_results: 5 })
 Empty -> 21st-dev: not_configured
 Non-empty -> 21st-dev: available
 ```
 
-**D — Magic Patterns probe:**
+**D - Magic Patterns probe:**
 ```
 ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
 Empty -> magic-patterns: not_configured
 Non-empty -> magic-patterns: available
 ```
 
-**E — paper.design probe:**
+**E - paper.design probe:**
 ```
 ToolSearch({ query: "mcp__paper", max_results: 5 })
 Empty -> paper-design: not_configured
 Non-empty -> call mcp__paper-design__get_selection; success -> available; error -> unavailable
 ```
 
-**F — pencil.dev probe (file-based):**
+**F - pencil.dev probe (file-based):**
 ```bash
 find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null | head -1
 Empty -> pencil-dev: not_configured
@@ -91,7 +91,7 @@ Found -> pencil-dev: available
 
 After all probes complete, commit results in a single call:
 
-`mcp__gdd_state__probe_connections` with `probe_results` = an array of `{ name, status }` entries — one per probed connection. Example:
+`mcp__gdd_state__probe_connections` with `probe_results` = an array of `{ name, status }` entries - one per probed connection. Example:
 
 ```json
 {
@@ -103,9 +103,9 @@ After all probes complete, commit results in a single call:
 }
 ```
 
-Unspecified connections keep their existing value. Do NOT issue multiple `probe_connections` calls — the tool is designed for a single batch write per stage.
+Unspecified connections keep their existing value. Do NOT issue multiple `probe_connections` calls - the tool is designed for a single batch write per stage.
 
-## Step 1.5 — 21st.dev Prior-Art Check (when 21st-dev: available)
+## Step 1.5 - 21st.dev Prior-Art Check (when 21st-dev: available)
 
 If `state.connections.21st-dev === "not_configured"` (from the snapshot captured at stage entry): skip this step entirely.
 
@@ -131,7 +131,7 @@ If no greenfield components in scope: skip this step.
 
 ---
 
-## Step 2 — Inventory scan (unless `--skip-scan`)
+## Step 2 - Inventory scan (unless `--skip-scan`)
 
 **Map pre-check:** If `.design/map/` exists and all 5 files (`tokens.md`, `components.md`, `visual-hierarchy.md`, `a11y.md`, `motion.md`) are present AND fresher than `src/` (mtime), consume them as the inventory source and skip the grep pass. Otherwise proceed with grep below and, after Step 4, suggest running `/gdd:map` for richer parallel-scanned data on the next cycle.
 
@@ -143,22 +143,22 @@ If no greenfield components in scope: skip this step.
 
 Run the canonical scan grep/glob inventory (preserves PLAT-01/02 POSIX ERE patterns from Phase 1):
 
-- **Component detection** — `Glob` for `**/*.{tsx,jsx,vue,svelte}`; count exports, identify shared UI primitives.
-- **Color extraction** — `Grep` for hex (`#[0-9a-fA-F]{3,8}`), `rgb(`, `hsl(`, Tailwind arbitrary color classes; dedupe.
-- **Typography scan** — Grep font-family declarations, Tailwind `font-*`, `text-*` size classes; identify type scale.
-- **Motion scan** — Grep `transition`, `animate-`, `@keyframes`, `framer-motion` imports.
-- **Token detection** — Check for `tailwind.config.{js,cjs,mjs,ts}`, CSS custom properties (`--*`), design-token JSON.
-- **Layout detection** — Ordered fallback: `src/` -> `app/` -> `pages/` -> `lib/` -> unknown.
+- **Component detection** - `Glob` for `**/*.{tsx,jsx,vue,svelte}`; count exports, identify shared UI primitives.
+- **Color extraction** - `Grep` for hex (`#[0-9a-fA-F]{3,8}`), `rgb(`, `hsl(`, Tailwind arbitrary color classes; dedupe.
+- **Typography scan** - Grep font-family declarations, Tailwind `font-*`, `text-*` size classes; identify type scale.
+- **Motion scan** - Grep `transition`, `animate-`, `@keyframes`, `framer-motion` imports.
+- **Token detection** - Check for `tailwind.config.{js,cjs,mjs,ts}`, CSS custom properties (`--*`), design-token JSON.
+- **Layout detection** - Ordered fallback: `src/` -> `app/` -> `pages/` -> `lib/` -> unknown.
 
 Write findings to:
-- `.design/DESIGN.md` — current design system inventory + baseline score
-- `.design/DESIGN-DEBT.md` — prioritized debt roadmap
+- `.design/DESIGN.md` - current design system inventory + baseline score
+- `.design/DESIGN-DEBT.md` - prioritized debt roadmap
 
 Record scan progress: call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` to reflect the scan pass.
 
-### Step 2.x — i18n readiness probe (informational)
+### Step 2.x - i18n readiness probe (informational)
 
-Phase 28 D-04 probe — 3-state classification, **informational only**. NO gate, NO blocking, NO required-action. Output appears as a single line in the explore report.
+Phase 28 D-04 probe - 3-state classification, **informational only**. NO gate, NO blocking, NO required-action. Output appears as a single line in the explore report.
 
 Classification logic (matches `./reference/i18n.md` §Explore Integration Spec):
 
@@ -185,34 +185,34 @@ Output line in explore report (single informational line, per D-04):
 Localization readiness: framework-managed | partial | none
 ```
 
-(Exactly one of the three values, single line.) A consumer downstream (a planning agent, a roadmap reviewer, the user) can act on the signal if a gap is meaningful for the project, but the probe itself never forces a step — surface signal, do not bolt on a new pillar (D-07 orthogonal-lens discipline).
+(Exactly one of the three values, single line.) A consumer downstream (a planning agent, a roadmap reviewer, the user) can act on the signal if a gap is meaningful for the project, but the probe itself never forces a step - surface signal, do not bolt on a new pillar (D-07 orthogonal-lens discipline).
 
-## Step 2.5 — Detect prior sketches and project-local conventions
+## Step 2.5 - Detect prior sketches and project-local conventions
 
-**Sketches**: If `.design/sketches/` exists, list all sketch slugs — group by those with `WINNER.md` (completed wrap-ups) vs without (pending). Call `mcp__gdd_state__set_status` with a brief note (e.g., `status: "explore_sketches_present"`) so downstream stages see the history. Include the inventory in DESIGN.md under a "Prior Explorations" section.
+**Sketches**: If `.design/sketches/` exists, list all sketch slugs - group by those with `WINNER.md` (completed wrap-ups) vs without (pending). Call `mcp__gdd_state__set_status` with a brief note (e.g., `status: "explore_sketches_present"`) so downstream stages see the history. Include the inventory in DESIGN.md under a "Prior Explorations" section.
 
-**Project-local skills**: Read any `./.claude/skills/design-*-conventions.md` files if present. Include their content in DESIGN-CONTEXT.md under a `<project_conventions>` section — these are codified decisions from prior `/gdd:sketch-wrap-up` runs or manual edits, and they override defaults.
+**Project-local skills**: Read any `./.claude/skills/design-*-conventions.md` files if present. Include their content in DESIGN-CONTEXT.md under a `<project_conventions>` section - these are codified decisions from prior `/gdd:sketch-wrap-up` runs or manual edits, and they override defaults.
 
-**Global skills**: If `~/.claude/gdd/global-skills/` exists and contains `.md` files (other than README.md), read them and prepend their content to the `<project_conventions>` section under a `<global_conventions>` sub-block. Global skills represent cross-project personal conventions. They inform but do not override project-local decisions — when a project-local D-XX decision conflicts with a global skill, the project-local decision wins.
+**Global skills**: If `~/.claude/gdd/global-skills/` exists and contains `.md` files (other than README.md), read them and prepend their content to the `<project_conventions>` section under a `<global_conventions>` sub-block. Global skills represent cross-project personal conventions. They inform but do not override project-local decisions - when a project-local D-XX decision conflicts with a global skill, the project-local decision wins.
 
 ---
 
-## Step 3 — Design interview (unless `--skip-interview`)
+## Step 3 - Design interview (unless `--skip-interview`)
 
-**Run this inline — do NOT spawn `design-discussant` as a subagent.** Subagent UI tools (`AskUserQuestion`) only render the native picker when called from the top-level skill context; spawning a Task() degrades the interview to plain markdown in chat (broken in Claude Desktop).
+**Run this inline - do NOT spawn `design-discussant` as a subagent.** Subagent UI tools (`AskUserQuestion`) only render the native picker when called from the top-level skill context; spawning a Task() degrades the interview to plain markdown in chat (broken in Claude Desktop).
 
-### 3.a — Pre-load context
+### 3.a - Pre-load context
 
 Read in this order:
-1. `state.decisions` from the snapshot captured at stage entry — existing D-XX entries (do NOT re-ask anything covered). If the snapshot is stale, refresh by calling `mcp__gdd_state__get`.
-2. `.design/BRIEF.md` — problem statement, audience, constraints
-3. `.design/DESIGN.md` — auto-detected inventory from Step 2
-4. `.design/DESIGN-CONTEXT.md` if it exists — `<gray_areas>` block lists unresolved topics
-5. `./.claude/skills/design-*-conventions.md` if any — locked project conventions, treat as authoritative
+1. `state.decisions` from the snapshot captured at stage entry - existing D-XX entries (do NOT re-ask anything covered). If the snapshot is stale, refresh by calling `mcp__gdd_state__get`.
+2. `.design/BRIEF.md` - problem statement, audience, constraints
+3. `.design/DESIGN.md` - auto-detected inventory from Step 2
+4. `.design/DESIGN-CONTEXT.md` if it exists - `<gray_areas>` block lists unresolved topics
+5. `./.claude/skills/design-*-conventions.md` if any - locked project conventions, treat as authoritative
 
 If `state.connections` shows `figma: available`, read the resolved `prefix=` from the same entry and call `{prefix}get_variable_defs`, then draft tentative D-XX entries (mark `(tentative — confirm with user)`) before asking.
 
-### 3.b — Identify question set
+### 3.b - Identify question set
 
 Build the list of areas needing input. Skip any area already answered by an existing D-XX or covered by a project convention. Default coverage:
 
@@ -225,13 +225,13 @@ Build the list of areas needing input. Skip any area already answered by an exis
 - Motion preferences (only if no motion patterns detected)
 - Any `<gray_areas>` from DESIGN-CONTEXT.md
 
-### 3.c — Ask, one question at a time
+### 3.c - Ask, one question at a time
 
-For each area, call `AskUserQuestion` with a single focused question. Provide 4 concrete options plus "Other" / "Skip" where it helps. Do not batch questions into one call. Do not print the question as markdown — always go through the tool.
+For each area, call `AskUserQuestion` with a single focused question. Provide 4 concrete options plus "Other" / "Skip" where it helps. Do not batch questions into one call. Do not print the question as markdown - always go through the tool.
 
 Reject generic answers ("modern", "clean", "professional"). If the answer is vague, ask one follow-up before recording.
 
-### 3.d — Record after each answer
+### 3.d - Record after each answer
 
 After each confirmed answer:
 1. Call `mcp__gdd_state__add_decision` with the decision payload. The tool assigns the next `D-NN` id and persists atomically. Format the summary as:
@@ -243,18 +243,18 @@ After each confirmed answer:
    {"ts":"<iso>","question_id":"Q-NN","question_text":"<verbatim>","answer_summary":"<one sentence>","quality":"high|medium|low|skipped","evidence":"<why>","cycle":"<active-cycle-slug>"}
    ```
    Quality classification: `skipped` if user picked Skip / "doesn't matter"; `low` if < 10 words and not a specific value; `medium` if hedged ("maybe", "I think", "not sure"); `high` otherwise.
-3. `add_decision` commits incrementally — the decision survives a crash mid-interview without an explicit save step.
+3. `add_decision` commits incrementally - the decision survives a crash mid-interview without an explicit save step.
 
-### 3.e — Produce DESIGN-CONTEXT.md
+### 3.e - Produce DESIGN-CONTEXT.md
 
 When all questions are answered, write `.design/DESIGN-CONTEXT.md` summarizing the locked decisions, remaining gray areas, and any Figma-sourced tentatives that were confirmed or rejected. Set frontmatter `status: complete`.
 
 ---
 
-## Step 4 — Close out explore
+## Step 4 - Close out explore
 
 - If the synthesizer (or equivalent mapper batch) ran in Step 2, call `mcp__gdd_state__update_progress` with `task_progress: "<mappers-completed>/<mappers-total>"` and `status: "explore_mappers_done"` before advancing.
-- Call `mcp__gdd_state__checkpoint` — bumps `frontmatter.last_checkpoint` + appends a timestamp entry.
+- Call `mcp__gdd_state__checkpoint` - bumps `frontmatter.last_checkpoint` + appends a timestamp entry.
 - Stage advance to `plan` happens at the next stage's entry (the plan skill will transition from its own entry step); do not edit frontmatter directly from this skill.
 
 ## After Writing

package/skills/export/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-export
-description: "Packages a completed design cycle (.design artifacts + decisions + screenshots) into a stakeholder-shareable artifact — self-contained HTML, print-styled PDF (Paged.js-compatible), or a Notion page. Redacts secrets; --pseudonymize masks identity for external sharing; --pr posts the HTML preview as a PR comment. Use to hand a design-review packet to PMs/execs/brand who aren't in the repo."
+description: "Packages a completed design cycle (.design artifacts + decisions + screenshots) into a stakeholder-shareable artifact - self-contained HTML, print-styled PDF (Paged.js-compatible), or a Notion page. Redacts secrets; --pseudonymize masks identity for external sharing; --pr posts the HTML preview as a PR comment. Use to hand a design-review packet to PMs/execs/brand who aren't in the repo."
 argument-hint: "<cycle-id> --format html|pdf|notion [--pseudonymize] [--pr]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, ToolSearch, Task
@@ -8,23 +8,23 @@ tools: Read, Write, Bash, Glob, Grep, ToolSearch, Task
 
 # /gdd:export
 
-Turns a completed cycle's in-repo design output into a shareable artifact. Closes the gap that `.design/*.md` lives only in the repo — stakeholders not in code can't consume it. The format contract + source set live in `../../reference/export-formats.md`; the Notion write-path in `../../connections/notion.md`.
+Turns a completed cycle's in-repo design output into a shareable artifact. Closes the gap that `.design/*.md` lives only in the repo - stakeholders not in code can't consume it. The format contract + source set live in `../../reference/export-formats.md`; the Notion write-path in `../../connections/notion.md`.
 
 ## Steps
 
 1. **Resolve the cycle.** `<cycle-id>` (or the current cycle from `.design/STATE.md`). Read the **source set**: `EXPERIENCE.md` (Phase 19.5), `.design/DESIGN.md`, `.design/DESIGN-VERIFICATION.md`, `.design/DESIGN-AUDIT.md` (if present), the decision log, and any Preview/Chromatic screenshots.
 2. **Redact (always) + pseudonymize (opt-in).** Pass every section through `scripts/lib/redact.cjs` (secrets). If `--pseudonymize`, additionally apply `scripts/lib/pseudonymize.cjs` (git identity / paths / hostname) for external sharing. Honor `GDD_DISABLE_NOTION` for the notion format.
 3. **Assemble per `--format`:**
-   - **`html`** (default) — `node -e "require('scripts/lib/export/build-html.cjs').buildHtml({...})"` → a **self-contained** HTML (inline CSS, base64-embedded screenshots, no external refs). Write to `.design/export/<cycle>.html`.
-   - **`pdf`** — the same `buildHtml({ ..., print: true })` (Paged.js-compatible `@page` print CSS). Write `.design/export/<cycle>.print.html`; instruct the user to render it via Paged.js / headless-Chrome (GDD ships **no** PDF runtime — D-02).
-   - **`notion`** — probe the Notion MCP (`ToolSearch({query:"notion"})`); if `available`, create a page from the same source (nested toggles + image upload) per `connections/notion.md`; if `not_configured`/disabled → degrade to the `html` format + a note.
-4. **`--pr`** — hand the generated HTML preview to `agents/pr-commenter.md` (via `Task`) to post as a PR comment (degrade-to-noop if no PR / pr-commenter unavailable).
+   - **`html`** (default) - `node -e "require('scripts/lib/export/build-html.cjs').buildHtml({...})"` → a **self-contained** HTML (inline CSS, base64-embedded screenshots, no external refs). Write to `.design/export/<cycle>.html`.
+   - **`pdf`** - the same `buildHtml({ ..., print: true })` (Paged.js-compatible `@page` print CSS). Write `.design/export/<cycle>.print.html`; instruct the user to render it via Paged.js / headless-Chrome (GDD ships **no** PDF runtime - D-02).
+   - **`notion`** - probe the Notion MCP (`ToolSearch({query:"notion"})`); if `available`, create a page from the same source (nested toggles + image upload) per `connections/notion.md`; if `not_configured`/disabled → degrade to the `html` format + a note.
+4. **`--pr`** - hand the generated HTML preview to `agents/pr-commenter.md` (via `Task`) to post as a PR comment (degrade-to-noop if no PR / pr-commenter unavailable).
 5. **Print the artifact path** (and the Notion URL / PR comment status when applicable).
 
 ## Do Not
 
-- Do not add a PDF/markdown runtime dependency (`paged`/`puppeteer`/`pdfkit`/a markdown lib) — `build-html.cjs` is pure and the PDF is render-it-yourself print HTML (D-02).
-- Do not emit an un-redacted artifact — redact is mandatory; pseudonymize is the external-sharing opt-in.
-- Do not block on Notion/PR — both degrade to a noop / the html file.
+- Do not add a PDF/markdown runtime dependency (`paged`/`puppeteer`/`pdfkit`/a markdown lib) - `build-html.cjs` is pure and the PDF is render-it-yourself print HTML (D-02).
+- Do not emit an un-redacted artifact - redact is mandatory; pseudonymize is the external-sharing opt-in.
+- Do not block on Notion/PR - both degrade to a noop / the html file.
 
 ## EXPORT COMPLETE

package/skills/extract-learnings/SKILL.md

@@ -16,7 +16,7 @@ tools: Bash, Read, Write, Glob, Grep
 
 ## Protocol
 
-### Step 1 — Gather source artifacts
+### Step 1 - Gather source artifacts
 
 Collect content from available `.design/` files:
 
@@ -26,11 +26,11 @@ ls .design/*.md 2>/dev/null
 
 Read (if present): DESIGN-CONTEXT.md, DESIGN-VERIFICATION.md, DESIGN-DEBT.md, DESIGN-SUMMARY.md, CYCLES.md
 
-### Step 2 — Invoke gdd-learnings-extractor agent
+### Step 2 - Invoke gdd-learnings-extractor agent
 
 Delegate extraction to the `gdd-learnings-extractor` agent, passing it the list of available files. The agent extracts structured learning entries.
 
-### Step 3 — Write learnings artifact
+### Step 3 - Write learnings artifact
 
 The agent writes or appends to `.design/learnings/LEARNINGS.md`.
 
@@ -53,7 +53,7 @@ Layout of `.design/learnings/LEARNINGS.md`:
 ---
 ```
 
-### Step 4 — Reference file proposal (optional)
+### Step 4 - Reference file proposal (optional)
 
 After writing LEARNINGS.md, check each learning entry with `Proposed reference update: yes`.
 
@@ -78,7 +78,7 @@ If user types `y`: write the addition to the reference file.
 If user types `n`: mark the learning as "proposal declined" in LEARNINGS.md.
 If user types `edit`: open the proposed text for the user to modify, then write.
 
-### Step 5 — Summary
+### Step 5 - Summary
 
 ```
 ━━━ Learnings extracted ━━━

package/skills/fast/SKILL.md

@@ -27,7 +27,7 @@ The leanest possible execution path. No subagents, no STATE.md update, no DESIGN
 ## Steps
 
 1. Parse the task description from the argument.
-2. Use Grep/Glob to locate the target file(s). If ambiguous (>2 candidates), stop and ask the user which to edit — do not guess.
+2. Use Grep/Glob to locate the target file(s). If ambiguous (>2 candidates), stop and ask the user which to edit - do not guess.
 3. Read the target file(s).
 4. Apply the described change with Edit.
 5. Run a relevant sanity check (grep for the old value to confirm it's gone; grep for the new value to confirm it's in).
@@ -40,12 +40,12 @@ The leanest possible execution path. No subagents, no STATE.md update, no DESIGN
 - No `.design/` writes.
 - No STATE.md mutation.
 - No pipeline stage invocation.
-- Do not proceed if the change turns out to be non-trivial — bail out and recommend `/gdd:quick` or the full pipeline.
-- Do not skip the `capability_gap` emit on bail-out — Stage-0 telemetry depends on it (Phase 29 D-01).
+- Do not proceed if the change turns out to be non-trivial - bail out and recommend `/gdd:quick` or the full pipeline.
+- Do not skip the `capability_gap` emit on bail-out - Stage-0 telemetry depends on it (Phase 29 D-01).
 
 ## Emitting capability_gap on no-skill-match
 
-If step 2 cannot locate any candidate files for the task description (or all candidates are filtered out as off-topic), or if the change in step 4 turns out to be non-trivial in a way that has no obvious resolution without a dedicated skill/agent, emit ONE `capability_gap` event before returning control to the user. This feeds Phase 29 Stage-0 telemetry — the reflector pattern-detection pass (Plan 29-02) and aggregation (Plan 29-03) read these events from the chain file (`.design/gep/events.jsonl`) to surface recurring capability gaps in `/gdd:apply-reflections`.
+If step 2 cannot locate any candidate files for the task description (or all candidates are filtered out as off-topic), or if the change in step 4 turns out to be non-trivial in a way that has no obvious resolution without a dedicated skill/agent, emit ONE `capability_gap` event before returning control to the user. This feeds Phase 29 Stage-0 telemetry - the reflector pattern-detection pass (Plan 29-02) and aggregation (Plan 29-03) read these events from the chain file (`.design/gep/events.jsonl`) to surface recurring capability gaps in `/gdd:apply-reflections`.
 
 Synchronous emitter call (via Bash):
 
@@ -75,10 +75,10 @@ appendChainEvent({
 ```
 
 Notes:
-- `evidence_refs` is empty `[]` for fast (no trajectory in `/gdd:fast` — that path is too lean by design).
+- `evidence_refs` is empty `[]` for fast (no trajectory in `/gdd:fast` - that path is too lean by design).
 - `parent_event_id` is null (root event for the fast bail-out).
 - `suggested_kind` is `"skill"` because fast bail-outs are usually narrow primitives, not multi-step workflows. Plan 29-03's aggregator may upgrade to `"agent"` if a `context_hash` cluster shows multi-step usage.
-- The emitter MUST NOT block — `appendChainEvent` already swallows IO errors via its existing try/catch (see `scripts/lib/event-chain.cjs:97-105`).
+- The emitter MUST NOT block - `appendChainEvent` already swallows IO errors via its existing try/catch (see `scripts/lib/event-chain.cjs:97-105`).
 - The 7-field payload is preserved verbatim through `appendChainEvent`'s opaque-extras pattern; the chain row carries `type`, `timestamp`, `sessionId`, `payload` as opaque caller-supplied fields and is projected back to the events-schema envelope shape by readers (Plan 29-03 aggregator).
 
 Trigger conditions:
@@ -86,6 +86,6 @@ Trigger conditions:
 - **Trigger 2**: Step 2 returns more than 2 candidates AND the user bail-out in step 2 fires (stop and ask).
 - **Trigger 3**: Step 4 reveals the change is non-trivial in a way that has no obvious primitive resolution (the `## Do Not` "Do not proceed" line fires).
 
-MCP-probe failures (connection down, transport-layer errors) do NOT emit `capability_gap` — those are Phase 22 connection-status concerns (D-08).
+MCP-probe failures (connection down, transport-layer errors) do NOT emit `capability_gap` - those are Phase 22 connection-status concerns (D-08).
 
 ## FAST COMPLETE

package/skills/figma-extract/SKILL.md

@@ -5,7 +5,7 @@ description: Off-context Figma design-system extraction into a compact local dig
 
 # gdd-figma-extract
 
-Pull a whole Figma design system into a compact, queryable local digest — **without** the raw JSON ever entering Claude context. The heavy lifting runs in tested `.cjs` tools; the model reads only the digest outputs.
+Pull a whole Figma design system into a compact, queryable local digest - **without** the raw JSON ever entering Claude context. The heavy lifting runs in tested `.cjs` tools; the model reads only the digest outputs.
 
 ## Usage
 
@@ -22,21 +22,21 @@ Pull a whole Figma design system into a compact, queryable local digest — **wi
    ```
    node -e "process.exit(process.env.FIGMA_TOKEN||process.env.FIGMA_PERSONAL_ACCESS_TOKEN?0:1)"
    ```
-   If unset, tell the user to `export FIGMA_TOKEN=figd_…` (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment **only** — never ask the user to paste it into a file or the chat, and never echo it back.
+   If unset, tell the user to `export FIGMA_TOKEN=figd_…` (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment **only** - never ask the user to paste it into a file or the chat, and never echo it back.
 
-2. **Stage 1 — pull.** Pull the file's REST endpoints into the gitignored raw cache (D-09):
+2. **Stage 1 - pull.** Pull the file's REST endpoints into the gitignored raw cache (D-09):
    ```
    node scripts/lib/figma-extract/pull.cjs "<file-key-or-url>"
    ```
-   This caches to `.figma-extract-cache/raw/<file-key>/` and skips re-pulling when Figma's `version` is unchanged (D-11). Add `--force` to bypass the cache, `--out <dir>` to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout — the raw bodies stay on disk.
+   This caches to `.figma-extract-cache/raw/<file-key>/` and skips re-pulling when Figma's `version` is unchanged (D-11). Add `--force` to bypass the cache, `--out <dir>` to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout - the raw bodies stay on disk.
 
-3. **Stage 2 — plugin sync (OPTIONAL, Path C).** Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows `variables` skipped) and the user wants token coverage:
+3. **Stage 2 - plugin sync (OPTIONAL, Path C).** Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows `variables` skipped) and the user wants token coverage:
    ```
    node scripts/lib/figma-extract/receiver.cjs --out .figma-extract-cache/raw/<file-key>
    ```
-   This binds `127.0.0.1:5179` (D-06). Tell the user to run the dev-installed **"GDD Sync"** plugin in Figma and click **"Export to GDD"** — see `figma-plugin/README.md` for the one-time dev-install. The receiver writes `variables.json` into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
+   This binds `127.0.0.1:5179` (D-06). Tell the user to run the dev-installed **"GDD Sync"** plugin in Figma and click **"Export to GDD"** - see `figma-plugin/README.md` for the one-time dev-install. The receiver writes `variables.json` into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
 
-4. **Stage 3 — digest.** Transform the cache into the compact digest:
+4. **Stage 3 - digest.** Transform the cache into the compact digest:
    ```
    node scripts/lib/figma-extract/digest.cjs --raw .figma-extract-cache/raw/<file-key> --out .figma-extract-cache/digest
    ```
@@ -46,9 +46,9 @@ Pull a whole Figma design system into a compact, queryable local digest — **wi
 
 ## Required Reading
 
-- `.figma-extract-cache/digest/DESIGN.md` — the compact human/LLM-readable spec
-- `.figma-extract-cache/digest/tokens.json` — resolved design tokens (when structured token data is needed)
-- `.figma-extract-cache/digest/components.json` — components with variants/props/defaults (when structured component data is needed)
+- `.figma-extract-cache/digest/DESIGN.md` - the compact human/LLM-readable spec
+- `.figma-extract-cache/digest/tokens.json` - resolved design tokens (when structured token data is needed)
+- `.figma-extract-cache/digest/components.json` - components with variants/props/defaults (when structured component data is needed)
 
 ## Notes
 
@@ -59,6 +59,6 @@ Pull a whole Figma design system into a compact, queryable local digest — **wi
 ## Do Not
 
 - **Do NOT read or `cat` the `raw/*.json` cache** (e.g. `.figma-extract-cache/raw/<file-key>/file.json`). It is tool-internal and often 100+ MB; loading it into context defeats the off-context guarantee (D-12). Read only the digest outputs above.
-- **Do not persist, log, echo, or print `FIGMA_TOKEN`** (D-10). It belongs in the environment only — never write it to a file, a commit, or chat output.
+- **Do not persist, log, echo, or print `FIGMA_TOKEN`** (D-10). It belongs in the environment only - never write it to a file, a commit, or chat output.
 
 ## FIGMA-EXTRACT COMPLETE

package/skills/figma-write/SKILL.md

@@ -14,19 +14,19 @@ Dispatches the `design-figma-writer` agent to write design decisions back to the
 ```
 
 Modes:
-- `annotate` — add design decision comments to Figma layers
-- `tokenize` — bind hard-coded color/spacing/type values to Figma variables
-- `mappings` — write Code Connect component↔code file mappings
+- `annotate` - add design decision comments to Figma layers
+- `tokenize` - bind hard-coded color/spacing/type values to Figma variables
+- `mappings` - write Code Connect component↔code file mappings
 
 Flags:
-- `--dry-run` — emit the proposal without executing any Figma writes
-- `--confirm-shared` — authorize writes to shared team library components
+- `--dry-run` - emit the proposal without executing any Figma writes
+- `--confirm-shared` - authorize writes to shared team library components
 
 ## Prerequisites
 
 1. Remote Figma MCP registered (writes are remote-only). Preferred: `claude plugin install figma@claude-plugins-official`. Manual: `claude mcp add --transport http figma https://mcp.figma.com/mcp`.
 2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first)
-3. `.design/STATE.md` `<connections>` shows `figma: available (…, writes=true)`. If `writes=false` (desktop-only variant), writes are not supported — the agent will STOP with an instruction to install the remote MCP.
+3. `.design/STATE.md` `<connections>` shows `figma: available (…, writes=true)`. If `writes=false` (desktop-only variant), writes are not supported - the agent will STOP with an instruction to install the remote MCP.
 
 ## Required Reading
 

package/skills/graphify/SKILL.md

@@ -19,7 +19,7 @@ Thin command wrapper around the GSD graphify tools integration.
 ## Behavior
 
 1. Read `.design/STATE.md` to check `graphify` status in `<connections>`.
-2. Check `graphify.enabled` in `.design/config.json` via a direct file read (per D-09 — no `config-get` CLI subcommand):
+2. Check `graphify.enabled` in `.design/config.json` via a direct file read (per D-09 - no `config-get` CLI subcommand):
    ```
    node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
    ```
@@ -38,12 +38,12 @@ Thin command wrapper around the GSD graphify tools integration.
 
 ## Required Reading
 
-- `.design/STATE.md` — for graphify status in `<connections>`
-- `.design/config.json` — for `graphify.enabled` flag
+- `.design/STATE.md` - for graphify status in `<connections>`
+- `.design/config.json` - for `graphify.enabled` flag
 
 ## Notes
 
-- Graphify is optional. The native CLI ships in this repo at `bin/gdd-graph` (no external install — Node only).
+- Graphify is optional. The native CLI ships in this repo at `bin/gdd-graph` (no external install - Node only).
 - Graph is stored at `.design/graph/graph.json` (Ajv-validated against `scripts/lib/graph/schema.json`).
 - Graph covers source code (`src/`, `components/`). It does NOT index `.design/` artifacts by default.
 - Use `query` with node IDs from the graph schema: `component:<name>`, `token:color/<name>`, `decision:D-<nn>`, etc.