Cy Create Techspec

Create TechSpec

Translate business requirements into a detailed technical specification.

<HARD-GATE> Do NOT write the TechSpec file until ALL phases are complete and the user has approved the final draft. Do NOT skip the codebase exploration — every TechSpec MUST be informed by existing architecture. Do NOT skip user interactions — the user MUST participate in shaping the TechSpec at every decision point. Do NOT require section-by-section approval — generate the complete draft, then let the user review it. This applies to EVERY TechSpec regardless of perceived simplicity. </HARD-GATE>

Asking Questions

When this skill instructs you to ask the user a question, you MUST use your runtime's dedicated interactive question tool — the tool or function that presents a question to the user and pauses execution until the user responds. Do not output questions as plain assistant text and continue generating; always use the mechanism that blocks until the user has answered.

If your runtime does not provide such a tool, present the question as your complete message and stop generating. Do not answer your own question or proceed without user input.

Anti-Pattern: "This Is Too Simple To Need Technical Design Review"

Every TechSpec goes through the full design review process. A single endpoint, a minor refactor, a configuration change — all of them. "Simple" technical changes are where unexamined assumptions about existing architecture cause the most integration failures. The design review can be brief for genuinely simple changes, but you MUST ask technical clarification questions and get approval on the technical approach before writing the artifact.

Anti-Pattern: End-Of-Flow Bureaucracy

Once the user has answered the technical clarification questions and approved an approach, do not force them through a second approval loop for System Architecture, Data Models, API Design, or other final document sections. Synthesize the approved direction into the TechSpec directly. The user can review and request edits in the generated file afterward.

Required Inputs

• Feature name identifying the .compozy/tasks/<name>/ directory.
• Optional: existing _prd.md as primary input.
• Optional: existing _techspec.md for update mode.

Checklist

You MUST create a task for each phase and complete them in order:

1. Gather context — read PRD, ADRs, and explore codebase architecture 2. Ask technical questions — 3-6 targeted questions on architecture, data models, APIs, testing 3. Create ADRs — record significant technical decisions (architecture pattern, technology choices, data model approach) 4. Draft the TechSpec — write using the canonical template from references/techspec-template.md 5. Review with user — present the draft, iterate until approved 6. Save the file — write to .compozy/tasks/<name>/_techspec.md

Workflow

1. Gather context.

• Check for _prd.md in .compozy/tasks/<name>/. If it exists, read it as the primary input.
• If no PRD exists, ask the user for a description of what needs technical specification.
• Read existing ADRs from .compozy/tasks/<name>/adrs/ to understand decisions already made during PRD creation.
• Create .compozy/tasks/<name>/adrs/ directory if it does not exist.
• Spawn an Agent tool call to explore the codebase for architecture patterns, existing components, dependencies, and technology stack.
• If _techspec.md already exists, read it and operate in update mode.

2. Ask technical clarification questions.

• Focus on HOW to implement, WHERE components live, and WHICH technologies to use.
• Cover architecture approach and component boundaries.
• Cover data models and storage choices.
• Cover API design and integration points.
• Cover testing strategy and performance requirements.
• Ask only one question per message. If a topic needs more exploration, break it into a sequence of individual questions.
• Prefer multiple-choice questions when the options can be predetermined.
• Include a fallback option (e.g., "D) Other — describe") for flexibility.

3. Create ADRs for significant technical decisions.

• For each significant decision (architecture pattern chosen, technology selected, data model approach, etc.):
• Read references/adr-template.md.
• Determine the next ADR number by listing existing files in .compozy/tasks/<name>/adrs/.
• Fill the template: the chosen design as "Decision", rejected alternatives as "Alternatives Considered", and trade-offs as "Consequences". Set Status to "Accepted" and Date to today.
• Write each ADR to .compozy/tasks/<name>/adrs/adr-NNN.md (zero-padded 3-digit sequential number).

4. Draft the TechSpec.

• Read references/techspec-template.md and fill every applicable section.
• MANDATORY — Architecture Decision Records section: The generated TechSpec MUST end with an "Architecture Decision Records" section listing every ADR created during this process. Each entry must include the ADR number (e.g., ADR-001), title, and a one-line summary formatted as a link to the adrs/ directory. Even simple features require at least one ADR documenting the primary technical approach chosen and alternatives rejected. If no ADRs were created in step 3, go back and create at least one before generating the document.
• Apply YAGNI ruthlessly: remove any component, interface, or abstraction that is not strictly necessary. Do NOT propose new packages or directories when the feature can be implemented by adding a single file to an existing package.
• Every PRD goal and user story should map to a technical component.
• Reference PRD sections by name but do not duplicate business context.
• Include code examples only for core interfaces, limited to 20 lines each. The Core Interfaces section must contain at least one Go interface or struct definition as a code block, even for simple features — show the primary type that other components will depend on.
• The Development Sequencing section MUST include a numbered Build Order where every step after the first explicitly states which previous steps it depends on.
• Prefer active voice, omit needless words, use definite and specific language over vague generalities. Every sentence should earn its place.
• Language: English. Tone: clear, technical, consistent with existing project artifacts.
• Present the complete draft to the user for review.

5. Review with the user.

• Present the draft and ask using the interactive question tool:
• "Here is the TechSpec draft. Please review and let me know:"
• A) Approved — save as is
• B) Adjust specific sections (tell me which ones)
• C) Rewrite section X (tell me what to change)
• D) Discard and start over
• If B or C: make the changes and present again.
• If D: go back to step 2.

6. Save the TechSpec file.

• Write the completed document to .compozy/tasks/<name>/_techspec.md.
• Confirm the file path to the user.
• Remind the user that the next step is to create tasks using cy-create-tasks from this TechSpec.

Process Flow

digraph create_techspec {
    "Gather context (PRD + codebase)" [shape=box];
    "Ask technical questions (one at a time)" [shape=box];
    "Create ADRs for key decisions" [shape=box];
    "Draft TechSpec (canonical template)" [shape=box];
    "User approves draft?" [shape=diamond];
    "Save _techspec.md" [shape=doublecircle];

    "Gather context (PRD + codebase)" -> "Ask technical questions (one at a time)";
    "Ask technical questions (one at a time)" -> "Create ADRs for key decisions";
    "Create ADRs for key decisions" -> "Draft TechSpec (canonical template)";
    "Draft TechSpec (canonical template)" -> "User approves draft?";
    "User approves draft?" -> "Draft TechSpec (canonical template)" [label="no, revise"];
    "User approves draft?" -> "Save _techspec.md" [label="approved"];
}

Error Handling

• If the PRD is missing, proceed with user-provided context and note the absence in the Executive Summary.
• If codebase exploration reveals conflicting architectural patterns, document both and recommend one with rationale.
• If the user rejects the design proposal, incorporate all feedback and present a revised proposal.
• If the target directory does not exist, create it.
• If operating in update mode, preserve sections the user has not asked to change.

Key Principles

• One question at a time — Do not overwhelm with multiple questions in a single message
• Multiple choice preferred — Easier for users to answer than open-ended when possible
• YAGNI ruthlessly — Remove unnecessary components, abstractions, and interfaces from all designs
• Draft then review — Generate the complete TechSpec draft first, then iterate with the user until approved
• Technical focus only — Never ask business questions; that belongs in the PRD
• Trade-offs are mandatory — Every Executive Summary must state the primary technical trade-off of the chosen approach
• PRD as input — When _prd.md exists, use it as primary context; every PRD goal should map to a technical component
• Pipeline awareness — The TechSpec feeds into cy-create-tasks; focus on HOW, not WHAT or WHY
• Template compliance — Every TechSpec MUST follow the canonical template
• Language consistency — Write all TechSpec content in English

ADR-XXX: [Title]

Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

Date

YYYY-MM-DD

Context

[Describe the issue or problem that motivates this decision. Include relevant technical context, constraints, and any forces at play.]

Decision

[State the decision that was made. Be specific and clear about what will be done.]

Alternatives Considered

Alternative 1: [Name]

• Description: [Brief description]
• Pros: [List advantages]
• Cons: [List disadvantages]
• Why rejected: [Reason]

Alternative 2: [Name]

• Description: [Brief description]
• Pros: [List advantages]
• Cons: [List disadvantages]
• Why rejected: [Reason]

Consequences

Positive

• [List positive outcomes]

Negative

• [List negative outcomes or trade-offs]

Risks

• [List risks and mitigation strategies]

Implementation Notes

[Any specific implementation details, migration steps, or technical notes relevant to this decision.]

References

• [Link to relevant documents, PRDs, tech specs, or external resources]

TechSpec Template

Use this template to structure every Technical Specification. Fill each section based on technical clarification outcomes and codebase exploration. Omit sections that do not apply and note the reason.

Executive Summary

Brief technical overview in 1-2 paragraphs:

• Key architectural decisions
• Implementation strategy and approach
• Primary technical trade-offs

System Architecture

Component Overview

Main components, their responsibilities, and relationships:

• Component name, purpose, and boundaries
• Data flow between components
• External system interactions

Implementation Design

Core Interfaces

Key service interfaces with code examples. Limit each example to 20 lines or fewer:

• Interface definitions and contracts
• Method signatures with parameter and return types
• Error handling conventions

Data Models

Core domain entities and their relationships:

• Entity definitions with field types
• Request and response types for APIs
• Database schemas or storage structures

API Endpoints

API surface organized by resource:

• Method, path, and description
• Request format and required fields
• Response format and status codes

Integration Points

External services and system boundaries. Include only when the design integrates with systems outside the codebase:

• Service name and purpose of integration
• Authentication and authorization approach
• Error handling and retry strategy

Impact Analysis

Table of components affected by this implementation:

Testing Approach

Unit Tests

• Strategy and key components to test
• Mock requirements and boundaries
• Critical scenarios and edge cases

Integration Tests

• Components to test together
• Test data requirements and setup
• Environment dependencies

Development Sequencing

Build Order

Ordered implementation sequence respecting dependencies: 1. [First component] - no dependencies 2. [Second component] - depends on step 1 3. [Continue with dependency chain]

Technical Dependencies

Blocking dependencies that must be resolved before implementation:

• Infrastructure requirements
• External service availability
• Team deliverables or shared components

Monitoring and Observability

Operational visibility for the implementation:

• Key metrics to track
• Log events and structured fields
• Alerting thresholds and escalation

Technical Considerations

Key Decisions

Significant technical choices with rationale:

• Decision: what was chosen
• Rationale: why this option
• Trade-offs: what was given up
• Alternatives rejected: what else was considered and why not

Known Risks

Technical challenges and mitigation strategies:

• Risk description and likelihood
• Mitigation approach
• Areas requiring further research or prototyping

Architecture Decision Records

ADRs documenting key decisions made during PRD brainstorming and technical design:

• ADR-NNN: Title — One-line summary of the decision