Grill With Docs

Run a /grilling session, using the /domain-modeling skill.

DECISIONS.md Format

A decision ledger records the resolved, implementation-relevant answers from grilling so they survive to-prd and to-issues intact instead of being softened into prose. It is the feature-level source of truth CONTEXT.md is not: the glossary says what a word means, DESIGN.md what a screen looks like, an ADR why a hard trade-off was made — the ledger says what the feature must do, verbatim.

One ledger per feature/plan, created lazily during grilling and committed. Lives under docs/decisions/ (or the context's own docs/decisions/ in a multi-context repo), parallel to docs/adr/.

Structure

# {Feature} — Decisions

Resolved, implementation-relevant answers from grilling. Each record is the
source of truth for downstream work; `to-prd` and `to-issues` cover every one.

## D1 — Tabs survive restart

**Resolved:** Every open tab must survive a restart with its identity and order unchanged; tabs are never collapsed into one session.
**Requirement:** On restart, the set, identity, and order of open tabs match the pre-restart state exactly.
**Constraints:** No tab merging. Order is preserved, not just membership.

## D2 — Retry preserves prior state

**Resolved:** A failed message can be retried without clearing prior messages or unsent input.
**Requirement:** Retrying a failed send leaves earlier messages and any draft input untouched.
**Constraints:** Retry is non-destructive — never clears the thread or the composer.

Rules

• Implementation-relevant answers only. Constraints, negative requirements, edge cases, numeric defaults, ordering decisions — the precise things prose softens. Glossary terms go in CONTEXT.md, visual conventions in DESIGN.md, trade-off rationale in an ADR.
• Keep the answer verbatim. Resolved is the user's exact decision; Requirement is its testable restatement, not a replacement. Don't generalize "identity and order unchanged" into "persist sessions".
• Stable IDs. Number records D1, D2… in resolution order and never renumber — downstream skills reference them.
• Revise in place. If an answer changes, edit its record and keep the ID, so artifacts built on the old version are visibly out of date.

DESIGN.md Format

DESIGN.md is the visual glossary — the settled conventions of the project's design system. It is to design what CONTEXT.md is to the domain: what IS, not why.

If the repo already keeps a design-system doc, follow its structure and update that file instead. The shape below is a minimal fallback when none exists.

Structure

# {Project} Design

{One or two sentences on the product's visual lane and who it's for.}

## Color

**Primary**: `#2563eb` — actions, links, focus
**Surface**: `#ffffff` background, `#1a1a1a` text

## Type

**Body**: Inter, 16/1.5
**Headings**: Inter, 600

## Layout

**Primary actions**: sticky bottom bar on mobile, top-right on desktop
**Forms**: single column, label-above-field

## Components

**Button**: solid (primary), outline (secondary), ghost (tertiary)

Rules

• Settled conventions only. A line earns its place once a decision is final, not while it's still being debated.
• No rationale. The why behind a hard visual trade-off goes in an ADR. DESIGN.md records the rule, not the argument for it.
• Be opinionated. When two patterns compete for the same job, pick one and write that down — the same way CONTEXT.md picks one term and lists the rest under _Avoid_.
• Group under subheadings (Color, Type, Layout, Components…) only as they fill out. A short flat list is fine early on.