Task: Create SPEC.md for a Work Unit

Task: Create SPEC.md for a Work Unit

Objective

Produce a SPEC.md that serves as the single source of truth for implementing one work unit: a file manifest, every public symbol with a full signature, every behavioral path as ordered prose, every error as an ERR_CODE row bound to ERRORS.md § 3, every test as a setup/action/assertion triple, and every design-layer citation (invariants, events, state machines, sagas, metrics, SLOs, threats, mitigations, use cases, data aggregates) the unit touches. The defining discipline — and the definition of "done" — is that the gap between SPEC and code is purely mechanical: an implementing agent reading only this file (and the dependency SPECs it cites) produces the implementation without making any architectural, behavioral, or naming decisions of its own.

The commonest violation is silently picking an answer for a design-level question instead of surfacing it. When the design suite is silent, ambiguous, or contradictory on a question the unit must answer — a wire shape, an error code, a lock granularity, a field name — the question belongs in § 10 Open Questions with options, tradeoffs, and a recommendation. Do not invent. The SPEC must never introduce a design decision that is not already traceable to DOMAIN, INTERFACES, BEHAVIOR, ERRORS, QUALITY, SECURITY, DATA, or USE_CASES.

Inputs

1. Trigger artifact(s) (required) — one or more roadmap/<NNN>-<slug>/ROADMAP.md (planned work) and/or issues/<NNN>-<slug>/ISSUE.md (defects in shipped code) that initiated this unit. Read the body and frontmatter end-to-end: the trigger states what the unit must deliver, its acceptance criteria, and the area it belongs to.
2. Unit folder with stub frontmatter (required) — the orchestrator has pre-created units/<area>/u<NN>/SPEC.md with frontmatter populated (unit, kind, area, trigger, status: in-design, and possibly initial depends_on / supersedes / related candidates). Empty list fields (files: [], concepts: [], owns_ids: []) are placeholders this skill fills in. The SPEC body is what this skill writes. Path: units/<area>/u<NN>/SPEC.md.
3. Architecture and design suite (required) — DOMAIN.md plus the design registries whose stable IDs the SPEC will cite: ARCHITECTURE.md, INTERFACES.md, BEHAVIOR.md, ERRORS.md, QUALITY.md, SECURITY.md, DATA.md, USE_CASES.md. The subset actually loaded is the read set the orchestrator passes — the registries whose IDs the unit touches given its trigger and area.
4. Decision documents (optional, auto-discovered) — any D-NNN referenced from the trigger or from any cited design artifact. Discovery mechanism: follow D-NNN citations and read each referenced decision at decisions/D-NNN-slug/DECISION.md.
5. SPEC.md files of related existing units (when applicable, supplied by orchestrator) — area peers and cross-area related units identified via the orchestrator's spec discovery (folder peers in units/<area>/, plus frontmatter grep on overlapping concepts and files, plus units named in the new unit's stub frontmatter depends_on / supersedes / related). These are the source of truth for the exact type names, function signatures, and interface shapes the new unit may import or rewrite. Read every supplied dependency SPEC end-to-end — truncated reads on dependencies cause silent signature drift.
6. Prior SPEC.md for this unit (optional, auto-discovered — only if refining) — read fully; preserve every resolved open question, every assigned internal-symbol name, and every Size hint already calibrated against earlier drafts. Re-run citations against the current registries — do not assume stale INV-NN or ERR_CODE are still valid.

Read-set size: trigger(s) + DOMAIN are always read; 3–6 further artifacts depending on the orchestrator-supplied read set (related-unit SPECs + the design-layer registries this unit actually cites). Read every supplied dependency SPEC end-to-end — truncated reads on dependencies cause silent signature drift.

Rules

Completeness rules

• Every public symbol must have a full signature: name, parameters (with names and types), return type, async/sync.
• Every error condition must be enumerated with its trigger, error type, and user-facing consequence (HTTP status, exit code, message format).
• Every constant, default value, environment variable name, timeout, size limit, or magic number must be stated explicitly with its value.
• Every file must be described at the level where an agent can produce it without referring to other sections — each file entry is a self-contained mini-spec.
• Every behavioral path (happy path, each error path, edge cases) must be described step by step in prose.
• The Open Questions section must be empty. If you cannot resolve a question, surface it to the user rather than leaving it open.

Precision rules

• Use exact names — function names, type names, field names, file paths, route paths, crate/package names. Do not use placeholders like "appropriate error" or "relevant fields."
• When referencing something from a dependency unit, use its exact exported name and the file it comes from.
• Describe behavior as ordered steps ("1. Acquire write lock on repo_id. 2. Open repository. 3. ..."), not as vague summaries ("handles the request appropriately").
• Distinguish between "returns error" and "returns empty/default" — state which one, and the exact value.