@kiwidata/grimoire 0.1.3 → 0.1.4

package/skills/references/design-heuristics.md

@@ -0,0 +1,138 @@
+# Design Heuristics Reference
+
+Loaded by `grimoire-design` (variant generation, state enumeration) and review skills running visual-fidelity checks. A compact checklist of the heuristics, laws, and minimum-viable rules an AI agent or reviewer should know before generating or critiquing UI.
+
+The goal is **calibration**, not exhaustiveness. Every heuristic below has a trigger condition — if the trigger doesn't apply to the change under review, skip it. Heuristics fired indiscriminately become noise; the materiality gate from `./review-personas.md` §2 applies here too.
+
+---
+
+## 1. Nielsen's 10 Usability Heuristics
+
+The classic baseline. Each line: heuristic, one-line definition, trigger.
+
+| # | Heuristic | Trigger (when it applies) |
+|---|---|---|
+| 1 | **Visibility of system status** — keep users informed of what's happening | Any async action; loading > 1s; multi-step flows |
+| 2 | **Match between system and real world** — speak the user's language | Naming any concept users will see; error messages |
+| 3 | **User control and freedom** — escape hatches, undo, cancel | Any destructive action; multi-step wizards; modal dialogs |
+| 4 | **Consistency and standards** — follow platform and product conventions | New component where a similar one exists; reinventing standard controls |
+| 5 | **Error prevention** — design out errors before they happen | Forms; destructive actions; irreversible operations |
+| 6 | **Recognition rather than recall** — show options, don't make users remember | Multi-step flows; command palettes; settings spread across pages |
+| 7 | **Flexibility and efficiency of use** — accelerators for power users | Frequently-used flows; keyboard shortcuts; bulk operations |
+| 8 | **Aesthetic and minimalist design** — every extra element competes for attention | Crowded UI; multiple CTAs; decorative elements without purpose |
+| 9 | **Help users recognize, diagnose, and recover from errors** — plain language, named cause, suggested fix | Every error path; form validation; API failures |
+| 10 | **Help and documentation** — searchable, task-focused, concrete steps | Onboarding; complex features; first-use moments |
+
+Findings cite the heuristic by number: "Violates H#9 — error message names no recovery path."
+
+---
+
+## 2. WCAG 2.2 AA Quick Reference
+
+The minimum bar for any web or mobile UI claiming accessibility. Numbers are AA-level; AAA is stricter and rarely required outside regulated domains.
+
+### Contrast
+
+- **Body text vs background**: 4.5:1 minimum
+- **Large text** (≥18pt regular or ≥14pt bold) vs background: 3:1 minimum
+- **UI components** (buttons, form borders, focus indicators, icons that convey meaning) vs adjacent colors: 3:1 minimum
+- **Tools**: check contrast with a contrast checker; pseudo-disabled or low-emphasis text still must meet 3:1 if it carries meaning
+
+### Target size
+
+- **Minimum interactive target**: 24×24 CSS pixels (WCAG 2.2 added this — was 44×44 in iOS HIG, 48dp in Material)
+- **Spacing**: targets smaller than 24×24 must have at least 24px of clear space around them
+- **Exceptions**: inline links in body text; user-agent-controlled (native `<select>`); essential controls where size is dictated by the underlying content
+
+### Focus
+
+- Focus indicator must be **visible** on every interactive element
+- Focus order must match visual reading order (left-to-right, top-to-bottom for LTR; reverse for RTL)
+- No focus traps except in modal dialogs (where trap must be escapable via Esc)
+
+### Forms
+
+- Every input has a programmatically-associated `<label>`
+- Required fields are marked beyond color (asterisk, "required" text)
+- Errors are announced to screen readers (live region or focus shift) and named in text near the field
+
+### Motion
+
+- No content that flashes >3 times per second (seizure risk)
+- Respect `prefers-reduced-motion`; provide a non-animated alternative for essential motion
+
+---
+
+## 3. Deceptive Patterns (Brignull Taxonomy)
+
+Dark patterns to **avoid** in the design, and to **flag** during review. Source: deceptive.design (Harry Brignull's taxonomy). Findings here are usually blockers — the project's stage and audience determine severity, but never normalize them.
+
+### Patterns
+
+- **Roach motel** — easy to get into, hard to get out (e.g. one-click signup, multi-step cancel flow). Trigger: review any sign-up / subscription / account-deletion flow.
+- **Confirmshaming** — guilt the user out of opting out (e.g. "No thanks, I hate saving money"). Trigger: any opt-out / decline button.
+- **Sneak into basket** — adds items the user did not select (e.g. donation pre-checked, add-on default-enabled at checkout). Trigger: any cart / order-review flow.
+- **Hidden costs** — final price revealed only at last step (fees, shipping, taxes appear at checkout). Trigger: any purchase / pricing flow.
+- **Forced continuity** — free trial silently rolls to paid without notice. Trigger: any trial / subscription onboarding.
+- **Disguised ads** — ads styled to look like content or controls. Trigger: any ad-supported UI.
+- **Friend spam** — uses contact list to send unsolicited invites under the user's name. Trigger: any contact-import / referral flow.
+- **Privacy zuckering** — tricks users into sharing more data than intended. Trigger: any consent flow, permission prompt, default privacy setting.
+- **Misdirection** — uses visual emphasis to distract from a deceptive choice. Trigger: A/B-tested CTA layouts; "recommended" defaults.
+- **Trick questions** — confusingly-worded questions where the obvious answer is the opposite of intent. Trigger: any settings toggle, consent checkbox.
+
+### Reviewer rule
+
+For each pattern, ask: "If a regulator (FTC, CMA, EU DSA enforcement) saw this flow tomorrow, would the company defend it or change it?" If the answer is "change it," the pattern is a blocker.
+
+---
+
+## 4. Cognitive Laws (apply when relevant)
+
+Named laws that compress empirical findings about human-UI interaction. Each one is a single sentence plus when to apply it.
+
+- **Fitts's Law** — time to acquire a target is a function of distance and size. *Apply when*: placing primary actions (put them where the cursor / thumb already is, make them large); reviewing dense toolbars.
+- **Hick's Law** — decision time grows with the log of the number of choices. *Apply when*: menus with >7 items; settings pages; onboarding step sequences. Reduce, group, or progressively disclose.
+- **Miller's 7±2** — short-term memory holds roughly 7 items. *Apply when*: navigation breadth (top-level menu items), groups within a form, items shown without scrolling. Chunk when over the limit.
+- **Jakob's Law** — users spend most of their time on other sites. *Apply when*: inventing a new pattern where a standard one exists. Most users expect the search box top-right, the logo top-left, the cart icon top-right, the sign-out under a profile menu. Deviate only with reason.
+- **Doherty Threshold** — productivity soars when system response is under 400ms. *Apply when*: any interactive action — feedback within 100ms, completion under 400ms where possible, skeleton/loader for anything longer.
+- **Tesler's Law** — every system has irreducible complexity; the question is who absorbs it (user, designer, engineer). *Apply when*: simplifying — never delete complexity, only shift it. Don't push to users what the system can decide.
+- **Postel's Law (UI variant)** — be liberal in what you accept, conservative in what you produce. *Apply when*: form inputs (accept "(555) 123-4567" or "5551234567"); display formatting (canonicalize on output).
+
+---
+
+## 5. Empty / Error / Loading State Rules
+
+For every interactive component, the design must address these states. Missing states are the single most common omission in AI-generated UI; treat them as a checklist.
+
+### Required states (all interactive components)
+
+| State | Minimum-viable handling |
+|---|---|
+| **Default** | The component at rest, ready for input or display. |
+| **Loading** | Visible feedback if action takes >300ms. Skeleton, spinner, or progress bar. Never a blank screen. |
+| **Empty** | Component is visible but holds no data. Show a brief explanation of what would normally appear and how to populate it (the "zero state"). Never silent. |
+| **Error** | Component cannot fulfill its job. Show what went wrong in plain language, with a concrete recovery action (retry, contact, alternative path). Never just "An error occurred." |
+
+### Conditional states (apply per component type)
+
+| State | Applies when | Handling |
+|---|---|---|
+| **Success** | Action has a meaningful completed state (form submit, file upload) | Brief acknowledgement + next step. No celebration confetti unless the action genuinely warrants it. |
+| **Disabled** | Action is unavailable in the current context | Visually muted; tooltip or label explains *why* it's disabled and what would enable it. Never disable without explanation. |
+| **Read-only** | Component shows data the user can't edit | Visually distinct from editable (no input border, no cursor); copy-to-clipboard if data is referenceable. |
+| **Over-limit** | Input has a max length, count, or quota | Live counter visible at ≥80% capacity; clear feedback when limit is hit and what the user can do (delete, upgrade). |
+| **Partial / degraded** | Component depends on a service that's slow or down | Show what's available + named outage explanation; do not pretend everything is fine. |
+
+### Reviewer rule
+
+For each interactive component in the design, walk the four required states. If any is missing, that's a finding — severity depends on the criticality of the component. Login forms missing an error state = blocker. Footer-link list missing a loading state = drop (loading isn't a thing for static content).
+
+---
+
+## Notes for AI Agents Generating UI
+
+- Default to **fewer choices** (Hick) and **standard patterns** (Jakob). The marginal cost of inventing a novel layout almost never beats the marginal cost of users not recognizing it.
+- Default to **visible feedback within 100ms** for any interaction. Even a focus-ring change counts.
+- Default to **calm, blameless error messages** with a named recovery path. "Couldn't reach the server. Retry?" beats "An error occurred."
+- When in doubt about contrast, check; do not estimate. AI-generated palettes routinely miss 4.5:1.
+- When in doubt about target size, go to 44×44. The 24×24 minimum is the floor, not the goal.

package/skills/references/design-input-formats.md

@@ -0,0 +1,190 @@
+# Design Input Formats Reference
+
+Loaded by `grimoire-design` (variant generation) and `grimoire-draft` (Figma snapshot consumption). Defines the input sources grimoire-design can consume, in precedence order, and the fallbacks when none are available.
+
+The precedence is **Figma MCP → other MCPs → static HTML → ASCII**. Higher-fidelity inputs win; lower-fidelity outputs are emitted only when nothing better is available. See ADR-0018 for the Figma-primary decision.
+
+---
+
+## 1. Figma MCP (primary)
+
+When `project.design_tool.mcp` is configured with the Figma server, grimoire-design queries Figma directly for frame data and component metadata.
+
+### Setup
+
+Configured at `grimoire init` time. Stored as:
+
+```yaml
+project:
+  design_tool:
+    name: figma
+    mcp:
+      name: figma-developer
+      command: npx
+      args: ["-y", "figma-developer-mcp@latest"]
+```
+
+The access token is **never** written to config. The MCP server reads `FIGMA_ACCESS_TOKEN` from the shell environment.
+
+### What to query
+
+- **Frame data** — given a Figma URL or node ID, fetch frame structure (children, sizes, positions). Use for converting a designed screen into a Gherkin scenario set.
+- **Variables** — Figma Variables → DTCG tokens. If the project's `.grimoire/brand/tokens.json` is missing and Figma Variables exist, offer to seed `tokens.json` from them via Tokens Studio export.
+- **Components** — query the file's components inventory. Cross-reference with `.grimoire/docs/components.md` to detect drift or net-new components.
+
+### Cache
+
+When grimoire-design or grimoire-draft fetches frame data, cache the response at `.grimoire/changes/<change-id>/designs/figma-snapshot.json`. Reuse cache for subsequent skills on the same change-id; refresh on user request.
+
+### Graceful degradation
+
+If the MCP is configured but the call fails (network, expired token, missing file permission):
+- Emit one-line "Figma MCP unreachable — `<error>`. Falling back to static HTML."
+- Continue with HTML fallback (§4 below). Do not crash the workflow.
+
+---
+
+## 2. shadcn-ui MCP (optional)
+
+When the project uses shadcn-ui (detected via `components.json` or `@radix-ui/*` deps) and the shadcn MCP is installed, grimoire-design can fetch component source by name.
+
+### What to query
+
+- **Component fetch** — given a component name (e.g. `Button`, `DialogClose`), retrieve the canonical source. Use when generating variants to ensure they reference the actual project component shape, not a generic one.
+- **Variants list** — enumerate variants the project's component library exposes (e.g. `Button` → `default`, `destructive`, `ghost`, `outline`).
+
+### Activation
+
+Only engaged when `.grimoire/docs/components.md` lists shadcn-ui as the component library. Otherwise skip.
+
+---
+
+## 3. Storybook MCP (optional)
+
+When the project has Storybook (`.storybook/` directory, `*.stories.*` files), the Storybook MCP can extract story metadata.
+
+### What to query
+
+- **Story enumeration** — list all stories with their args, controls, and parameters. Use to derive states per component (default / loading / empty / error).
+- **Story rendering** — for a given story, fetch the rendered HTML snapshot (if Storybook is running locally with the addon installed).
+
+### Use case
+
+The richest source of per-component state coverage. When available, prefer over manually enumerating states in §9 of the grimoire-design workflow.
+
+---
+
+## 4. design-extract (optional)
+
+URL-to-tokens scraper. Given a live site URL, produces DTCG-format `tokens.json`.
+
+### When to use
+
+- Bootstrapping `tokens.json` from an existing site (e.g. migrating to grimoire mid-project)
+- Sanity-checking that hand-edited tokens match what's actually on a deployed page
+
+### Output
+
+Writes to stdout or a path; pipe to `.grimoire/brand/tokens.json` (or to a temp file for diffing).
+
+### Limitations
+
+- Computed styles only — no semantic grouping. Output is flat; group manually.
+- Misses tokens not present on the scanned page (e.g. error states never rendered).
+
+---
+
+## 5. HTML Fallback
+
+When no MCP is available, grimoire-design emits self-contained static HTML files at `.grimoire/changes/<change-id>/designs/variant-{n}.html`.
+
+### Structure
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>Variant 1 — <change-id></title>
+  <style>
+    :root {
+      /* Brand tokens injected from .grimoire/brand/tokens.json */
+      --color-primary: #0066ff;
+      --color-text: #111827;
+      --spacing-base: 8px;
+      --font-family-base: Inter, sans-serif;
+    }
+    body { font-family: var(--font-family-base); color: var(--color-text); }
+    .button-primary { background: var(--color-primary); padding: var(--spacing-base); }
+    /* ... */
+  </style>
+</head>
+<body>
+  <main>
+    <!-- Variant markup -->
+  </main>
+</body>
+</html>
+```
+
+### Rules
+
+- **Self-contained** — no external CSS, no CDN scripts, no remote fonts. Designer opens the file directly; offline must work.
+- **CSS variables only** — every color, spacing, font value must reference a `--token` CSS variable defined in `:root`. The `:root` block is the bridge between `tokens.json` and rendered output.
+- **No JS** unless the variant is demonstrating an interaction that can't be shown statically. Prefer multiple HTML files showing each state over one file with JS state toggling.
+- **One file per variant** — `variant-1.html`, `variant-2.html`, `variant-3.html` by default. A `preview.html` file at the same level renders all variants × all states in a grid for side-by-side review.
+
+### Token referencing
+
+Generate the `:root` block by reading `.grimoire/brand/tokens.json` and emitting one CSS custom property per token. Mapping rule: `color.primary` → `--color-primary`, `font.family.base` → `--font-family-base`. Dot becomes hyphen, kebab-case throughout.
+
+If `tokens.json` is absent, emit neutral defaults (white background, system font, 8px spacing) and note in a top-of-file comment: `/* No brand tokens — using neutral defaults. Run grimoire-design --capture-brand. */`
+
+---
+
+## 6. ASCII Fallback
+
+For trivial scope (level 1-2 changes touching a single existing component), ASCII art in a markdown table is the right tier. Faster to author and read than HTML for low-stakes layout changes.
+
+### When to use
+
+- Single component, single state change
+- Pure layout reordering (no new visual treatment)
+- TUI surface (where HTML preview is irrelevant)
+- Quick sketch for a consult conversation, not a final spec
+
+### Convention
+
+```markdown
+## Variant 1 — login form, error state
+
+| Element        | Layout                              |
+|---             |---                                  |
+| Header         | [Logo]                  [Help link] |
+| Form           | Email:    [____________________]    |
+|                | Password: [____________________]    |
+|                | [!] Invalid credentials             |
+|                | [ Sign in ]      Forgot password?   |
+| Footer         | Terms · Privacy · v2.4              |
+```
+
+Use `[Element]` for interactive controls, `[!]` for error states, plain text for static labels. Markdown tables keep the structure readable in any viewer.
+
+### When NOT to use
+
+- Web or mobile surface with new visual treatment → use HTML
+- Multi-component or multi-state designs → ASCII collapses; use HTML grid
+- Anything a designer needs to react to visually → ASCII underspecifies
+
+---
+
+## Selection Rule (precedence)
+
+Grimoire-design picks the highest-fidelity output the environment supports:
+
+1. Figma MCP configured → render in Figma (no local artifact written)
+2. shadcn / Storybook MCP available + UI codebase detected → HTML using actual component source
+3. Otherwise → static HTML with brand-token CSS variables
+4. Override to ASCII only when scope is trivial OR surface is TUI
+
+User can override via conversational invocation: "use HTML" or "give me ASCII". The selection is a default, not a lock.

package/skills/references/pattern-guard.md

@@ -0,0 +1,180 @@
+# Pattern Guard Reference
+
+Loaded by `grimoire-apply` and `grimoire-bug`. Run **before writing the test** for each task — not after, not as a review pass. The goal is to write code that matches the codebase's established conventions the first time, rather than writing to generic patterns and fixing divergence later.
+
+This is not a quality checklist. It is a reconnaissance step: find out how this codebase already solves this class of problem, then write to that pattern.
+
+Requires `codebase-memory-mcp` indexed. If the graph is not available, skip this reference entirely and rely on `code-quality.md` alone.
+
+---
+
+## Run Before Each Task
+
+### Step 1 — Classify the code being written
+
+From the task description and feature file, identify what category of code this task produces:
+
+| Code type | Examples |
+|---|---|
+| `api_handler` | Route handler, view, controller, endpoint function |
+| `service` | Use case, interactor, domain service, business logic function |
+| `repository` | Data access, ORM query, store method, DAO |
+| `model` | ORM model, dataclass, schema, type definition |
+| `utility` | Helper, formatter, validator, parser |
+| `test` | Step definition, unit test, fixture, factory |
+| `middleware` | Auth, logging, rate-limiting, request transform |
+| `integration` | External API client, webhook handler, adapter |
+
+A task may touch multiple types — classify the primary one.
+
+### Step 1b — Reuse discovery
+
+Before finding peer patterns, ask: **does what I'm about to write already exist?**
+
+These are two different questions. Step 2 finds code to *pattern-match against*. This step finds code to *call instead of writing*.
+
+For each function, helper, or class the task requires, run both searches:
+
+**Semantic search** — find it by concept, not by name:
+```
+search_graph(semantic_query=["<primary_concept>", "<action_verb>", "<domain_noun>"])
+```
+Example: about to write something that formats a currency amount →
+```
+search_graph(semantic_query=["format", "currency", "amount"])
+```
+This finds `render_price`, `display_amount`, `format_currency` — whatever name the codebase already uses.
+
+**Name-pattern search** — find it by likely prefix or suffix:
+```
+search_graph(name_pattern="(format_|_format|currency|amount|price)")
+```
+
+**Decision rules:**
+- Result does the job → **call it**. Do not re-implement.
+- Result almost fits → **use it directly**. Do not generalize it for a second case that doesn't exist yet.
+- Both searches return nothing usable → write new code and proceed to Step 2.
+
+**Log the outcome in the pattern brief** (Step 4): note which searches ran and what they found. If calling an existing function instead of writing new code, note it explicitly: `Reused format_currency from billing/utils.py — no new function needed.`
+
+Do not skip this step. Writing new code without a reuse search is the primary source of duplication in LLM-generated codebases. The semantic_query mode bridges vocabulary gaps — it finds "publish" when you search "send".
+
+### Step 2 — Find peer examples
+
+Use `search_graph` to find 3–5 existing functions/classes of the same type. Prefer the most established (oldest, least recently changed) — these are the modal pattern, not the recent drift.
+
+**Queries by code type:**
+
+```
+api_handler:   search_graph(label="Function", name_pattern="(handle|view|endpoint|get_|post_|put_|delete_|patch_)")
+service:       search_graph(label="Function", name_pattern="(service|use_case|create_|update_|delete_|process_)")
+repository:    search_graph(label="Function", name_pattern="(repo|get_by|find_by|list_|save_|delete_)")
+model:         search_graph(label="Class", name_pattern="(Model|Schema|DTO|Type|Entity)")
+utility:       search_graph(label="Function", name_pattern="(parse_|format_|validate_|convert_|build_)")
+test:          search_graph(label="Module", name_pattern="(test_|_test|spec|_spec|conftest|fixture)")
+middleware:    search_graph(label="Function", name_pattern="(middleware|guard|interceptor|filter|auth)")
+integration:   search_graph(label="Class", name_pattern="(Client|Adapter|Gateway|Connector|Webhook)")
+```
+
+If the query returns > 10 results, filter to the same area as the task's target file (check area docs or directory).
+
+Exclude files changed in the last 60 days from your sample — those may already be drifted. Use `git log --since="60 days ago" --name-only --format=` to get the recent list.
+
+If < 3 peers exist in the graph, skip the pattern brief — there's no established pattern yet. Write to `code-quality.md` rules and the feature spec only.
+
+### Step 3 — Extract the modal pattern
+
+`get_code_snippet(qualified_name)` for each peer. Read across all samples and identify:
+
+**Four critical seams** (these are the ones that cause architectural drift if broken):
+
+1. **Error handling** — Does this codebase raise exceptions or return result/error values at this layer? Do handlers catch specific exception types? Is there a central error handler or per-function handling?
+
+2. **Dependency access** — Are dependencies injected (constructor, function arg) or imported directly? Is there an established pattern (DI container, FastAPI `Depends`, Django `self.repository`, etc.)?
+
+3. **Abstraction depth** — Does this code type contain business logic, or does it delegate? (e.g., handlers should be thin, services should be thick — but check what *this* codebase actually does)
+
+4. **Return shape** — Dict? Typed dataclass/schema? Model instance? Tuple `(result, error)`? Pydantic model? Match exactly.
+
+**Three secondary seams** (style drift, not architecture):
+
+5. **Naming** — snake_case vs camelCase beyond language default, verb-first vs noun-first for functions, consistent abbreviation patterns
+
+6. **Test structure** — `pytest` fixtures vs factories vs inline setup? `unittest.mock` vs `pytest-mock`? Arrange/Act/Assert comments or no?
+
+7. **Import order / grouping** — stdlib → third-party → local? Relative vs absolute imports?
+
+### Step 4 — Write the pattern brief
+
+Produce a short, concrete brief of 5–8 rules derived from the samples. Not generic rules — rules for *this task in this codebase*. Example:
+
+```
+Pattern brief for: POST /invoices handler (api_handler)
+
+From 4 peers (billing/views.py, orders/views.py, customers/views.py, auth/views.py):
+
+1. Error handling: raise ValidationError / NotFound — do NOT return {"error": ...}. 
+   Central handler in middleware/errors.py converts exceptions to HTTP responses.
+2. Dependency: inject service via constructor arg — `def __init__(self, invoice_service: InvoiceService)`
+   Do NOT call InvoiceService() inline.
+3. Abstraction: handler validates request, calls one service method, serializes response.
+   No business logic in the handler.
+4. Return shape: return InvoiceSerializer(result).data with DRF Response — not a raw dict.
+5. Naming: method names are HTTP verb — `def post(self, request)` not `def create_invoice`.
+```
+
+This brief is your constraint set for this task. Apply it while writing — not as a review after.
+
+### Step 5 — Write to the brief
+
+When writing the test and production code for this task:
+
+- Apply the brief's rules as hard constraints, not suggestions
+- If the task spec conflicts with the brief (e.g., feature file implies a return shape the codebase doesn't use), flag it to the user before writing — don't silently choose one
+- If you must deviate from the brief (e.g., the brief's pattern won't work for this specific case), note the deviation inline with a comment explaining why, and add it to the handoff note
+
+### Step 6 — Verify called functions exist
+
+After writing production code, before running tests:
+
+Extract every external function/method call your new code makes (exclude stdlib and known third-party packages). For each:
+
+```
+search_graph(name_pattern="<function_name>")
+```
+
+If a called function is not found in the graph:
+- Check the import — is it an alias or renamed import?
+- Check for typos against similar names in the graph
+- If genuinely missing: **stop**. Do not call a function that doesn't exist. Either find the correct function via `search_graph` or flag to the user.
+
+This catches hallucinated API calls before they become broken tests.
+
+---
+
+## Pattern Brief Template
+
+```
+Pattern brief for: <task title> (<code_type>)
+
+From <N> peers (<file1>, <file2>, ...):
+
+1. Error handling: <what the peers do>
+2. Dependency: <injection pattern used>
+3. Abstraction: <what this layer does vs delegates>
+4. Return shape: <concrete type/shape>
+5. Naming: <any non-obvious conventions>
+[6. Test structure: <if this is a test task>]
+[7. Deviation noted: <if you must deviate, why>]
+```
+
+Write the brief into the task's handoff note in `tasks.md` so future sessions have it.
+
+---
+
+## When to Skip
+
+- Graph not indexed → skip entirely, use `code-quality.md` only
+- < 3 peers found → skip the brief, note "no established pattern yet"
+- Task is adding a new code type with no prior examples → skip the brief, note "first of this type"
+- Hotfix / bug task in `grimoire-bug` → run only Step 6 (hallucination check); skip the full brief to avoid over-constraining the fix