Cursor rule

1---
2description: "Guides AI in creating detailed Technical Specification documents that complement PRDs, providing senior-level architectural guidance and implementation details for development teams"
3globs:
4alwaysApply: false
5---
6# Rule: Generating Technical Specification Documents
7 
8<goal>
9To guide an AI assistant in creating detailed Technical Specification (Tech Spec) documents that complement Product Requirements Documents (PRDs). The Tech Spec should provide senior-level architectural guidance, implementation details, and system design decisions suitable for implementation teams.
10</goal>
11 
12## Template Reference
13 
14<template_reference>
15**ALWAYS use the standardized Tech Spec template:** tasks/docs/_techspec-template.md
16This template provides a comprehensive structure for technical specifications, ensuring consistency across all technical documentation in the project.
17</template_reference>
18 
19## Prerequisites
20 
21<prerequisites>
22- **Review Project Standards:** First examine `.cursor/rules/` to understand all established coding standards, patterns, and architectural guidelines
23- **MANDATORY:** Review [architecture.mdc](mdc:.cursor/rules/architecture.mdc) for SOLID principles, Clean Architecture, and design patterns
24- A completed PRD document must exist in `tasks/prd-[feature-slug]/_prd.md`
25- Understanding of the project's domain structure: `engine/{agent,task,tool,workflow,runtime,infra,llm,mcp,project,schema,autoload,core}/` and `pkg/` for internal packages
26- Familiarity with project standards: Go patterns, clean architecture, SOLID principles
27- **Separation of Concerns:** Confirm that detailed technical design and implementation information is **absent** from the PRD and will be authored exclusively in this Tech Spec. If such details are found in the PRD, create a `PRD-cleanup.md` file in the feature folder listing the specific lines to remove or move, and notify the PRD owner.
28</prerequisites>
29 
30## Process
31 
32<process_workflow>
331. **Analyze PRD:** Review the existing PRD to understand requirements and scope, noting any misplaced technical details that should be migrated to the Tech Spec.
342. **Pre-Analysis with Zen MCP:** Use Zen MCP with Gemini 2.5 and O3 to analyze the PRD and identify technical complexity areas, potential architecture patterns, and system design considerations
353. **Ask Technical Questions:** Gather technical clarifications focusing on system design, performance, and architecture decisions
364. **Generate Tech Spec:** Create focused technical specification appropriate for MVP/alpha phase
375. **Post-Review with Zen MCP:** Use Zen MCP with Gemini 2.5 and O3 to review the generated tech spec for completeness, architectural soundness, and adherence to best practices
386. **Save Tech Spec:** Save as `_techspec.md` in `tasks/prd-[feature-slug]/`
39</process_workflow>
40 
41## Technical Clarifying Questions
42 
43<technical_questions_guidance>
44Focus on essential implementation details for MVP:
45 
46* **System Architecture:** "Which domain should this feature belong to? (agent/task/tool/workflow/runtime/infra/llm/mcp/project/schema/autoload/core or pkg/ for internal packages)"
47* **Data Flow:** "What are the main data inputs/outputs and how do they flow through the system?"
48* **External Dependencies:** "Does this require any external services or APIs?"
49* **Key Implementation:** "What's the core logic that needs to be implemented?"
50* **Testing Focus:** "What are the critical paths that must be tested?"
51* **Impact Analysis:** "What existing modules or components might be affected by this change?"
52* **Monitoring:** "What metrics or logs would be useful for monitoring this feature?"
53* **Special Concerns:** "Are there any specific performance or security requirements for this feature?"
54 
55Note: Keep questions focused on what's needed for implementation, not theoretical concerns.
56</technical_questions_guidance>
57 
58## Tech Spec Structure
59 
60<spec_structure>
61The generated Tech Spec MUST follow the template structure from @_techspec-template.md:
62 
631. **Executive Summary:** Brief technical overview (1-2 paragraphs)
642. **System Architecture:** Domain placement and component overview
653. **Implementation Design:** Core interfaces, data models, and API endpoints
664. **Integration Points:** External integrations (only if needed)
675. **Impact Analysis:** Effects on existing components, APIs, and data models
686. **Testing Approach:** Unit and integration testing strategy
697. **Development Sequencing:** Build order and technical dependencies
708. **Monitoring & Observability:** Metrics, logs, and dashboards
719. **Technical Considerations:** Key decisions, risks, special requirements, and standards compliance
72 
73Note: Keep the spec focused and practical. Only include sections relevant to the feature. The goal is a 2-4 page document that developers can quickly reference.
74</spec_structure>
75 
76## Content & Code Snippet Guidelines
77 
78<content_guidelines>
79**Primary Focus:** Provide architectural decisions, system design rationale, and interface-level detail. Avoid implementation-heavy content.
80 
81**Code Snippets:**
82- Include **only** concise, illustrative code snippets (≤ 20 lines).
83- Focus on interfaces, method signatures, or small algorithm excerpts necessary to explain a concept.
84- **NEVER** embed complete source files or large implementation blocks.
85- Use `// ...` or `/* ... */` to indicate omitted sections when context is needed.
86 
87**Document Size Guidelines:** Aim for **~1,500-2,500 words (2-4 pages)**. Focus on essential technical decisions and implementation guidance. This is an MVP/alpha phase project - avoid over-engineering the documentation.
88 
89**Quality Checklist:**
90- [ ] All technical design captured (moved from PRD if needed)
91- [ ] Development sequencing and dependencies clearly defined
92- [ ] Impact analysis identifies affected existing components
93- [ ] Document is ≤ 2,500 words (focused and practical)
94- [ ] No duplication of functional requirements from PRD
95- [ ] Confirms adherence to all project standards in `.cursor/rules/`
96- [ ] Includes monitoring approach using existing infrastructure
97</content_guidelines>
98 
99## Design Principles
100 
101<design_principles type="mandatory">
102**MANDATORY:** Follow architectural principles defined in [architecture.mdc](mdc:.cursor/rules/architecture.mdc):
103- **SOLID Principles:** Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
104- **DRY Principle:** Don't Repeat Yourself - extract common functionality, centralize configuration
105- **Clean Architecture:** Domain-driven design with proper layer separation and dependency flow
106- **Clean Code:** Intention-revealing names, small functions, proper error handling
107- **Project Patterns:** Service construction, context propagation, resource management
108</design_principles>
109 
110<target_audience>
111Written for **senior developers and architects** who need:
112- Clear implementation guidance
113- Architectural decision rationale
114- Integration and deployment strategies
115- Performance and security considerations
116</target_audience>
117 
118<output_specification>
119* **Format:** Markdown (`.md`)
120* **Location:** `tasks/prd-[feature-slug]/`
121* **Filename:** `_techspec.md`
122* **Template:** Use @_techspec-template.md structure
123</output_specification>
124 
125## Final Instructions
126 
127<final_instructions type="mandatory">
1281. **Architecture Foundation:** Apply patterns from [architecture.mdc](mdc:.cursor/rules/architecture.mdc) and other project rules.
1292. **Technical Focus:** Concentrate on *how* to implement, not *what*; do not repeat functional requirements from the PRD.
1303. **Keep It Focused:** Stay within 2,500 words. Focus on practical implementation guidance while maintaining high quality standards.
1314. **Standards Compliance:** Ensure alignment with all `.cursor/rules/` standards and project patterns.
1325. **Implementation Ready:** Provide clear, actionable guidance for developers to start coding immediately.
133</final_instructions>
134