@kiwidata/grimoire 0.1.3 → 0.1.5

package/skills/grimoire-bug/SKILL.md

@@ -83,20 +83,52 @@ generation, causing user lookup to fail on the reset page.
 Added scenario: "Password reset with plus-sign email"
 ```
 
-### 5. Create Fix Branch
-Before writing any code, create a branch for the fix:
+### 5. Decide the Branch
+
+Default bias: **stay on the current branch if the bug is related to in-flight work.** Only create a new branch when the bug is clearly a separate concern from whatever the current branch is doing.
+
+Snapshot state first:
+
 ```
-fix/<short-description>
+git branch --show-current
+git status --porcelain
+grimoire list --changes --json
 ```
-For example: `fix/special-chars-password-reset`, `fix/null-pricing-response`.
+
+Find any active change whose `manifest.md` `branch:` matches the current branch.
+
+| Current state | Bug relation | Action |
+|---------------|--------------|--------|
+| Protected branch (`main`/`master`/`develop`/`trunk`), clean tree | any | Create `fix/<short-description>` and switch |
+| Feature branch + active change on it | Bug is in the same feature/code path the change touches | **Stay on the branch.** Fix in place. The repro test and fix become part of that change |
+| Feature branch + active change on it | Bug is unrelated to that change | Ask the user. Default: stash/commit, switch to default branch, create `fix/...` off it |
+| Feature branch + no matching active change | any | Create `fix/<short-description>` off the default branch |
+| Dirty tree, no clear owner | any | Block. Commit, stash, or discard before proceeding |
+
+How to judge "related vs separate":
+- **Related** — the bug lives in files the in-flight change is modifying, or the bug is a direct consequence of the in-flight work (e.g. tests added by the change reveal it, the new code path crashes on an edge case). Fixing it on the same branch keeps the change coherent and the PR self-contained.
+- **Separate** — the bug exists on `main` independent of the in-flight change, touches unrelated code, or would still need to ship if the in-flight change were abandoned. Mixing it in pollutes the diff and the `Change:` trailer.
+
+When in doubt, ask the user one question: "This bug looks like it's [in / outside] the scope of the current `<branch>` work — fix it here, or branch off main?"
+
+Branch name format when creating new: `fix/<short-description>` (e.g. `fix/special-chars-password-reset`, `fix/null-pricing-response`).
 
 ### 6. Fix the Bug
-Now — and only now — modify production code:
+Now — and only now — modify production code. **Apply `../references/code-quality.md` while writing the fix, not after.** Inline rules:
+- Reuse existing utilities — grep / check the area doc before adding new helpers.
+- No new defensive guards inside the trust boundary — fix the real bug, don't paper over it with `if x is None` / `try-except`.
+- Specific names — no `data` / `result` / `temp` when a concrete name fits.
+- No new abstraction layer for a one-line bug fix.
+- Comments only for non-obvious *why* — one short note linking the bug + reproduction test is enough.
+
+Then:
 
 1. Make the smallest change that fixes the failing test
-2. Run the reproduction test — it should pass
-3. Run ALL existing tests — no regressions
-4. If the fix is more than a few lines, pause and consider whether the approach is the simplest one
+2. **Hallucination check:** Before running tests, verify every external function/method the fix calls actually exists: `search_graph(name_pattern="<name>")` for each new call. If not found: locate the correct function or stop and flag to user. (Full instructions in `../references/pattern-guard.md` Step 6. Skip if graph not indexed.)
+3. Run the reproduction test — it should pass
+4. Run ALL existing tests — no regressions
+5. If the fix is more than a few lines, pause and consider whether the approach is the simplest one
+6. **Code quality check:** Walk the seven-point checklist in `../references/code-quality.md` against every file you changed. Any fail → fix and re-run tests.
 
 **Escalation guard:** If the fix requires changes to more than 3 files, introduces new abstractions, modifies data models, or crosses service boundaries — STOP. This is not a bug fix, it's a change that needs design. Tell the user: "This fix is larger than a typical bug fix. I recommend routing to `grimoire-draft` to handle this as a proper change with specs and a plan." The user can override.
 
@@ -120,7 +152,7 @@ After the fix, generate a checklist for testers to verify the fix and check for
 3. **Generate the checklist:**
 ```markdown
 ## Verification Checklist: <bug-id>
-Fix branch: `fix/<name>`
+Branch: `<current-branch>` (new `fix/...` branch, or the in-flight feature branch if fixed in place)
 
 ### Original Bug
 - [ ] Reproduce the original steps: <steps>
@@ -149,12 +181,19 @@ Report to the user:
 - **Performance issues** — these usually need profiling, not a repro test. Handle directly.
 - **Configuration errors** — wrong env vars, missing dependencies, bad setup. Just fix the config.
 
+## References
+
+**Before writing the fix**, read both:
+- `../references/code-quality.md` — anti-slop rules to apply *while writing*: reuse before write, trust callers, names reveal intent, branching budget, function size, no premature abstraction, comments only for non-obvious why. Includes a seven-point quality gate to run before declaring the fix done.
+- `../references/pattern-guard.md` Step 6 only — after writing the fix, verify every new external function call exists in the graph via `search_graph`. Skip the full pattern brief (over-constrains bug fixes). Skip entirely if graph not indexed.
+
 ## Important
 - **Reproduce before you fix.** No exceptions. If you can't reproduce it, you don't understand it, and your fix is a guess.
 - **Small fixes only.** If the bug fix requires significant architectural changes, it's not a bug fix — route to `grimoire-draft` for a proper change.
 - **Don't over-document.** The test is the documentation. A one-line comment in the test explaining the bug is enough. Don't create tracking files, bug reports, or manifests for a bug fix.
 - **The feature file is truth.** If a scenario describes behavior the user now says is wrong, that's a spec change, not a bug. Handle it through `grimoire-draft`.
 - **One bug, one fix.** Don't bundle "while I'm in here" improvements with a bug fix. Fix the bug, nothing more.
+- **Don't reflexively branch.** A bug related to in-flight work belongs on the in-flight branch — splitting it into a separate PR fragments the change and breaks the `Change:` trailer audit trail. Branch only when the bug is genuinely a separate concern. See step 5.
 
 ## Done
 When the bug is fixed, tests pass (reproduction + regression), and the summary is presented, the workflow is complete. Suggest `grimoire-commit` for the fix commit.

package/skills/grimoire-commit/SKILL.md

@@ -19,7 +19,8 @@ Write a commit message from staged changes and active grimoire context. Never au
 ## Routing
 - No changes to commit → nothing to do
 - Want to create a PR → `grimoire-pr` (commit first, then PR)
-- Want to review changes before committing → show the diff first
+- Want a multi-persona review of the staged diff before committing → `grimoire-precommit-review`
+- Just want to eyeball the diff → show the diff first
 
 ## Workflow
 
@@ -65,7 +66,7 @@ If `commit_style` in config is anything else, read it as a format hint and adapt
 - If multiple logical changes are staged, suggest splitting into separate commits
 
 ### 5. Git Trailers (mandatory for audit trail)
-When a grimoire change is active, the commit **MUST** include `Change:` as a git trailer. This is what makes `grimoire trace` and `grimoire log` work — without it, the commit is invisible to the audit trail.
+When a grimoire change is active, the commit **MUST** include `Change:` as a git trailer. This git-native anchor links the commit to its change — `grimoire trace` and `git log --grep "Change: <id>"` both rely on it. Without it, the commit is invisible to the audit trail.
 
 ```
 Change: add-2fa-login

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 scenarios as a **design artifact** at `.grimoire/changes/<change-id>/designs/scenarios.feature` (a proposal, not the live baseline). One Scenario per (component × state), Given / When / Then grounded in the design. `grimoire-draft` writes the user-approved scenarios live into `features/` — design does not edit the live baseline directly. Every proposed scenario must still pass draft's feature admission test (external actor, observable, domain language).
+
+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 `.gitignore`)
+- 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 `.gitignore`.** Any scan (component inventory, brand lint) must skip vendored, generated, and version-control-ignored paths.
+- **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`.