Produces the smallest useful handoff for the next step — not an implementation
spec. grill-with-docs will challenge the plan, sharpen domain terms, update
GLOSSARY.md, and offer ADRs only for hard decisions.
Output contract
Final prompts use this shape:
Project:
[Full Project Matrix code, repo, path, or context. Use one line.]
What is needed:
[The change to make. One short paragraph or 2-4 bullets.]
Why it is needed: [The problem, user pain, business reason, or workflow gap — so grill-with-docs can challenge tradeoffs, not just wording — and what happens if nothing is built.]
Expected end result: [Observable done state. Prefer user-visible behavior, passing checks, or a demo flow; seeds the later acceptance criteria. Name the empty, loading, error, and recovery behavior, each role that sees it, and one thing that must not happen.]
Known limits: [Hard constraints, non-goals, compatibility needs, or exclusions already known. When intake was split, list the deferred slices as explicit non-goals. Always include the zero-attribution rule.]
Open questions: [Conditional. Real unresolved questions for grill-with-docs to attack.]
The first five sections are always present; omit `Open questions` when none remain.
## Rules
Zero attribution: never add or leave co-author, AI, or tool attribution in any output. Include this rule in the prompt's `Known limits`.
### Intake and inference
- Start from free-form intake. Infer first; ask only when `What is needed` is
unclear or project/context cannot be inferred safely.
- Use repo evidence when cheap: Project Matrix, cwd, `GLOSSARY.md`,
`GLOSSARY-MAP.md`, and ADR names. Do not run a broad code scan by default.
### Scope and slicing
- Before drafting, apply the fog test: can you state the destination in one
line *and* name every open decision as a sharp question, right now? If not,
stop and suggest `/wayfinder` — it charts those decisions and resolves them
one per session. Do not write a PR-sized prompt for foggy
work. Fog, not size, is the test: a large mechanical change with nothing left
to decide is not fog.
- Default to one thin vertical slice, small enough to review and merge
independently. Broad intake gets split: draft this prompt for slice 1 only;
`Known limits` records the deferred slices. A prompt that would force a very
long grilling session → ask to split scope before finalizing; user away →
split it yourself and note the split at the top of the response.
- When the user intends parallel agent threads, split slices to minimize
shared-file coupling.
### Context and evidence
- Use the full Project Matrix code verbatim whenever one exists. Never
abbreviate project codes or invent shorthand.
- Reference existing files/modules/seams when known, and keep "reuse existing
seam vs create new seam" under `Open questions` explicitly — it is how
duplicate logic gets prevented. When cheap search finds no existing seam,
say which terms were searched.
- Include only non-obvious context: constraints, architecture quirks, and
domain rules the model cannot infer cheaply from repo scans. Omit stack
facts the code already shows.
- Dependency internals central and unclear → suggest fetching targeted source
(e.g. `opensrc`) as a follow-up context step before deep grilling.
- Keep domain words intact. Ground candidate definitions in evidence and use
the approval flow below; unresolved definitions belong to `grill-with-docs`.
### Questions and output discipline
- Do not create `Domain terms`, `Decisions`, `Dependents`, `Risks`,
`Doc anchors`, `Integration`, `Constraints`, or `Acceptance` sections. Fold
useful facts into the six contract sections; user-stated hard decisions go
under `Known limits`.
- All unclear decisions land under `Open questions`; ungrillable ones ("needs
to feel/see it") also route to `/handoff` + `/prototype` before deep grilling
continues.
- Keep `Open questions` to the highest-leverage unknowns (usually 1-5). Drop
trivia that can be decided during implementation.
- A vague answer to a sharp question ("as fast as possible", "all users") is
not an answer — ask once for a number or a named segment; still vague →
park it under `Open questions` as written.
- Do not implement the feature, create a spec, or edit ADRs. `GLOSSARY.md`
changes happen only through the approved candidate-terms flow below.
- Keep the final prompt spartan, direct, plain English — it is a generated
artifact, never compressed shorthand.
## Candidate context terms
Only when cheap repo evidence or user-requested exploration reveals domain
terms missing from or stale in `GLOSSARY.md` — never run extra exploration just
to fill this. The shared flow — what qualifies, presentation, the
away-fallback, applying approvals — lives in
[`references/context-terms.md`](references/context-terms.md). Show candidates
before finalizing the prompt, apply only approved updates, and report the
edited path before saving. Terms still needing review stay under
`Open questions`.
## Agent use
Sub-agents: dispatch local lanes automatically for independent work — never cloud agents; announce the lane count at dispatch and report each lane as it completes. Lanes are for fast, independent context checks only — no worker agents, no code edits.
## Final output
1. Draft the final prompt.
2. For non-trivial or inferred prompts, show it once for correction, listing
inferred facts (project, slice boundary, end result) separately from what
the user stated. User away → save as drafted and note at the top that it
is unconfirmed.
3. If candidate context terms were found, run the shared approval flow.
4. Verify the pre-save checklist and save to the path below, then re-open the
saved file and confirm sections and path match the approved draft, or the
explicitly unconfirmed draft when the user is away, before
reporting.
5. Add only:
```markdown
Context updated: <relative GLOSSARY.md path> [only if edited]
Saved to: <relative path written>
Next: pass this final prompt to the `grill-with-docs` skill.
Suggested next skills (optional):
- /grill-with-docs: challenge assumptions, sharpen domain terms, and confirm decisions.
- /handoff + /prototype: when open questions are ungrillable and need a higher-fidelity spike.
- /to-spec: if this needs a formal spec (PRD) after grilling.
File output
Path
<artifacts-root>/specs/prompts/NNNN-<feature-slug>-prompt.md
Resolve <artifacts-root>: the *.code-workspace directory if one exists, else the per-context root (GLOSSARY-MAP.md at repo root; legacy CONTEXT-MAP.md), else the repo root.
NNNN— scan<artifacts-root>/specs/adr/andspecs/prompts/for the highest existing four-digit number and increment. This avoids numbers occupied when the prompt is created. ADRs have an independent sequence and may later reuse a prompt number; the recorded prompt path is the link.<feature-slug>— kebab-case fromWhat is needed, max 4 words, ASCII.-prompt— fixed suffix marking the artifact type.
Conflict handling
- Create
specs/prompts/lazily. Never overwrite a number already used by another artifact. Never delete unrelated files. - A prior same-slug prompt counts as hand-edited when git shows commits or working-tree changes to it that this session didn't make; if git can't tell (untracked file), assume hand-edited.
- A same-slug prompt created in this session and unchanged since → update in place. Hand-edited → show the diff and ask: overwrite, new numbered revision, or abort. If the user is away, write a new numbered revision — never overwrite hand edits unconfirmed.
File body
Write exactly the final prompt body — no preface, no generated-by header —
drop-in usable as input to grill-with-docs.
Pre-save checklist
- Only the six allowed section headers appear, in contract order
-
Project:names the full Project Matrix code verbatim (when one exists) - For a new file,
NNNNunique acrossspecs/adr/andspecs/prompts/; an in-place update retains its own number; slug ≤ 4 words, kebab-case ASCII,-promptsuffix - Split intake: deferred slices recorded under
Known limits; the zero-attribution rule is present - No placeholder text (
TBD,TODO,[...]) remains, and no two sections contradict each other - File body is the prompt only — drop-in, no preface