spec git:20260921.95d68f9A

Immutable. This exact content is served forever at /api/v1/blob/705cd5c510cb0726.

---
name: spec
description: Plan a requested codebase change or architecture decision. Use when planning is requested; do not implement code.
---

# Spec

Define the outcome, scope, constraints and sufficient acceptance evidence. Read
only instructions, code and prior decisions that can change this plan. Resolve
questions from available evidence before asking the user.

Choose the least durable artifact that the task needs:

- `direct`: objective, scope and check in the response; no file.
- `verified_single`: a bounded hypothesis/check loop for one writer.
- `light_spec`: an amendable `decisions/<slug>.md` for a material architectural
  decision. Reuse an existing decision record when it fits.
- `graph`: independent deliverables requiring durable coordination. Read
  [graph-planning.md](references/graph-planning.md) only for this mode.

Planning does not require running the intake CLI for a bounded edit. Do not
select graph because more models or workers happen to be available.

For substantial work, map each required outcome to observable evidence. Separate
optional ideas and exclusions. Define completion as meeting the current request,
not merely finishing implementation or obtaining a successful process exit.
Name any acceptance that cannot currently be observed.

For substantial plans or an explicit visual request, deliver a **PDF visual
summary** before implementation handoff, with a direct link to the actual PDF.
Use the bundled [visual brief](references/visual-brief.md) renderer and template;
it produces PDF plus self-contained HTML by default. HTML alone, screenshots or
instructions to print are not a completed PDF delivery. If export is blocked,
report that explicitly; use HTML-only only when the user requests that exception.
Inspect the rendered PDF for pagination, legibility and missing content. Keep
Mermaid flow/sequence diagrams in the canonical spec when they explain the
change; render them into the same offline PDF as the decisions and checks.
Distinguish proposals from execution evidence. Trivial edits need no artifact.

Do not invoke `grill-me`, a council or a whole-corpus audit unless requested.
When the plan is ready, provide the appropriate `$impl` invocation. Do not demand
another approval when the user already authorized implementation of this scope.