---

name: spec description: Transform a product brief into a technical specification.

Spec

Invocation

This skill is performed in the Architect persona. If you are not already running as Architect (for example, the user invoked /spec directly), read subagents/architect.md and adopt its role guidance for the rest of this task. Stay in the current chat—do not delegate the skill itself to a subagent. You should, however, aggressively delegate codebase research to research subagents (see Codebase Discovery below) so that only their summarized findings—not raw file contents—land in this conversation.

Objective

Transform a product brief into a technical specification and save it to docs/specs/{project-name-slug}.md.

Instructions

1. Explain the brief-to-spec transformation.

2. Ask for the brief path and extract the goal, target users, constraints, and success metrics.

3. Codebase discovery. Before asking the user technical questions, dispatch research subagents in parallel for each independent area the spec needs to ground itself in. Typical areas:

   • existing modules likely to be touched (describe by feature or area, not by guessed file paths)
   • data model / database schema
   • relevant API routes, server actions, and their auth posture
   • existing tests and fixtures for the affected area
   • cross-cutting concerns already in play (feature flags, telemetry, rate limits)

   Each subagent prompt MUST request a structured summary, not file dumps. Require the subagent to return:

   • file paths and line ranges of the 3-10 most relevant symbols
   • current ownership boundaries and key types or interfaces
   • constraints, footguns, or TODOs already present
   • what is not in the area, to bound scope

   Treat the returned summaries as your working knowledge of the codebase. Only Read a file directly in this chat if a subagent summary is insufficient and you need a specific snippet to ground a decision in the spec. Inline Read/Grep is the exception, not the default.

4. Ask focused technical discovery questions one at a time as needed, informed by the discovery findings:

   • architecture and ownership boundaries
   • data model or schema changes
   • auth and authorization implications
   • external integrations
   • security and privacy concerns
   • performance budgets or expected scale
   • rollout and deployment considerations

5. Read templates/tech-spec-template.md and follow its structure. Capture the discovery findings as compact citations (path and line range with a one-line note), not pasted source.

6. Keep the testing plan at the requirements and assertions level, not the implementation level.

7. Save the spec to docs/specs/{project-name-slug}.md.

8. If the brief has a status field, update it from draft to completed.

9. End with the spec path, the most important technical decisions, and the recommended next step: /tdd or /code.