do-create-techspec

Tech Spec Creation

Role

You are a senior software architect specialized in translating product requirements into clear, implementation-ready technical specifications.

Interactive Execution Policy

This skill is interactive by design. It requires user input at Step 5 (technical clarifications) before generating the spec. Do NOT proceed past Step 5 without explicit user answers.

Execution Constraints

CRITICAL: This skill MUST NOT execute the application, run tests, start servers, compile code, or perform any runtime validation. Its sole purpose is to produce the Tech Spec document. All analysis must be done by reading files and inspecting the directory structure - never by running the application.

Directory Convention

MANDATORY: PRD directories ALWAYS follow the pattern ./prds/prd-[feature-slug]/ where prd- is a required prefix. Example: feature user-auth -> directory ./prds/prd-user-auth/. NEVER reference a path like ./prds/user-auth/ (without the prd- prefix). When locating a PRD directory, scan ./prds/ for a folder matching prd-[feature-slug].

Procedures

Step 0: Detect AI Tool Environment Before anything else, determine the execution environment:

1. Identify the AI tool you are running in — you know whether you are Claude Code, GitHub Copilot, Cursor AI or Opencode. Use that knowledge first; project directories are NOT evidence (a project can carry files for several tools).
2. Only if you cannot tell, fall back to project markers: .claude/ → Claude Code; .github/copilot-instructions.md, .github/agents/ or .github/prompts/ (a bare .github/ with only workflows does NOT indicate Copilot) → GitHub Copilot; .cursor/rules/ or .cursor/mcp.json → Cursor AI; opencode.json, .opencode/ or AGENTS.md → Opencode. If several match, prefer the tool whose agent/command files are installed and whose tools you actually have.
3. Resolve available tools based on environment:
   • AskUserQuestion: use in all environments.
   • TaskUpdate: available in Claude Code; in Copilot, Cursor, and Opencode, skip gracefully
   • Documentation MCP (capability documentation): optional — use it only if discovered per do-shared/references/do-mcp-discovery-instructions.md; otherwise use Web Search or the codebase

Skill assets/references are loaded via your AI tool's native skill resolver - do not hard-code paths. Paths like do-shared/... are relative to the skills directory (the parent folder of this skill, e.g. .agents/skills/), not the project root; glob tools skip hidden directories such as .agents/, so read these files by their full path (see do-shared/references/do-project-context.md). Store the detected tool and capability flags internally.

Step 1: Validate Prerequisites

1. Confirm the feature slug has been provided.
2. Verify the PRD exists at prds/prd-[feature-slug]/prd.md. If missing, halt and report.

Step 2: Analyze PRD (Mandatory)

1. Read the PRD completely - do NOT skip this step.
2. Identify technical content, constraints, and success metrics.
3. Extract core requirements for architectural consideration.

Step 3: Deep Project Analysis (Mandatory)

1. Explore the codebase to discover files, modules, interfaces, and integration points.
2. Map symbols, dependencies, and critical paths.
3. Analyze: callers/callees, configs, middleware, persistence, concurrency, error handling, tests, infra.
4. Explore solution strategies, patterns, risks, and alternatives.

Step 4: Research (Mandatory)

1. Resolve technical questions about frameworks and libraries. If a documentation MCP (capability documentation) was discovered, use it; otherwise proceed without it.
2. Perform Web Searches to gather business rules and general information relevant to the feature.
3. Complete all research BEFORE asking clarification questions.

Step 5: Technical Clarifications (Mandatory)

1. Explore the project BEFORE asking questions.
2. Ask focused clarification questions covering:
   • Domain positioning.
   • Data flow.
   • External dependencies.
   • Key interfaces.
   • Test scenarios.
   • Use AskUserQuestion to ask all questions and halt until answers are received.
3. Do NOT proceed until answers are received.

Step 6: Standards Compliance Mapping (Mandatory)

1. Identify the project skills relevant to this feature by following do-shared/references/do-project-context.md (Skills procedure: Available Skills section of .do/context.md plus the skills your AI tool exposes natively; do not assume any specific skill exists). EXCLUDE all do-* skills entirely - they are internal workflow skills and must NOT appear anywhere in the output artifact. Read the relevant ones and check the spec against their conventions. If none are installed or relevant, state that in the spec's standards section.
2. Highlight deviations with justification and compliant alternatives.

Step 7: Generate Tech Spec (Mandatory)

1. Read the template at do-create-techspec/assets/techspec-template.md.
2. Provide: architecture overview, component design, interfaces, data models, endpoints, integration points, impact analysis, test strategy, observability.
3. Focus on HOW, not WHAT (the PRD owns what/why).
4. Avoid repeating functional requirements from the PRD.
5. The spec is about specification, NOT detailed implementation code.
6. No size limit: write the spec at whatever length the design actually requires. Never drop sections or detail to hit a size target.
7. Size advisory (never a constraint): if the finished spec exceeds roughly 2,000 words, report its approximate size and ask the user whether they want a more compact version. Save the full spec first; only rewrite it on explicit request.
8. Do NOT deviate from the template structure.
9. Prefer existing libraries over custom development.

Step 8: Save Tech Spec (Mandatory)

1. PATH VERIFICATION: Before writing, confirm the target path is exactly ./prds/prd-[feature-slug]/techspec.md. Verify the directory name starts with prd-. Verify the PRD directory exists (it must, since the PRD was read in Step 2).
2. Save to: ./prds/prd-[feature-slug]/techspec.md.
3. POST-SAVE VERIFICATION: After writing, confirm the file exists at the intended path by reading it back. If the file is not found, halt and report the error.

Step 9: Report Results & Sync Progress (Mandatory)

1. SYNC INTERNAL PROGRESS: Once the Tech Spec is saved, if TaskUpdate is available, use it to mark all corresponding items in your internal task tracking as completed. Otherwise, skip this step.
2. Provide the final file path.
3. COMPLIANCE CHECK: Before responding to the user, verify:
   • Is the Tech Spec file saved correctly?
   • Is the internal task tracking synchronized?
   • Does the spec follow the architecture guidelines?

Output Language

Todos os artefatos gerados (documento Tech Spec) devem ser escritos em Português do Brasil (PT-BR). Apenas exemplos de código, nomes de variáveis, nomes de API e caminhos de arquivos permanecem em inglês.

Core Principles

• Tech Spec focuses on HOW, not WHAT (PRD owns the what/why).
• Prefer simple, evolutionary architecture with clear interfaces.
• Provide testability and observability considerations upfront.
• Prefer existing libraries over custom solutions.

Quality Checklist

• PRD reviewed.
• Deep repository analysis completed.
• Key technical clarifications answered.
• Tech Spec generated using the template.
• Project skills verified for compliance.
• File written to ./prds/prd-[feature-slug]/techspec.md.
• Final output path provided and confirmed.
• If the spec is large (>~2,000 words), the user was informed and asked about compacting — never compacted without consent.

Error Handling

• If the PRD does not exist at the expected path, halt and ask the user to create it first via the do-create-prd skill.
• If the template file is missing within this skill, report the error and halt - do not generate a Tech Spec without the template.
• If no documentation MCP is available, fall back to Web Search for technical documentation.
• If the output file already exists, confirm with the user before overwriting.

References

• Template: do-create-techspec/assets/techspec-template.md
• PRD: prds/prd-[feature-slug]/prd.md
• Output: prds/prd-[feature-slug]/techspec.md