---
name: shape
description: Use when turning a fuzzy idea, a position to stress-test, or a set of already-clear requirements into a written spec — grill mode tests a position, explore mode is open-ended, synthesis mode drafts straight from clear requirements. Invoke via route or explicit command.
---

# shape

Turns an idea into a spec file. Three entry modes reach the same exit: a written
spec, self-reviewed, waiting on approval. Route hands you a mode directly
(`shape-synthesis`, `shape-grill`, `shape-explore`, `shape-wayfinder`); a request
that names a mode itself — "grill me", "requirements are settled" — picks the mode
the same way.

## Picking a mode, if not already told

- A position exists and needs stress-testing → grill.
- Open-ended, no position yet → explore.
- Requirements are already clear enough to state → synthesis.
- The topic won't resolve in one sitting → wayfinder (below).

## Grill

Stress-tests a position someone already holds.

1. Build a decision tree of the open questions, ordered by dependency: which
   decisions block which others. An early answer can change what the later
   questions even are.
2. Split each node into a fact or a decision. A fact is checkable — confirm it
   (read the code, ask one direct question) and move on. A decision is a choice
   among options — that gets the interview treatment below.
3. Ask one decision at a time, in dependency order. Never put a list of questions
   in one turn — the position gets stress-tested one decision at a time.
4. Every question carries a concrete recommendation: state your pick and the
   one-line reason before asking, then let the user confirm, override, or answer
   differently. A bare question with no stance is not a grill question.

   ```
   Next: does "reviews" mean buyer reviews of a storefront, or reviews of the
   platform itself? Recommend buyer reviews of a storefront — that's the noun
   already in use, and "platform reviews" isn't a stated need yet.
   ```

5. The moment a decision confirms, append its line to memory-progress.md —
   immediately, not batched for later. An interview is exactly the kind of work a
   session dies mid-way through; a decision that only lives in the conversation
   dies with it.

   ```
   DECISION [<topic>] <question> → <choice>
   ```

6. Keep going until every branch of the tree is resolved or explicitly deferred
   with a named owner. "This got hard, let's stop" is not an exit — resolved or
   deferred-with-an-owner are the only two ways out of grill. When you defer a
   branch to a later cycle, append it to the backlog per /galdr:backlog
   (skills/backlog/SKILL.md) — don't restate the format here.
7. Once the tree is exhausted, continue to Synthesis.

## Explore

Open-ended: no position exists yet to test.

1. Read the project's context first — CLAUDE.md, memory.md, the existing code —
   before proposing anything. An approach that ignores what's already there gets
   rejected on the first read anyway.
2. If the request spans more than one subsystem, decompose the scope: name each
   subsystem's slice of the question separately before designing any of them.
3. For each slice, present 2-3 approaches with a recommendation stated first, not
   a neutral list, before going into design detail: the pick and why, then the
   alternatives and their tradeoffs.
4. Once a direction is picked for a slice, any open question left in it gets the
   same treatment as grill: one at a time, recommendation first.
5. Continue to Synthesis.

## Synthesis

The exit every mode reaches, and a mode in its own right.

- Entered directly (`shape-synthesis`, or the requirements are already stated as
  clear): skip the interview entirely. Do not ask a clarifying question — the
  request already said what's needed. Go straight to the spec draft.
- Arrived here after grill or explore: the interview already happened; there is
  nothing left to skip, just write.

Write the spec to `docs/specs/YYYY-MM-DD-<topic>.md` in the target repo. Near the
header, carry a one-line `Lifecycle status:` field. It moves through four states
over the spec's life — `shaped → planned → in-progress → shipped` — and shape
sets it to `shaped` when it writes the spec.

- **Goal** — what this spec is for, one paragraph.
- **Non-goals** — what's explicitly out of scope, so it can't drift back in later.
- **Constraints** — project-wide rules every task must obey (style, consent,
  cross-repo invariants). The plan skill copies this section forward verbatim, so
  write it as rules, not prose.
- **Decision log** — every decision reached (grill/explore) or assumed (direct
  synthesis), as a table: `# | Decision | Choice`.
- **Acceptance criteria** — stated per future wave, so the downstream `plan` skill
  has something concrete to check tasks against.
- **Roles touched** — one line, `**Roles touched:** <comma-separated role names>` or
  `**Roles touched:** none`. Names are roles cited from the target repo's
  `docs/agents/roles-and-journeys.md`, if that doc exists; if the repo has no such
  doc, the field is always `none`.

### 5-point self-review

Before showing the spec, check it against these five and fix inline — don't flag
a problem and leave it for later:

1. **Placeholders** — any "TBD", "handle edge cases", "similar to X"? Replace with
   the actual content.
2. **Contradictions** — do any two sections disagree with each other? Reconcile
   them.
3. **Scope** — does the spec match what was actually asked, no more and no less?
   Trim anything that crept in.
4. **Ambiguity** — could two different readers build this two different ways?
   Sharpen the wording until one reading survives.
5. **Roles drift** — check what "Roles touched" ended up being:
   - No existing role named (the field is `none`, or names only roles absent from
     `docs/agents/roles-and-journeys.md`): this point is done — the review is the
     original four points, unchanged.
   - An existing role is named and the spec's claims about that role's
     capabilities/boundaries match the doc's `**Capabilities:**` /
     `**Boundaries:**` lines for it: passes silently, same as any other point that
     finds nothing wrong.
   - An existing role is named and the spec's claims conflict with the doc (the
     spec assumes a capability the doc's `**Boundaries:**` rules out, or contradicts
     a stated `**Capabilities:**` line): stop synthesis before the spec is shown for
     approval, and tell the user to either fix the spec to match the doc, or run
     `setup`'s refresh to update the doc first — then resume. Never fix this by
     editing `docs/agents/roles-and-journeys.md` yourself in-session; that file is
     only ever written by `setup`.

On a session with the Workflow tool: after the inline fixes above, dispatch one
independent reviewer at the `spec-review` binding from the repo's
`docs/agents/galdr.md` §Models — an activity row that names a tier, resolved through
that tier's own binding. Input: the draft spec and its decision log. Return: findings
against the same five points above. Fix its findings inline, the same way the five
points are fixed, before the spec is shown for approval — the reviewer is a second
opinion from a context that did not write the spec, which is the point.

On any runtime without the Workflow tool: skip the dispatch. The self-review above is
the whole review, unchanged.

### Hard gate

No implementation action — no code, no plan file, no wave dispatch — happens
until the user has approved this spec. This is a hard rule, not a preference: an
unapproved spec is a draft, and drafts don't get built.

## Wayfinder

When a topic won't reach a spec in one session — too many open branches, or the
session runs out before the tree is exhausted — load `references/wayfinder.md`.
It covers the multi-session fog map: what to record, what never to record, and
how the map closes back out into a spec.

## Notes

- A memory-progress.md decision line and the spec's Decision log table are not
  the same artifact: the line is written the moment a decision lands, mid-
  interview; the table is the same decisions, collected, at the end.
- Facts and decisions differ in treatment, not in stakes — a wrongly assumed fact
  is still a spec bug, it just didn't need an interview to catch.
