@kiwidata/grimoire 0.1.2 → 0.1.4

package/skills/grimoire-design/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: grimoire-design
+description: Generate UI/UX designs grounded in a stated user problem — variants, component states, brand-token compliance, and derived Gherkin scenarios. Use when the user wants to design, wireframe, mock up, or rethink a UI surface.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-design
+
+Generate UI/UX designs grounded in a stated user problem. Produces variants, enumerates component states, lints for brand drift, and derives Gherkin scenarios that hand off cleanly to `grimoire-draft` and `grimoire-plan`.
+
+This is one skill, not three (see ADR-0017). Brand-drift lint is a *mode* of this skill, not a separate skill — same artifact (`tokens.json`), same skill, different verb.
+
+## Triggers
+- User describes UI/UX work: a new screen, a redesign, a flow, a component
+- User mentions a design tool by name (Figma) in the context of producing work
+- Loose match: contains "design", "wireframe", "ui", "ux", "mockup", "layout", "figma" combined with "new", "draft", "explore", "redesign", or "rethink"
+
+## Routing
+- Non-UI behavior change (API, data model, business logic) → `grimoire-draft` directly
+- Brand-only updates (new logo, new color, capture missing tokens) → stay here; use `--capture-brand` or `--lint`
+- Tech-check before designing ("should I worry about anything?") → `grimoire-design-consult`
+- Bug in an existing UI → `grimoire-bug`
+- Pure refactor of UI code (no behavior change) → no grimoire artifact; just do it
+
+## Workflow
+
+### 1. Qualify
+Is this actually UI/UX work? If the user is asking for an API contract, a data model change, or backend logic with no user-facing surface, route to `grimoire-draft` and stop.
+
+If a `.grimoire/changes/<change-id>/consult.md` exists for this change-id (from a prior `grimoire-design-consult` run), read it now. Parse the `## Inferred assumptions` and `## Inferred givens` sections verbatim — these exact H2 headers are written by `grimoire-design-consult` and must not be paraphrased or fuzzy-matched. Propagate both lists into every subsequent prompt in this workflow. Specifically:
+
+- **Step 6 (Variant Generation)**: exclude patterns that violate any given. For example, if a given says "no JS-heavy patterns due to perf budget", do not produce a variant that relies on client-side state machines. State the exclusion in the affected variant's tradeoff line so reviewers see why the pattern was avoided.
+- **Step 9 (Derive Gherkin)**: reference inferred assumptions in scenario preconditions where applicable (e.g., a Given line that mirrors the assumption "user is authenticated before reaching this surface"). Cite givens by their consult.md bullet when a scenario's expected outcome depends on the given.
+
+Carry the open-questions list (also in `consult.md`) forward as warnings — surface unresolved items to the user when they affect a variant choice or scenario, but do not block on them. Open questions are flags, not gates.
+
+### 2. Problem Statement (soft gate)
+Ask for the user problem this design addresses. If the user provides one up-front, write it to `.grimoire/changes/<change-id>/designs/problem.md` and continue.
+
+If the user skips or describes the design without a problem (e.g., "make a settings page"), emit the soft-gate warning verbatim:
+
+> No user problem articulated. Generic designs ≈ wasted iteration.
+> The most common cause of redesigns is missing problem context.
+> Strongly recommend stating the problem first.
+
+Then ask: "Proceed without problem statement? (y/N)". On `y`, log `problem_statement: skipped (user override)` in `problem.md` and continue. On `N` or no answer, offer the framework menu:
+
+| option | format |
+|---|---|
+| jtbd | When [situation], I want to [motivation], so I can [outcome] |
+| lean-ux | Business problem / users / outcomes / solutions / hypotheses |
+| hmw | How might we [verb] [user] [outcome]? |
+| pr-faq | Press release + FAQ working-backwards |
+| freeform | (user writes their own) |
+
+Render the chosen template for the user to fill in. Write the result to `problem.md`.
+
+### 3. User Flow & Success Metrics
+Ask for a **friction-log narrative** as the default minimum-viable level — a short prose description of the current user journey and where it hurts. Offer (but never force) two upgrades: Mermaid journey diagram, then service blueprint.
+
+Separately — not bundled — ask "What are the user's current pain points?" Accept a bulleted list, free text, or "none known". Capture pain points in `problem.md` under a dedicated `## Pain Points` section. Variants generated in step 6 must each state which pain points they address (or explicitly mark "deferred").
+
+Ask for at least one measurable success metric (e.g., "reduce support tickets about lockouts by 50%"). If the user cannot articulate one, note `no success metric — design effectiveness will be hard to evaluate` as an assumption in `problem.md`.
+
+### 4. Lazy Component Inventory
+If `.grimoire/docs/components.md` is absent AND the project has UI code, ask the user before scanning. On approval, scan for:
+
+- `components.json` (shadcn-ui marker)
+- `tailwind.config.{js,ts}` (Tailwind setup)
+- MUI / Chakra / Mantine / Radix imports in `package.json`
+- `*.stories.{ts,tsx,jsx,js}` (Storybook stories)
+
+Write findings to `.grimoire/docs/components.md` listing detected components with file paths and known variants. Skip the scan entirely if no UI signals are present (greenfield or non-UI surface). Subsequent variants prefer existing components over net-new designs and flag net-new explicitly.
+
+### 5. Brand Grounding
+Read `.grimoire/brand/tokens.json` and `.grimoire/brand/voice.md` if they exist. Use the format documented in `../references/brand-tokens-format.md`. Required groups: `color.*`, `font.family.*`, `font.size.*`, `spacing.*`.
+
+**Malformed `tokens.json`**: if JSON parse fails or required `$value` fields are missing, emit a one-line error:
+
+> tokens.json malformed at `<path>` — `<parse-error-description>`. Continuing without brand grounding.
+
+Continue the workflow without brand grounding rather than crashing. Variants will use neutral defaults and the user can fix the file and re-run. Anchor: pre-mortem failure mode #6 — undetected brand drift produces low-quality output, but a crashed skill produces zero output.
+
+**Absent `tokens.json`**: continue silently with neutral defaults. Note in the generated HTML that no tokens were found.
+
+### 6. Variant Generation
+Produce **3 variants by default**. Each variant explicitly states the tradeoff it optimizes for (e.g., "minimal clicks", "maximum information density", "progressive disclosure") and lists which pain points from step 3 it addresses.
+
+Output target by precedence — pick the highest-fidelity option available:
+
+1. **Figma MCP** configured (`project.design_tool.mcp` present) → query Figma; reference variants by node ID in `.grimoire/changes/<change-id>/designs/variants.md`
+2. **Static HTML** → write `.grimoire/changes/<change-id>/designs/variant-{n}.html` per variant. Self-contained, no CDN. Brand tokens injected as CSS custom properties in `:root` per `../references/design-input-formats.md` §5
+3. **ASCII** → inline in `variants.md` for trivial scope (copy change, single-field form, TUI surface) per `../references/design-input-formats.md` §6
+
+If Figma MCP is configured but unreachable, emit one-line "Figma MCP unreachable — `<error>`. Falling back to static HTML." and continue with HTML. Never crash.
+
+Each variant must reference brand tokens from `tokens.json` (if present) and consult `../references/design-heuristics.md` to avoid common omissions (missing feedback, no escape hatch, contrast too low, novel pattern where a standard exists).
+
+When the user requests a revision of a specific variant ("redo variant 2 with a wizard pattern"), regenerate only that variant; leave the others unchanged.
+
+### 7. State Enumeration
+For each interactive component in the selected variant, walk the state checklist from `../references/design-heuristics.md` §5:
+
+| state | required? |
+|---|---|
+| default | yes |
+| loading | yes |
+| empty | yes |
+| error | yes |
+| success | conditional (forms, async actions) |
+| disabled | conditional (inputs, buttons) |
+| readonly | conditional (inputs) |
+| over-limit | conditional (rate-limited / quota'd actions) |
+
+If the user attempts to mark the design complete with a required state missing, emit the soft gate:
+
+> Missing `<state>` state. Most "the design didn't work in production"
+> complaints trace to missing error / loading / empty handling.
+
+Ask "Skip `<state>` state? (y/N)". On confirm, log the skip as an unvalidated assumption in `problem.md` under a `## Skipped States` section (created if absent). Infer conditional state upgrades from change context — a form submission upgrades `success` to required; a rate-limited action upgrades `over-limit` to required.
+
+### 8. Render Preview
+For HTML output, write a single `.grimoire/changes/<change-id>/designs/preview.html` showing each component in each state, side-by-side. Each state is labeled and visually distinct (loading shimmer, error banner, empty placeholder, etc.). Designer opens the file directly in a browser — no `grimoire preview` CLI command exists in v1.
+
+Skip preview rendering when output is Figma (the Figma file IS the preview) or ASCII (the markdown table IS the preview).
+
+### 9. Derive Gherkin
+Propose draft `.feature` files at `.grimoire/changes/<change-id>/features/<capability>/`. One Scenario per (component × state). Each Scenario has Given / When / Then steps grounded in the design.
+
+Apply surface-conditional adversarial scenarios per `../references/adversarial-personas.md`:
+
+- `project.surface: web` → keyboard-navigation, screen-reader-announcement, color-contrast scenarios
+- `project.surface: mobile` → touch-target-size, gesture-conflict scenarios
+- `project.surface: tui` → keyboard-navigation only (no screen-reader, no contrast)
+
+Apply security tags per `../references/security-compliance.md`. Components handling user input get `@input-validation` and at least one negative scenario.
+
+Present the proposed scenarios for review: "Review proposed scenarios — accept, edit, or reject each." Accept all / accept some / edit / reject any. Rejected scenarios do not get written.
+
+### 10. Handoff
+When the user accepts proposed scenarios, the change folder is populated. Suggest the next step:
+
+> Run `grimoire-draft` to refine the manifest and ADRs, or `grimoire-plan` to break into tasks.
+
+Skill is done.
+
+## Revision Mode
+
+Triggers: user says "revise", "iterate", "refine", "update variant", "change the design", "I want to try again with variant N", "add a state", "update the scenarios", or `--revise`.
+
+Revision mode re-enters an **existing** change without restarting the full workflow. Steps 1–5 (problem statement, user flow, component inventory, brand grounding) are already done — skip them unless the user says the problem itself has changed.
+
+**Revision workflow:**
+
+1. Read the existing artifacts for the change-id: `problem.md`, `designs/variants.md` or `variant-*.html`, `features/`. Show a brief summary of what exists:
+   > Current design: 3 variants (wizard, inline, progressive). Accepted variant: 2. 8 Gherkin scenarios. 4 component states documented.
+
+2. Ask one question: "What would you like to change?"
+
+3. Based on the answer, identify the minimum affected steps and run only those:
+
+   | User says | Re-run |
+   |---|---|
+   | "redo variant 2 with a different pattern" | Step 6 — single variant only |
+   | "add empty state to the search field" | Step 7 — state enumeration for that component |
+   | "the problem is actually X not Y" | Update `problem.md`, re-run step 3 (user flow + pain points), then step 6 for all variants |
+   | "make it more accessible" | Step 9 — re-derive adversarial Gherkin scenarios |
+   | "show me 2 more variants" | Step 6 — additive, do not overwrite existing variants |
+   | "the preview looks wrong" | Step 8 — regenerate preview only |
+
+4. Leave all other artifacts unchanged.
+
+5. If Gherkin scenarios from a prior pass were already accepted, ask before overwriting:
+   > These scenarios were previously accepted — overwrite with revised versions? (y/N)
+
+6. On completion, suggest `grimoire-draft` or `grimoire-plan` if not yet run, or `grimoire-verify` if implementation is already in progress.
+
+**Revision is not a full restart.** If the design direction has fundamentally changed (different surface, new user, different problem), start a new change-id via `grimoire-design` fresh rather than revising.
+
+## Modes
+
+The flags below are **conversational invocations** the AI interprets, not real CLI subcommands of the `grimoire` binary. Per ADR-0010, skills are pure markdown — there is no executable code behind `--lint`, `--variants=N`, or `--capture-brand`. The AI reads these as user intent and runs the corresponding flow.
+
+### `--capture-brand` / "capture brand" / "capture brand guidelines"
+When the user says "capture brand" or invokes `--capture-brand`, run the brand-capture flow using the same prompts as `grimoire init` onboarding (see `src/core/init.ts` `askPreferences()` brand-capture block):
+
+- Ask for primary / secondary / accent color (hex, validated against `/^#([0-9a-f]{3}|[0-9a-f]{6})$/i`; re-prompt on invalid)
+- Ask for font family, base font size, base spacing unit
+- Optional: logo path, favicon path
+- Ask for one Do-example and one Don't-example for voice/tone
+- Write `.grimoire/brand/tokens.json` in DTCG format (see `../references/brand-tokens-format.md`)
+- Write `.grimoire/brand/voice.md` from the captured do/don't pair
+
+Before writing, glob the repo root for existing `tokens.json` or `design-tokens.json`. If found, ask "Use existing `<path>`? (Y/n)" — on yes, copy it to `.grimoire/brand/tokens.json` instead of prompting from scratch.
+
+Do **not** create `.grimoire/brand/` unless the user has explicitly opted in via this mode or the onboarding flow.
+
+### `--lint` / "lint brand" / "lint brand drift"
+When the user says "lint brand" or invokes `--lint`, run the brand-drift lint flow described in the Lint Mode section below.
+
+### `--variants=N` / "give me N variants" / "N variants"
+When the user invokes `--variants=N` or says "give me 5 variants", override the default count of 3 in step 6. Accept any positive integer up to 10. Above 10, ask the user to confirm — variants become noise beyond that count.
+
+## Lint Mode
+
+Brand-drift lint cross-references hardcoded values in code against `.grimoire/brand/tokens.json` and suggests token replacements.
+
+### Scope
+- Default: scan **staged files** (`git diff --cached --name-only`) — fast, dev-loop-friendly
+- `--all` / "scan all" → scan all tracked files (slower; honor `.grimoire/mapignore`)
+- File types: `.css`, `.scss`, `.less`, `.html`, `.jsx`, `.tsx`, `.vue`, `.svelte` (configurable per project conventions)
+
+### What it looks for
+- Hardcoded color hex values (`#0066ff`, `#06f`, `rgb(...)`)
+- Hardcoded `px` / `rem` / `em` values
+- Hardcoded `font-family` strings
+
+Each hit is cross-referenced against `tokens.json`. If a near-match exists, emit a suggestion:
+
+> `src/components/Button.css:14` — `#0066ff` matches `color.primary`. Replace with `var(--color-primary)`.
+
+### Clean state
+If zero drift is found, emit exactly:
+
+> No brand drift detected across N files scanned.
+
+And exit 0. Do **not** print a long "everything passed" report — clean state is a one-liner. False positives erode trust faster than missed findings.
+
+### Malformed `tokens.json`
+Catch JSON parse errors and missing `$value` fields. Emit a one-line error with the parse description and exit non-zero — this is a misconfiguration, not a lint finding:
+
+> tokens.json malformed at `<path>` — `<parse-error>`. Fix or remove.
+
+Do not attempt partial lint with a half-parsed token file.
+
+### Absent `tokens.json`
+Clean exit. Emit:
+
+> No brand tokens to lint against. Run `grimoire init` or `grimoire-design --capture-brand` first.
+
+Do not error — absence is a valid state for projects that haven't onboarded brand capture yet.
+
+### Integration
+`grimoire-precommit-review` invokes this lint automatically when `.grimoire/brand/tokens.json` exists. The lint logic is also referenced from `../references/visual-fidelity.md` (the shared reference used by `grimoire-review`, `grimoire-precommit-review`, and `grimoire-pr-review` for the visual-fidelity tier).
+
+## Important
+- **Pure markdown.** This skill is interpreted by an LLM per ADR-0010. Do not generate executable code or shell scripts to satisfy any step. The variant HTML files are output artifacts; the workflow itself is prose the AI follows.
+- **Ask before scanning large codebases.** Component-inventory scans (step 4) and `--lint --all` scans can be expensive on monorepos. Confirm with the user before scanning more than ~500 files.
+- **Honor `.grimoire/mapignore`.** Any scan (component inventory, brand lint) must respect mapignore patterns. Reuse the same exclusion logic as `grimoire map`.
+- **Do not create `.grimoire/brand/` unprompted.** The directory only appears when the user opts in via onboarding or `--capture-brand`. Reading from a missing brand directory is a valid state — fall back to neutral defaults.
+- **Never log Figma access tokens.** The token lives in `FIGMA_ACCESS_TOKEN` env var, read by the MCP server. Never write it to config, never echo it in transcripts, never include it in artifacts.
+- **Soft gates are warnings, not blockers.** The problem-statement gate (step 2) and the state-enumeration gate (step 7) warn aggressively but accept user override. Record overrides as assumptions so they surface in review.
+- **Brand drift findings are suggestions, not blockers.** Lint mode proposes token replacements; it does not auto-rewrite code. The user decides whether to apply.
+
+## Done
+When the user accepts proposed Gherkin scenarios and the change folder contains `problem.md`, `designs/`, and `features/`, the workflow is complete. Suggest `grimoire-draft` (manifest + ADRs) or `grimoire-plan` (task breakdown) next.

package/skills/grimoire-design-consult/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: grimoire-design-consult
+description: Pre-design technical consult. Security and data personas interview the designer (or engineer) about a proposed change before any artifacts exist, surfacing assumptions and constraints early. Use before grimoire-design or grimoire-draft when the change might touch sensitive data, compliance, or risky surfaces.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-design-consult
+
+A **pre-design Q&A** with security and data personas. The designer brings a problem statement; the personas ask clarifying questions; the skill distills the transcript into assumptions, givens, and open questions that downstream `grimoire-design` and `grimoire-draft` consume.
+
+This is **not** a review. No artifacts are required to exist. No blocker/suggestion findings are produced. The output is a conversation transcript plus inferred constraints.
+
+## Triggers
+- User says "consult", "tech check", "tech check this idea", "should I ...", "what should I worry about", or "before designing"
+- User wants security or data sign-off on an idea before investing in design work
+- Loose match: "talk through", "sanity check", "pre-design", "thinking about" combined with concerns about data, auth, compliance, or PII
+
+## Routing
+- User already has a clear design direction and just wants to produce variants → `grimoire-design`
+- A full design with artifacts (problem.md, variants, scenarios) already exists and the user wants critical feedback → `grimoire-review`
+- User describes a bug rather than a new design → `grimoire-bug` or `grimoire-bug-report`
+- Change is purely behavioral / non-UI and the user is ready to spec it → `grimoire-draft`
+
+## Prerequisites
+- A `change-id` (existing or new). If no change exists yet, create the directory `.grimoire/changes/<change-id>/` with just a placeholder so `consult.md` has a home — no manifest, features, decisions, or tasks needed.
+- `.grimoire/config.yaml` exists (for surface, compliance, brand context). If absent, the consult still runs but skips the briefing axes that would require it.
+
+## Skipping
+This skill is optional. Engineers and designers can skip straight to `grimoire-draft` or `grimoire-design`. When the user skips and the change touches PII / payments / auth / compliance tags, downstream skills emit a one-line soft suggestion ("Consider `grimoire-design-consult` first — this change touches PII") but do not block.
+
+## Modes
+
+These are **conversational invocations** the AI interprets, not commander.js subcommands of the `grimoire` binary. Per ADR-0010, skills are pure markdown — the AI decides how to behave based on what the user said.
+
+- `--personas=security,data,qa` or "add QA persona" / "include the product manager" — adds personas beyond the default Security + Data pair. Allowed names match `../references/review-personas.md` §4 (product, senior, security, qa, data, adversarial-user). Do not load Code Style Reviewer or Contrarian — they are diff-time personas.
+- "shorter consult" / "quick consult" — cap each persona at 3 questions instead of the usual 5-8
+- "skip security" / "skip data" — drop a default persona for a single run (rare; warn the user once if their problem statement mentions PII / payments / auth and they skip security)
+
+## Workflow
+
+### 1. Collect Minimal Input
+Open with a brief orientation so the designer knows what to expect — display this verbatim before asking anything:
+
+> **Design consult** — two expert personas (Security Engineer + Data Engineer) will ask you questions about your idea before any design work begins. Their goal is to surface constraints and assumptions early, not find problems with a finished design.
+>
+> We'll start with your problem statement, then the personas take turns. Each asks **one question at a time** — you'll see `[Persona — Q N/total]` so you always know where you are.
+
+Collect inputs in three sequential turns — not a combined prompt:
+
+**Turn 1:** Ask only for the problem statement.
+> What user problem or business need does this design address? (One paragraph is enough.)
+
+If the user provides a clear problem statement, proceed. Do not gate on optional inputs.
+
+**Turn 2:** Derive a change-id slug from the problem statement and confirm in one line.
+> I'll track this change as `<slug>` — OK, or would you prefer a different name? (A "change ID" is just a short folder name we use to group your design artifacts.)
+
+On confirm or no reply, use the slug. On correction, use the user's name.
+
+**Turn 3 (optional context):** Ask for user flow and data together — these are supplementary and the personas will cover what's missing.
+> Two optional questions — type "none" or skip with Enter for either:
+> 1. Proposed user flow (1–2 sentences — e.g. "user taps X → sees Y → confirms Z"). Note: this should describe an existing journey or rough idea, not a solution — the design will derive the flow.
+> 2. What data will this design touch? (e.g. "user profiles", "payment methods", "none")
+
+### 2. Build the Mini-Briefing
+Follow the briefing pattern in `../references/review-personas.md` §1, but **pared down** for pre-design context. Skip the feature inventory (the change has no features yet) and focus on the axes that matter for security / data Q&A:
+
+**Sources** (subset of review-personas.md §1):
+- `.grimoire/config.yaml` → `project.surface`, `project.compliance`, `project.language`
+- `.grimoire/docs/context.yml` if present → deployment environment, related services, trust boundaries
+- All `.grimoire/decisions/*.md` with `status: accepted` — extract ID, title, top driver
+- Tag histogram across `.grimoire/changes/**/*.feature` for data-sensitivity signals (pii, payment, auth, phi)
+- `.grimoire/brand/tokens.json` existence (one bit — not needed for security/data questions but informs surface context)
+
+**Briefing block** (inject as preface to every persona, mirror review-personas.md §1 format):
+
+```markdown
+## Project Briefing (consult)
+
+**Surface:** <tui | web | mobile | api | mixed | unknown>
+**Stage:** <prototype | internal | customer-facing | regulated — from compliance + README>
+**Data sensitivity:** <none | pii | financial | phi — from tag histogram + compliance>
+**Compliance:** <list configured frameworks, or "none">
+**Threat surface signals:** <tags with count >0 — auth=N, pii=N, payment=N>
+**Active constraints (accepted ADRs):**
+- ADR-XXXX — <title>
+- ...
+```
+
+Skip the Feature Inventory and Linked-change Non-goals sections — there are no features yet and the consult precedes the manifest.
+
+### 3. Engage Personas in Q&A Mode
+**This is the core difference from `grimoire-review`.** Personas ASK questions; the designer ANSWERS. No blocker/suggestion grading. No materiality gate (the gate exists to keep reviewers from manufacturing findings — Q&A doesn't have findings).
+
+Default personas: **Security Engineer** + **Data Engineer**. Add others only when the user invokes a mode flag (e.g., `--personas=security,data,qa`).
+
+For each engaged persona:
+- Read the persona's section in `../references/review-personas.md` §4 to understand its concerns (what it cares about, what it would flag in a review).
+- Translate those concerns into clarifying questions for the designer, using the interview patterns in `../references/elicitation-personas.md` for that persona.
+- Determine a question count for this persona: 5 by default; 3 in "quick consult" mode; fewer if the problem statement or briefing already answers likely questions. Announce the count once before the first question: e.g. `Security Engineer — 5 questions.`
+- Ask **one question per turn**. Never list multiple questions in a single message. Prefix every question with its progress marker: `[Security — Q 1/5]`, `[Security — Q 2/5]`, etc.
+- Wait for the answer before asking the next question. Do not hint at or pre-list upcoming questions.
+- Skip questions whose answers are already obvious from the problem statement, briefing, or a prior answer — decrement the count and note it inline: `[Security — Q 3/5 skipped — covered above]`.
+- Questions are conversational. Examples:
+  - Security: "What user data flows through this screen?", "Does any of it leave the boundary of our service?", "Is this surface authenticated, or public?", "Are there compliance frameworks (GDPR, HIPAA) that apply to this data?"
+  - Data: "What entities does this design touch?", "Are you reading from existing tables or creating new ones?", "If new fields are needed, what's the cardinality and nullability?", "Are there migrations implied?"
+- Do **not** dump a checklist.
+- Do **not** produce blocker/suggestion findings. If a persona spots a real risk, frame it as a question ("Have you considered what happens if X?") not a verdict ("[blocker] X is wrong").
+
+Record the transcript verbatim for `consult.md` — questions asked, designer's answers, follow-up questions.
+
+### 4. Distill Assumptions, Givens, and Open Questions
+Once each persona has finished its Q&A pass, summarize the transcript into three distinct lists:
+
+- **Inferred assumptions** — things the design must hold true to be valid. Examples: "All write operations happen behind authentication." / "PII is only displayed to the owning user, never logged." Phrase as positive declarations the design will need to honor.
+- **Inferred givens** — constraints from existing systems, compliance, or accepted ADRs that the design cannot change. Examples: "User auth flows through the existing `auth-service` (ADR-0007)." / "PII storage must encrypt at rest per project.compliance: gdpr."
+- **Open questions** — items the designer could not answer in this consult. These are flags for follow-up, not blockers. Examples: "Unknown: retention window for payment audit logs — needs product input." / "Unknown: whether mobile clients will consume this surface in phase 1."
+
+Be honest about the boundary between assumption and given: a *given* is something the world imposes (compliance, an ADR, an existing service contract); an *assumption* is something the designer commits to upholding.
+
+### 5. Write `.grimoire/changes/<id>/consult.md`
+Compose the file with explicit, implementable sections in this order:
+
+```markdown
+# Pre-design consult: <change-id>
+
+## Problem statement
+<user's problem statement, verbatim>
+
+## Proposed user flow
+<user's input, or "Not provided">
+
+## Data the design will touch
+<user's input, or "Not provided">
+
+## Project Briefing (consult)
+<briefing block from step 2>
+
+## Security Q&A
+**Q:** <question 1>
+**A:** <designer's answer>
+
+**Q:** <question 2>
+**A:** <designer's answer>
+...
+
+## Data Q&A
+**Q:** <question 1>
+**A:** <designer's answer>
+...
+
+## <Any other engaged personas> Q&A
+<same Q/A format>
+
+## Inferred assumptions
+- <assumption 1>
+- <assumption 2>
+...
+
+## Inferred givens
+- <given 1, with ADR / compliance citation where applicable>
+- <given 2>
+...
+
+## Open questions
+- <unanswered item 1 — flagged for follow-up>
+- <unanswered item 2>
+...
+
+## Personas engaged
+- Security Engineer
+- Data Engineer
+<- ... other personas if added via mode flag>
+```
+
+Do not invent content for empty sections. If the designer skipped "Proposed user flow", write "Not provided" — do not synthesize one. If a Q&A turn produced no actionable assumption, the assumptions list can be short.
+
+### 6. Handoff
+Tell the user what runs next and what those skills will do with `consult.md`:
+
+- **`grimoire-design`** on the same `change-id` will read `consult.md` first, propagate assumptions and givens into prompts for variant generation (e.g., "exclude patterns that violate givens"), and copy the lists into `manifest.md` when the designer accepts a direction.
+- **`grimoire-draft`** on the same `change-id` will read `consult.md` and copy "Inferred assumptions" + "Inferred givens" into `manifest.md` (Assumptions section, plus a new Givens section) at level 3-4 complexity.
+- **Open questions** travel into `manifest.md` as unvalidated assumptions for the designer/PM to resolve before plan.
+
+Do not invoke the next skill automatically. Confirm with the user, then suggest the next command.
+
+## Important
+- **This is Q&A, not findings.** Personas ASK questions of the designer; they do not produce blocker/suggestion verdicts. If you catch yourself writing `[blocker]` or `[suggestion]` in `consult.md`, stop — that is `grimoire-review`'s job, not this skill's.
+- **No materiality gate.** The review-personas materiality gate exists to prevent manufactured findings. Q&A doesn't produce findings, so the gate does not apply — but the *intent* still holds: ask questions whose answers will change the design, not questions whose answers are already obvious from the briefing.
+- **Minimal input bar.** Problem statement only is enough to start. Do not interrogate the user before engaging personas — the personas exist to ask the missing questions.
+- **Available to engineers too.** This skill is not designer-exclusive. An engineer who says "I'm thinking about adding X, what should I worry about?" is invoking the same workflow. The output flows into `grimoire-draft` the same way it flows into `grimoire-design`.
+- **Do not load Contrarian or Code Style personas.** Contrarian challenges other personas' findings; Code Style reviews diffs. Neither has a role in pre-design Q&A.
+- **Honor the briefing pare-down.** Do not include the full review-personas.md §1 briefing — skip Feature Inventory and Linked-change Non-goals. They add noise without informing the questions a consult needs to ask.
+- **Pure markdown skill.** Do not generate executable code. The `--personas=` and "quick consult" mode markers in this file describe how the AI interprets user phrasing — they are not CLI flags of the `grimoire` binary.
+
+## Done
+When `consult.md` is written and the user has acknowledged the handoff path, the consult is complete. Suggest `grimoire-design` (visual surface work) or `grimoire-draft` (behavioral specs) as the next step on the same `change-id`.

package/skills/grimoire-discover/SKILL.md

@@ -66,10 +66,11 @@ If the snapshot includes a `duplicates` section (from `grimoire map --duplicates
 This replaces the need to manually read every source file to extract symbols. The graph gives you AST-accurate function signatures, call relationships, and dead code detection across 66 languages.
 
 ### 2. Determine Scope
-Ask the user what to document:
+Ask the user what to document (or accept the scope passed in by a calling skill):
 - **Full scan** — document all areas from the snapshot (default for first run)
 - **Area scan** — document specific directories (e.g., "just the API layer")
 - **Gap fill** — only document areas flagged as `undocumented` in the snapshot
+- **Targeted refresh** — a list of directories is passed in (from `grimoire-precommit-review` doc freshness check or `grimoire-plan` staleness gate). Skip the full snapshot walk. Go directly to step 3 for each named directory, regenerate only those area docs, and update their `last_updated` entries in `index.yml`. This is the fast-path mode for post-change maintenance — it does not touch areas outside the passed list.
 
 Check `.grimoire/docs/index.yml` if it exists — don't redo work unless refreshing.
 
@@ -174,6 +175,66 @@ Scan the codebase for data models, ORM definitions, migration files, and schema
 
 If `.grimoire/docs/data/` already exists, update it rather than regenerating. Diff against existing schema.yml to flag new models or removed fields.
 
+### 5.5 Component Inventory (optional)
+
+Scan the codebase for an existing UI component library, then produce `.grimoire/docs/components.md` documenting reusable components. This inventory lets `grimoire-design` reuse what exists instead of generating duplicate components.
+
+**Detection — component library:**
+
+| Signal | What it tells you |
+|--------|------------------|
+| `components.json` | shadcn/ui — components live under the configured `aliases.components` path (typically `components/ui/`) |
+| `tailwind.config.{js,ts}` | Tailwind project — utility-first; components are project-local |
+| `package.json` deps: `@mui/material` | Material UI — components imported from `@mui/material/*` |
+| `package.json` deps: `@chakra-ui/react` | Chakra UI — components imported from `@chakra-ui/react` |
+| `package.json` deps: `@mantine/core` (or any `mantine` package) | Mantine |
+| `package.json` deps: `@radix-ui/*` | Radix primitives — usually wrapped by shadcn or project components |
+
+**Detection — Storybook:**
+
+| Signal | What it tells you |
+|--------|------------------|
+| `.storybook/main.{ts,js}` | Storybook configured — stories define canonical component variants |
+| `*.stories.{ts,tsx,jsx,js}` | Story files — each story is a documented component variant |
+
+**Skip condition:** If no library signal and no story files are found, emit a single-line note ("No UI component signals detected — skipping component inventory.") and continue to §6. Do not create `components.md`.
+
+**Workflow:**
+1. Detect the library (or libraries) using the signals above
+2. Locate component source files — for shadcn, walk `components/ui/`; for project-local components, look under `src/components/`, `app/components/`, or wherever the convention places them
+3. For each component file, extract: name, file path, exported variants (e.g., `variant="primary|secondary"`), and notable props (especially required ones)
+4. If Storybook is present, walk `*.stories.*` files to harvest the canonical variant list per component — stories are the source of truth for which variants exist
+5. Write `.grimoire/docs/components.md` listing each component with file path, variants, and key props
+
+**`components.md` format:**
+
+```markdown
+# Component Inventory
+> Last updated: YYYY-MM-DD
+> Library: <shadcn | MUI | Chakra | Mantine | project-local | mixed>
+
+## Components
+
+| Component | Location | Variants | Key Props | Notes |
+|-----------|----------|----------|-----------|-------|
+| `Button` | `components/ui/button.tsx` | `default`, `destructive`, `outline`, `ghost`, `link` | `variant`, `size`, `asChild` | Wraps Radix Slot when `asChild` |
+| `Dialog` | `components/ui/dialog.tsx` | — | `open`, `onOpenChange` | Compound: `Dialog`, `DialogTrigger`, `DialogContent` |
+
+## Stories
+<Only if Storybook detected. List story files and the variants they document.>
+
+| Story File | Component | Documented Variants |
+|------------|-----------|---------------------|
+| `Button.stories.tsx` | `Button` | Primary, Secondary, Destructive, Loading |
+```
+
+**Rules:**
+- Document what exists in code, not what should exist. If the project has both shadcn and ad-hoc components, list both and note the inconsistency.
+- Point to source files; do not duplicate component code into the doc.
+- Variants come from prop unions in the type signature OR from the canonical Storybook stories — prefer Storybook when present.
+- Only list components meant for reuse. Skip one-off page-level components (e.g., `LoginPage`) unless they're imported elsewhere.
+- If `.grimoire/docs/components.md` already exists, update it — diff against existing entries to flag new or removed components.
+
 ### 6. Generate Project Context
 
 Scan the codebase for deployment and infrastructure artifacts, then populate `.grimoire/docs/context.yml`. This file captures the project's ecosystem — how it's deployed, what services it talks to, and what infrastructure it depends on. If `context.yml` doesn't exist, copy it from the template first (`grimoire init` creates it, but this handles projects initialized before this feature).
@@ -280,7 +341,9 @@ These are read by `grimoire map` and affect the snapshot this skill consumes.
 - The **plan** skill should read `.grimoire/docs/` before generating tasks — look for existing utilities in the reuse inventory, follow documented patterns
 - The **verify** skill can check new code against documented patterns
 - The **audit** skill can trigger a discover pass as part of onboarding
-- Run `grimoire map --refresh` periodically to detect new undocumented areas, then `/grimoire:discover` to fill the gaps
+- The **design** skill reads `.grimoire/docs/components.md` first to avoid generating duplicate components
+- The **precommit-review** skill checks area doc freshness on every commit and invokes discover in targeted refresh mode for stale dirs — this is the primary maintenance trigger, not a periodic manual task
+- The **plan** skill gates on staleness for level 3-4 changes and directs the user to run targeted refresh before planning
 
 ## Important
 - **Start from the snapshot.** Don't scan the filesystem yourself — `grimoire map` already did that. Read `.snapshot.json` for structure, then use `codebase-memory-mcp` graph queries for symbols and call graphs (if available), and read actual code files for meaning.