# Documentation Technical Spec Writing > Imported TRAE skill from documentation/Technical_Spec_Writing.md Use when this capability is needed. - Skill: `tomevault-io/documentation-technical-spec-writing` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/documentation-technical-spec-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-technical-spec-writing/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/documentation-technical-spec-writing --- # Skill: Technical Specification Writing (RFC/Design Doc) ## Purpose To document the architectural decisions, data models, and implementation plans for a complex feature or system before any code is written. This allows for early feedback, cross-team alignment, and avoids costly architectural mistakes. ## When to Use - Before starting a task that takes more than 1 week of development - When introducing a new technology, database, or infrastructure change - When building features that impact multiple teams or microservices - To document the rationale behind "why" a specific approach was chosen over others ## Procedure ### 1. Document Structure A standard Technical Spec should include these core sections: 1. **Overview/Abstract**: 1-2 paragraphs summarizing the problem and the proposed solution. 2. **Background**: Context on why this change is necessary (links to tickets, user research, or performance logs). 3. **Goals & Non-Goals**: - **Goals**: What we *must* achieve (e.g., "Reduce latency by 50%"). - **Non-Goals**: Explicitly state what is *out of scope* to prevent scope creep. 4. **Proposed Architecture**: High-level design, diagrams (Mermaid), and data flow. 5. **Data Model**: Schema changes, new tables, or API contracts. 6. **Detailed Implementation Plan**: Step-by-step breakdown of the work. 7. **Alternatives Considered**: Why we didn't choose other approaches (e.g., "We considered MongoDB but chose PostgreSQL because..."). 8. **Security & Performance**: Potential risks and mitigation strategies. 9. **Monitoring & Metrics**: How will we measure success? (e.g., "New Datadog dashboard for error rates"). ### 2. The "Alternatives Considered" Section This is the most important section for senior engineers. It demonstrates depth of thought and prevents repeating past mistakes. - List at least 2 other ways the problem could have been solved. - Provide a brief pros/cons list for each. - Explain the specific trade-offs (e.g., "Option A was faster to build but had higher long-term maintenance costs"). ### 3. Review Process 1. **Draft**: Write the spec in Markdown or a collaborative tool (Google Docs, Notion). 2. **Internal Feedback**: Share with your immediate team for technical sanity checks. 3. **Broad Review**: Share with stakeholders (Product, Security, SRE) for sign-off. 4. **Implementation**: Only start coding once the spec is approved. ### 4. Updating the Spec Specs are living documents. If the implementation plan changes significantly during development, update the spec to reflect the reality. ## Best Practices - **Write for the Future**: Imagine someone reading this spec 2 years from now. Will they understand *why* these decisions were made? - **Be Concise**: Use bullet points and diagrams. Avoid "walls of text". - **Use Clear Language**: Avoid vague terms like "scalable" or "performant". Use numbers (e.g., "Handle 10,000 requests per second"). - **Link Everything**: Link to PRs, Jira tickets, and related architectural docs (ADRs). - **Acknowledge Trade-offs**: Every architectural decision has a downside. Be honest about them. --- > Source: [Ditto190/crispy-nextjs-turborepo-monorepo](https://github.com/Ditto190/crispy-nextjs-turborepo-monorepo) — distributed by [TomeVault](https://tomevault.io).