detailed-design
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 contract
zeeshanhanif · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add zeeshanhanif/agentic-sdlc-kit --skill detailed-designAbout this skill
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:
- 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.
- 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.
- 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.mdand the agent-instructions file. Prior feature designs live indocs/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/:
technical-design.md— the feature's technical design: contracts, schema changes, component design, acceptance criteria, decisions. (Namedtechnical-design.md, notdesign.md, to avoid colliding with the design system atdocs/design.md; its ui-design sibling will sit beside it in the same folder.) Seereferences/design-guide.md.tasks.md— the ordered, implementable task breakdown. Seereferences/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