Detailed Design

---
name: detailed-design
description: >-
  Produces the per-feature technical design — the first skill in the
  construction loop, run once for each vertical slice as it reaches the front
  of the implementation plan. Reads the feature's spec from the plan, the FR/UC
  IDs it implements, the architecture's conceptual domain model and ADRs, and
  the live codebase (contracts and schema earlier features already established),
  then designs the feature concretely: API contracts (endpoints,
  request/response shapes, error codes), the physical schema changes
  (migrations — architecture owns the conceptual model; new entities escalate
  to an architecture amendment, never local invention), component-level
  design, acceptance criteria, and an ordered tasks.md breaking the feature
  into implementable tasks. Use after project-scaffolding, per feature, before
  ui-design and implementation. Trigger on "design this feature", "detailed
  design for", "design the API for this feature", "create the technical
  design", or "design the next feature". Hands contracts to ui-design.
---

# Detailed Design (per feature)

The first **loop skill**: it runs once per vertical slice, for the life of the
project, turning a feature's planned intent into a buildable technical design —
the backend/system half of the feature's low-level design (`ui-design` is the
presentation half, and consumes this skill's contracts).

Three principles govern it:

1. **The feature's *what* is fixed upstream; this skill designs the *how*.** The
   FR/UC IDs the feature implements were assigned and verified in requirements;
   the plan chose and scoped the feature. This skill never invents or reinterprets
   requirements — that inheritance-by-ID is exactly what keeps per-feature design
   consistent at scale.
2. **The live codebase is an input, not an obstacle.** Feature N is designed
   months after feature 1, in a fresh session, against code that has evolved past
   the skeleton. Design against *reality*: the contracts, schema migrations,
   and conventions earlier features established. A design that conflicts with
   existing code is wrong even if it matches the documents.
3. **Depth here, and only here.** This is where the pipeline's
   depth-on-demand promise is kept: full concrete detail for *this* feature —
   contracts, columns, components, tasks — and nothing for features that haven't
   reached the front.

## Inputs

Defaults below; user-provided paths win; source-gated citation throughout
(cite FR/UC/SCR/ADR IDs only when their documents exist; never fabricate).

- **Implementation plan** — `docs/implementation-plan.md`. Which feature is next
  (or the user names one), its traced touchpoints: FRs implemented, UCs
  realized, SCR screens, building blocks/endpoints, data.
- **SRS** — `docs/srs.md`. The verbatim FR statements (they become acceptance
  criteria) and relevant NFRs (they constrain the design — cite them).
- **Use cases** — `docs/use-cases.md`. The UC flows the feature realizes —
  main/alternate/exception paths drive endpoint behavior and error design.
- **Architecture** — `docs/architecture.md`. The conceptual domain model
  (entity ownership, consistency boundaries), the ADRs constraining this
  feature, cross-cutting concepts (auth, error handling, observability
  conventions the design must follow).
- **The live codebase** — mandatory read, not optional: existing route/contract
  patterns, the current schema and migration history, module boundaries,
  shared utilities, conventions in `docs/scaffold-notes.md` and the
  agent-instructions file. Prior feature designs live in `docs/features/`.
- **UX foundations** — `docs/ux-foundations.md`, light touch: the SCR screens'
  stated purpose/states, as context for what the contracts must serve.

## Outputs

Per feature, into **`docs/features/FEAT-NNN-<slug>/`** — keyed on the
feature's **stable FEAT ID from the plan** (immutable, so re-sequencing the
plan never invalidates folder names), with the slug from its name for human
readability — e.g., `docs/features/FEAT-004-sign-in/`:

1. **`technical-design.md`** — the feature's technical design: contracts,
   schema changes, component design, acceptance criteria, decisions. (Named
   `technical-design.md`, not `design.md`, to avoid colliding with the design
   *system* at `docs/design.md`; its ui-design sibling will sit beside it in
   the same folder.) See `references/design-guide.md`.
2. **`tasks.md`** — the ordered, implementable task breakdown. See
   `references/tasks-guide.md`.

Plus two write-backs:
- **RTM** (`docs/rtm.md`, if present; skip silently otherwise): **append** the
  feature's design ref (e.g., `features/FEAT-004-sign-in/technical-design.md`) into the **Design
  ref** cell of every FR this feature implements — append, never overwrite;
  Design ref column only, per the RTM ownership contract.
- **Architecture amendment escalation** (when triggered — see design-guide):
  a needed new entity or changed boundary is *not* designed locally; it's
  surfaced as a proposed architecture amendment and the feature design waits on
  or explicitly notes it.

## Workflow

### Phase 1 — Locate the feature and ingest

Identify the feature: the user names it (by FEAT ID or name — explicit naming
is the only legitimate off-sequence path), or default to
**the next undesigned feature — computed, not stored**: plan build-sequence
order minus the `FEAT-*` folders already in `docs/features/`. Multiple
candidates is not ambiguity — the sequence resolves it (earliest in build
order wins); never present a menu. **Announce the resolution** ("FEAT-004 is
next per the plan's build sequence") so the user can redirect before work
starts. Execution status
lives in the artifacts (a folder with a verified technical-design.md =
designed; its tasks.md checkboxes = build progress) — the plan itself is never
written with status; it stays the structural source owned by
implementation-planning. Read the feature's plan entry and pull its full
trace: FR IDs (fetch their verbatim statements and priorities from the SRS),
UC IDs (fetch their flows), SCR IDs, blocks/endpoints, data. Read the
architecture's domain model, the ADRs that touch this feature, and the
cross-cutting concepts.

If the feature's plan entry is missing touchpoints (a coarse far-future feature
that just reached the front), tighten it first: derive the missing FR/UC/SCR
trace from the documents and confirm with the user — this is the plan's
just-in-time elaboration happening on schedule.

### Phase 2 — Read the code

Survey the live codebase before designing anything: existing endpoint and
contract conventions (naming, envelope shapes, error format), the current
schema and its migration history, the module the feature lands in and its
boundaries, shared utilities the design should reuse, and prior feature designs
in `docs/features/` (especially any this feature depends on). Record what the
design must conform to. **Reality wins over documents** where they diverge —
and note the divergence.

### Phase 3 — Design

Read `references/design-guide.md`. Produce, concretely:
- **API contracts** — endpoints with methods, paths, request/response shapes,
  validation rules, error codes; following the codebase's established
  conventions. UC exception/alternate flows become error behaviors.
- **Physical schema changes** — tables/columns/indexes/constraints as
  migrations, within the entities the architecture's conceptual model already
  owns. **A new entity or ownership/boundary change escalates to an
  architecture amendment — never invented locally.**
- **Component design** — the modules/services/functions inside the feature's
  building block: responsibilities, interactions, where the stubbed skeleton
  code gets replaced.
- **Acceptance criteria** — testable, derived from the FR statements and UC
  flows, each citing its FR/UC ID. These are what acceptance verification will
  later check.
- **Design decisions** — any real fork gets a short decision note with its
  driver (mini-ADR discipline; feature-local decisions stay here, architectural
  ones escalate).

### Phase 4 — Break down tasks

Read `references/tasks-guide.md`. Decompose the design into `tasks.md`: an
ordered list of implementable tasks, each small enough to complete and verify
in one focused session, each pointing at the design sections and acceptance
criteria it serves, ordered so the feature builds incrementally (schema →
domain → contract → wiring → tests green), with UI tasks referenced but owned
by ui-design's output.

### Phase 5 — Verify

Read `references/verification.md` and self-check: every feature FR is covered by
acceptance criteria and by tasks; every cited ID resolves; the schema stays
inside the conceptual model (or an escalation is filed); contracts don't
collide with existing code; tasks are complete, ordered, and traceable. Fix
failures; flag the unfixable.

### Phase 6 — Deliver

Write both files, do the RTM append, and summarize: the design in a few
sentences, the task count and order, any escalations filed, a **live-computed
progress line** ("FEAT-004 designed — 5 of 14 features now designed", counted
from the plan vs. `docs/features/`; never stored anywhere), and the handoff —
**ui-design** now designs the feature's SCR screens against these contracts;
implementation follows tasks.md. Offer to proceed to either.

## Scope boundaries

Does **not**: design screens (ui-design's half — it consumes these contracts);
implement anything (tasks.md is the handoff to implementation); change
requirements or the plan (amendments belong to their owning skills); invent
entities or alter consistency boundaries (architecture amendment); write to
any RTM column except appending Design ref.

## What good looks like

- Every acceptance criterion cites the FR/UC it verifies; every task points at
  design sections; nothing in the design lacks a requirement behind it.
- The schema diff is migrations against the *actual current* schema, not the
  skeleton's — and it stays inside the conceptual model's entities.
- Contracts read like the codebase already reads — conventions inherited, not
  reinvented.
- tasks.md could be handed to a fresh session (or a loop agent) and executed
  top-to-bottom without re-deriving context.
- Escalations were filed, not worked around.