version: "1.0.0" 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.

1. 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/.

1. 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.

1. 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.

1. Map standards conformance.

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

1. 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.

1. 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.