tech-spec
Technical Specification
Translate approved product and UX decisions into the simplest technically sound plan. This skill answers: how should we implement the experience? It does not redesign the product or UX, create tickets, or write implementation code.
Read docs/ux-spec.md before proposing a solution. If it is missing, ask the user to run /ui-spec first or provide an approved equivalent. When a UX requirement is costly, preserve it where practical, identify the tradeoff, and ask for a decision rather than silently removing it.
Process
-
Inspect the UX specification, product requirements,
AGENTS.mdorCLAUDE.md, package configuration, current routes, components, data model, APIs, authentication, styling, dependencies, and tests. For existing products, the codebase is a major source of truth. Reuse working architecture and components unless a concrete constraint requires change. -
Trace each material UX requirement to an implementation boundary: route, component, state, interface, data, authorization rule, or test. Prefer the smallest architecture that preserves the experience. Avoid new layers, services, state stores, repositories, dependencies, caches, or background jobs without a requirement that justifies them.
-
Define only the data, interfaces, security controls, performance work, and tests the product requires. Record assumptions, open decisions, and deliberate exclusions. For AI features, specify purpose and safe operational behavior rather than adding AI because it is available.
-
Write
docs/technical-spec.md. Createdocs/if it does not exist. Use project vocabulary. Do not turn the document into an implementation ticket list or prescribe stale file-by-file edits. -
Verify that every critical UX journey and state has an implementation path, and that the plan does not alter the UX without an explicit decision. Present material tradeoffs and questions for approval.