tech-spec
Tech Spec
A tech spec makes implementation decisions reviewable before code changes. This skill is design-only: keep production files read-only and return the spec inline unless the user or calling workflow authorizes writing it.
Frame The Change
Use the accepted request and any confirmed Feature Contract as behavioral authority. Inspect the repository instructions and only the code, tests, docs, and runtime constraints needed to design the affected path. Reuse project vocabulary and established patterns where they fit.
Resolve routine engineering choices and explain consequential tradeoffs. Ask when a missing product, public-contract, trust, data-lifecycle, deployment, ownership, or scope decision changes the intended result. Keep unresolved decisions visible; a Confirmed - Blocked Feature Contract cannot yield an implementation-ready spec while its blocker still affects the change.
State the current behavior, target outcome, callers, goals, non-goals, invariants, constraints, affected entrypoints and side effects, operational risks, and smallest independently shippable slice. Ground claims in accepted input or inspected evidence rather than repeating broad discovery.
Subtract First
Before adding structure, identify what the slice can delete, collapse, inline, or narrow. A behavior-preserving refactor should pin current behavior and reduce reader load; separate any behavior change as a feature or fix.
Choose Direct cutover when no observed consumer, retained data, deployment constraint, or user requirement needs the old path, and leave one path. Choose Protected evolution only for a named obligation; place the compatibility mechanism at the narrowest seam and give temporary support a removal condition.