spec-authoring

Spec Authoring

Overview

The spec is not a document of its own any more: it is the context and design sections of the ONE analysis report the analiz task produces (analiz-html-report) — an HTML document attached with add_task_document, format: "html", titled analiz: <YYYY-MM-DD> <topic>. Never attach a separate spec: … document, never write it to a file and never commit it; shelling out to echo/heredoc to fake a file is how a run gets killed for repeating itself. The spec is the contract the plan section and every implementation task will be checked against.

These sections must name real files, symbols, and interfaces you found with codebase_search / grep_code / get_repo_tree / expand_symbol_context. A run that attaches an analiz document without a single successful exploration call is rejected by the system, not by a reviewer.

Structure

Where each part lives in the report: Context / Goal feeds summary and context; Architecture through Out of scope are subsections of design (each an <h3> with its own id). Scale each part to its complexity — a few sentences if straightforward, up to 200–300 words if nuanced; Decision record and Security & data are each written only when they apply (see their conditions below):

1. Context / Goal — the problem, who has it, what outcome closes it.
2. Architecture — the chosen approach, and in one line why it beat the alternatives.
3. Components — each unit with clear boundaries: what it does, its interface (exact names and types), what it depends on.
4. Data flow — how a request/value moves through the components, including where validation happens.
5. Error handling — what fails, how each failure surfaces, what the user sees.
6. Testing approach — what proves each component works: unit, integration, end-to-end.
7. Decision record — for a choice worth remembering (new dependency or framework, a datastore or schema shape, an API/contract pattern, auth or security architecture, a cross-repo integration — skip it for a bug fix or config change): <h3 id="design-decision"> with Problem (1–2 sentences) · Decision drivers (bullets) · Options (table: option | fits drivers | cost/risk) · "Chosen: X, because …" · Consequences (Good, because … / Bad, because …). If the repo keeps its own ADRs (docs/adr, docs/decisions, adr/), add a plan step in that repository that writes NNNN-<title>.md in the repo's own format.
8. Security & data — who may call each new interface, which inputs are attacker-controlled, what data leaves the system (to a log, a third party, a client bundle), and what is logged (security-review has the full checklist for any new endpoint or data flow). Any schema or contract change also gets its expand/contract shape and consumer list here (migration-and-contract-review).
9. Out of scope — explicitly named items deferred or excluded.