@hegemonart/get-design-done 1.59.3 → 1.59.5

package/scripts/skill-templates/explore/SKILL.md

@@ -0,0 +1,118 @@
+---
+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 {{command_prefix}}brief to map the existing system and lock decisions before planning. Activates for requests involving researching design direction, gathering references, or exploring visual options."
+argument-hint: "[--skip-interview] [--skip-scan] [--incremental] [--full]"
+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
+
+**Role:** You are the Explore stage. Stage 2 of 5 in the get-design-done pipeline.
+
+**Purpose:** Unified exploration merging the former `scan` (inventory grep) and `discover` (context interview) stages. Produces `.design/DESIGN.md`, `.design/DESIGN-DEBT.md`, and `.design/DESIGN-CONTEXT.md`.
+
+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`.
+
+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
+
+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.
+
+Full probe specs + commit-results JSON shape: `./explore-procedure.md` §Step 1.
+
+## 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`)
+
+**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 `{{command_prefix}}map` for the next cycle.
+
+**Parallelism decision**: read `.design/config.json` + `reference/parallelism-rules.md`. Record verdict via `mcp__gdd_state__set_status` (`"explore_parallel"` / `"explore_serial"`). Parallel -> multiple `Task()` in one response; serial -> sequential.
+
+**Incremental batching (Phase 53, default)**: `--incremental` (default; `--full` opts out) runs the change classifier first via the fingerprint store, groups the DesignContext graph into Louvain community batches, and dispatches mappers per the verdict (SKIP=0, PARTIAL=affected batches only, FULL=all). Engine: `scripts/lib/explore-parallel-runner` + `scripts/lib/mappers/incremental-discover.cjs`; dispatch concurrency comes from `concurrency-tuner.cjs`. Detail: `./explore-procedure.md` §Incremental Batching.
+
+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.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).
+- **Global skills**: `~/.claude/gdd/global-skills/*.md` (other than README) -> prepend to `<project_conventions>` under `<global_conventions>` sub-block. Project-local D-XX wins on conflict.
+
+## Step 2.6 - Graph review (gate then reviewer)
+
+Runs only when Step 2's mapper batch + synthesizer produced `.design/context-graph.json`. Skip the whole step if the file is absent (pre-Phase-52 project, or `--skip-scan`).
+
+1. **Gate first (cheap Haiku check).** Spawn `design-context-reviewer-gate` via `Task()` with the classifier signal from Step 2's incremental batching pass: `change_pct` (fingerprint classifier `pct`), `classifier_action` (`SKIP` / `PARTIAL_UPDATE` / `ARCHITECTURE_UPDATE` / `FULL_UPDATE`), and `graph_path: ".design/context-graph.json"`. Gate emits a single-line `{spawn, rationale}` JSON decision then `## GATE COMPLETE`.
+2. **If `spawn: false`**: record `mcp__gdd_state__set_status: "explore_graph_review_skipped"`, log the gate `rationale` (e.g., "project change 3% < 5% threshold"), set telemetry `lazy_skipped: true`. Done - proceed to Step 3.
+3. **If `spawn: true`**: spawn `design-context-reviewer` via `Task()` with `<required_reading>` pointing at `.design/STATE.md`, `.design/context-graph.json`, `reference/design-context-schema.md`, `reference/design-context-tag-vocab.md`. The reviewer runs `scripts/validate-design-context.cjs --json` as the deterministic floor (checks 1/2/3/5) then layers the semantic checks (4/6/7/8/9) and returns the 9-check verdict inline (`APPROVED` or `REJECT`).
+4. **Capture verdict (read-only contract).** The reviewer does NOT write `.design/DESIGN-CONTEXT-REVIEW.md` - it is `reads-only: true, writes: []`. WARN findings surface through `scripts/lib/health-mirror#getHealthChecks` as `status: 'warn'`; a hard-reject maps to `status: 'fail'`. Record the overall verdict via `mcp__gdd_state__set_status: "explore_graph_review_approved"` (or `"_rejected"`).
+5. **On REJECT**: record `mcp__gdd_state__add_blocker` with the reviewer's blocking-issues list verbatim. Do not advance to Step 3 until the synthesizer or the implicated mapper is re-run. On `APPROVED` (with or without WARNs): proceed.
+
+---
+
+## 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).
+
+- **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.
+- **3.c Ask one at a time**: `AskUserQuestion` with 4 concrete options + "Other" / "Skip". Reject generic answers ("modern", "clean") with one follow-up.
+- **3.d Record after each answer**: `mcp__gdd_state__add_decision` (atomic, auto-assigns D-NN); append a quality-classified JSON line to `.design/learnings/question-quality.jsonl`.
+- **3.e Produce DESIGN-CONTEXT.md**: summarize locked decisions, remaining gray areas, Figma tentatives. Frontmatter `status: complete`.
+
+Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
+
+---
+
+## 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"`.
+- If Step 2.6 ran the graph review: ensure the verdict status is recorded (`explore_graph_review_approved` / `_rejected` / `_skipped`); on `_rejected` do NOT checkpoint until re-run.
+- `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
+
+Print: "=== Explore complete ===\nSaved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md\nNext: @get-design-done plan".
+
+<HARD-GATE>
+Do NOT transition to plan (or invoke `{{command_prefix}}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
+
+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. |
+| "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. |
+| "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. |
+
+## EXPLORE COMPLETE

package/scripts/skill-templates/explore/explore-procedure.md

@@ -0,0 +1,267 @@
+---
+name: explore-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [explore, procedure, extracted, pipeline-stage, connection-probe, design-interview, i18n]
+last_updated: 2026-05-18
+---
+
+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).
+
+# Explore Procedure
+
+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 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`.
+
+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.
+
+---
+
+## Step 1 - Connection probe
+
+Probe connection availability (the batched write lands at the end of this step - see "Commit probe results" below):
+
+**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
+  into read-capable and write-capable prefix sets.
+Empty read set -> figma: not_configured
+One+ matches  -> pick prefix via tiebreaker:
+                (1) both-sets > reads-only,
+                (2) `figma` > others,
+                (3) non-`figma-desktop` > desktop,
+                (4) alphabetical.
+Then call {prefix}get_metadata:
+  success -> figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
+  error   -> figma: unavailable
+```
+
+**B - Refero probe:**
+```
+ToolSearch({ query: "refero", max_results: 5 })
+Empty -> refero: not_configured
+Non-empty -> refero: available
+```
+
+**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:**
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+Empty -> magic-patterns: not_configured
+Non-empty -> magic-patterns: available
+```
+
+**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):**
+```bash
+find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null | head -1
+Empty -> pencil-dev: not_configured
+Found -> pencil-dev: available
+```
+
+## Commit probe results
+
+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:
+
+```json
+{
+  "probe_results": [
+    { "name": "figma", "status": "available" },
+    { "name": "refero", "status": "not_configured" },
+    { "name": "preview", "status": "unavailable" }
+  ]
+}
+```
+
+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)
+
+If `state.connections.21st-dev === "not_configured"` (from the snapshot captured at stage entry): skip this step entirely.
+
+When the explore stage identifies any greenfield component in scope (component name from BRIEF.md or user request that does not yet have an implementation file):
+
+1. `21st_magic_component_search(component_name, limit: 3)`
+2. Evaluate top result:
+   - **fit >= 80%**: add `<prior-art>` block to DESIGN.md:
+     ```xml
+     <prior-art source="21st.dev" component="<name>" fit="<score>%" id="<component_id>">
+       Recommendation: adopt — do not build custom. Confirm with design-executor.
+     </prior-art>
+     ```
+   - **fit < 80%**: note top candidate in DESIGN.md as a reference, proceed with custom build:
+     ```xml
+     <prior-art source="21st.dev" component="<name>" fit="<score>%" id="<component_id>">
+       Low fit — noted for reference. Building custom component.
+     </prior-art>
+     ```
+3. If `svgl_get_brand_logo` is available and explore scope includes brand logo assets: call `svgl_get_brand_logo(brand_name)` for each required brand asset; add SVG results to `.design/assets/` and note in DESIGN.md.
+
+If no greenfield components in scope: skip this step.
+
+---
+
+## 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 `{{command_prefix}}map` for richer parallel-scanned data on the next cycle.
+
+**Parallelism decision (before any multi-agent spawn):**
+1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+2. Apply rules from `reference/parallelism-rules.md` (hard -> soft).
+3. Record the verdict via `mcp__gdd_state__set_status` with a short status label (e.g., `status: "explore_parallel"` or `"explore_serial"`) carrying the stage/verdict/reason/agents payload.
+4. If verdict is `parallel`, dispatch via multiple `Task()` calls in one response; if `serial`, spawn sequentially.
+
+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.
+
+Write findings to:
+- `.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)
+
+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):
+
+```txt
+1. Read package.json (dependencies + devDependencies).
+
+2. Check against library matrix:
+     react-intl, next-intl, i18next, vue-i18n, formatjs, lingui
+   >=1 library found in deps or devDeps -> state = "framework-managed"
+                                          -> STOP, emit line, exit probe.
+
+3. Else (no library):
+     grep -RE "Intl\.(DateTimeFormat|NumberFormat|PluralRules|RelativeTimeFormat|ListFormat|Collator|Segmenter)" src/
+   >=1 match -> state = "partial"
+              -> emit line, exit probe.
+
+4. Else: state = "none"
+         -> emit line, exit probe.
+```
+
+Output line in explore report (single informational line, per D-04):
+
+```txt
+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).
+
+## 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.
+
+**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 `{{command_prefix}}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.
+
+---
+
+## 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).
+
+### 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
+
+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
+
+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:
+
+- Cycle goal / outcome that matters most
+- Audience and primary use context
+- Brand direction (only if no tokens detected in DESIGN.md)
+- Color primitives (only if no palette detected)
+- Typography scale (only if no type system detected)
+- Spacing scale (only if no spacing tokens detected)
+- Motion preferences (only if no motion patterns detected)
+- Any `<gray_areas>` from DESIGN-CONTEXT.md
+
+### 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.
+
+Reject generic answers ("modern", "clean", "professional"). If the answer is vague, ask one follow-up before recording.
+
+### 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:
+   ```
+   [Category] Decision summary — short rationale
+   ```
+2. Append one JSON line to `.design/learnings/question-quality.jsonl` (create if absent):
+   ```json
+   {"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.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
+
+- 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.
+- 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
+
+```
+=== Explore complete ===
+Saved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md
+Next: @get-design-done plan
+=========================
+```

package/scripts/skill-templates/export/SKILL.md

@@ -0,0 +1,30 @@
+---
+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."
+argument-hint: "<cycle-id> --format html|pdf|notion [--pseudonymize] [--pr]"
+user-invocable: true
+tools: Read, Write, Bash, Glob, Grep, ToolSearch, Task
+---
+
+# {{command_prefix}}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`.
+
+## 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).
+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.
+
+## EXPORT COMPLETE

package/scripts/skill-templates/extract-learnings/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: gdd-extract-learnings
+description: "Extracts project-specific design patterns and decisions from .design/ artifacts and writes them to .design/learnings/. Optionally proposes updates to reference/ files for user review."
+tools: Bash, Read, Write, Glob, Grep
+---
+
+# {{command_prefix}}extract-learnings
+
+**Role:** Scan `.design/` artifacts for recurring patterns, successful decisions, and validated approaches. Write structured learnings to `.design/learnings/`. Optionally propose additions to tracked `reference/` files for the user to review and approve.
+
+## When to run
+
+- After `{{command_prefix}}complete-cycle` (auto-suggested by complete-cycle skill)
+- After a major verify/audit pass surfaces new patterns
+- Manually, to checkpoint what the project has learned
+
+## Protocol
+
+### Step 1 - Gather source artifacts
+
+Collect content from available `.design/` files:
+
+```bash
+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
+
+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
+
+The agent writes or appends to `.design/learnings/LEARNINGS.md`.
+
+Layout of `.design/learnings/LEARNINGS.md`:
+
+```markdown
+# Project Learnings
+
+## <Category> — <Date>
+
+### L-<NN>: <Title>
+
+**Source:** <which .design/ file and section>
+**Pattern type:** decision | anti-pattern | validated-approach | token-convention | component-convention
+**Confidence:** high | medium | low
+**Summary:** <1-2 sentences>
+**Evidence:** <quote or paraphrase from source>
+**Proposed reference update:** <yes — see proposal below | no>
+
+---
+```
+
+### Step 3b - Dual-emit atomic instinct units (Phase 51)
+
+Alongside the prose `LEARNINGS.md`, emit atomic instinct units for every learning the extractor tags as an `instinct-candidate`. A learning is an `instinct-candidate` when it states a single trigger plus a one-line response - the same shape the reflector emits. Broader narrative learnings stay prose-only.
+
+For each `instinct-candidate`, build a unit per `reference/instinct-format.md` (frontmatter: `id`, `trigger`, `confidence` from 0.3 to 0.9, `domain`, `scope`, `project_id`, `source`, `cycles_seen`, `first_seen`, `last_seen`, plus a short body). Set `source: extract-learnings`. Carry the learning's confidence (high / medium / low) into the numeric field (roughly 0.8 / 0.55 / 0.35), capped at 0.9.
+
+Write each unit through the store engine `scripts/lib/instinct-store.cjs` rather than by hand:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" add --scope project
+```
+
+If the engine exposes a module API only, drive `add(unit, { scope: 'project', baseDir })` from a short `node -e` script. The engine owns de-duplication and `cycles_seen` bookkeeping; do not pre-merge.
+
+The prose `LEARNINGS.md` is **retained read-only for one minor version** so existing readers keep working while tooling migrates to the units. Keep writing it; do not drop the prose path in this version.
+
+### Step 4 - Reference file proposal (optional)
+
+After writing LEARNINGS.md, check each learning entry with `Proposed reference update: yes`.
+
+For each such entry: generate a proposed addition to the appropriate `reference/` file (e.g., `reference/heuristics.md`, `reference/anti-patterns.md`).
+
+Print the proposal to the terminal and ask the user to review:
+
+```
+━━━ Reference update proposal ━━━
+
+Learning L-03 suggests adding to reference/anti-patterns.md:
+
+  ### Anti-pattern: Overloaded primary button
+  Using the primary button style for more than one action per screen
+  reduces clarity and violates Nielsen's heuristic #4 (consistency).
+  Evidence: DESIGN-VERIFICATION.md, cycle 3.
+
+Accept this update? [y/n/edit]
+```
+
+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
+
+```
+━━━ Learnings extracted ━━━
+Source files scanned:    <N>
+Learnings written:       <N>
+Reference proposals:     <N>  (<M> accepted)
+Output: .design/learnings/LEARNINGS.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Required reading (conditional)
+
+@.design/intel/decisions.json (if present)
+@.design/intel/patterns.json (if present)
+@.design/learnings/LEARNINGS.md (if present)
+
+## EXTRACT-LEARNINGS COMPLETE

package/scripts/skill-templates/fast/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: gdd-fast
+description: "Trivial inline design task. No subagents, no planning documents, no pipeline stages. Just do the thing described. Activates for requests involving a single quick design fix, a one-shot change, or a fast targeted edit."
+argument-hint: "<task description>"
+tools: Read, Write, Edit, Bash, Grep, Glob
+disable-model-invocation: true
+---
+
+# {{command_prefix}}fast
+
+The leanest possible execution path. No subagents, no STATE.md update, no DESIGN-*.md artifacts. Read the target file, apply the change inline, commit.
+
+## When to use
+
+- "Change this button's border-radius to 8px"
+- "Add a hover state to the nav links"
+- "Fix the mobile breakpoint on the hero"
+- Single-file or single-component obvious changes
+
+## When NOT to use
+
+- Multi-component changes.
+- Anything touching tokens used across the app.
+- Anything requiring a design decision (taste, tradeoff, scope).
+- Use `{{command_prefix}}quick` or the full pipeline instead.
+
+## 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.
+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).
+6. Commit with message: `fix: <task description>` (one commit, one change).
+7. Print: "Done: <summary of what changed>."
+
+## Do Not
+
+- No subagent spawns.
+- 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 `{{command_prefix}}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 `{{command_prefix}}apply-reflections`.
+
+Synchronous emitter call (via Bash):
+
+```bash
+node -e '
+const { appendChainEvent } = require("./scripts/lib/event-chain.cjs");
+const { createHash, randomUUID } = require("node:crypto");
+const intent = process.env.GDD_INTENT || "";
+const payload = {
+  event_id: randomUUID(),
+  parent_event_id: null,
+  source: "fast",
+  context_hash: createHash("sha256").update(intent).digest("hex"),
+  intent_summary: intent.slice(0, 256),
+  suggested_kind: "skill",
+  evidence_refs: [],
+};
+appendChainEvent({
+  agent: "fast",
+  outcome: "capability_gap",
+  payload,
+  type: "capability_gap",
+  timestamp: new Date().toISOString(),
+  sessionId: process.env.GDD_SESSION_ID || "fast-cli",
+});
+'
+```
+
+Notes:
+- `evidence_refs` is empty `[]` for fast (no trajectory in `{{command_prefix}}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 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:
+- **Trigger 1**: Step 2 returns zero candidate files for the task description (target is genuinely missing).
+- **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).
+
+## FAST COMPLETE