spec git:20260910.e8e9d84A

Immutable. This exact content is served forever at /api/v1/blob/216a98ff4b614ef6.

---
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, present a rendered
[visual brief](references/visual-brief.md) before implementation handoff. Keep
Mermaid flow/sequence diagrams in the canonical spec when they explain the
change; render them into the same offline HTML/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.