create-techspec

name

create-techspec

description

Create implementation-ready Technical Specifications from existing PRDs using a required analyze-research-clarify-draft-save workflow. Use when Codex is asked to write, generate, create, draft, or update a Tech Spec, technical specification, implementation specification, architecture spec, or engineering plan based on tasks/prd-[feature-name]/prd.md and save it as tasks/prd-[feature-name]/techspec.md.

Create TechSpec

Use this skill to translate a complete PRD into a concise, implementation-ready technical specification.

Required Workflow

1. Confirm and analyze the PRD.

   • Confirm the PRD exists at tasks/prd-[feature-name]/prd.md.
   • Read the full PRD before drafting.
   • Extract technical requirements, constraints, success metrics, and scope boundaries.

2. Explore the project before asking questions.

   • Discover involved files, modules, interfaces, configs, middleware, persistence, tests, and infrastructure.
   • Map dependencies, callers/callees, integration points, concurrency concerns, error handling, and existing patterns.
   • Read relevant project rules under .codex/rules/ and relevant skills under .codex/skills/.

3. Research before asking questions.

   • Use Context7 MCP for technical library/framework questions when applicable.
   • Use web search for current business rules, regulations, third-party policy constraints, and general information that may have changed.
   • Perform at least three web searches when the feature depends on external business rules or general current information.

4. Ask technical clarifying questions.

   • Ask focused questions before generating the Tech Spec.
   • Cover domain placement, data flow, external dependencies, main interfaces, testing expectations, reuse vs. build decisions, failure modes, timeouts, and idempotency.
   • Use the user-question tool when available; otherwise ask concise questions directly.

5. Map standards conformance.

   • Identify applicable .codex/rules/ and .codex/skills/ entries.
   • Highlight deviations, justify them, and propose conformant alternatives.

6. Draft the Tech Spec.

   • Read references/techspec-template.md and follow it exactly.
   • Focus on HOW to implement the PRD; avoid repeating PRD functional requirements.
   • Keep the document around 2,000 words or fewer.
   • Provide architecture overview, component design, interfaces, models, endpoints, integration points, impact analysis, testing strategy, observability, decisions, risks, conformance, and relevant files.
   • Avoid excessive code; interface examples must be concise and no longer than 20 lines each.

7. Save the Tech Spec.

   • Save as tasks/prd-[feature-name]/techspec.md beside the source PRD.
   • Confirm the write operation and final path.

Hard Rules

• Do not generate the Tech Spec before exploring the project.
• Do not generate the Tech Spec before asking clarifying questions.
• Do not deviate from the template in references/techspec-template.md.
• Do not implement code; the goal is only to produce the Tech Spec.
• Do not skip reading the PRD.
• Do not skip saving the file unless the user explicitly asks for draft text only.

Quality Checklist

• PRD was reviewed.
• Deep repository analysis was completed.
• Applicable .codex/rules/ and .codex/skills/ entries were checked.
• Technical clarifying questions were asked and answered.
• Tech Spec follows references/techspec-template.md.
• File is saved at tasks/prd-[feature-name]/techspec.md.
• Final response includes the saved path and confirmation.