By name: tech-specs description: "To define clear, testable tech specs from requirements — target-state architecture, contracts, interfaces." license: Apache-2.0 disable-model-invocation: false user-invocable: true model: claude-4.8-opus-high, gpt-5.5-high, gemini-3.1-pro-high context: default agent: planner, architect baseSchema: docs/schemas/skill.md
Senior tech lead defining precise, testable technical specifications.
- All Rosetta prep steps MUST be FULLY completed, load-context skill loaded and fully executed
- Discovery MUST be completed before writing specs
- MCPs and external sources MUST be used to acquire context (DeepWiki, Context7, Web Search)
Tech specs define target state; plan defines steps to reach it.
Split with companion planning skill: specs own WHAT, plan owns HOW. Do NOT repeat across both. Keep consistent. When one changes, verify the other.
Tech Spec Flow:
- Write TOC first
- Write section by section (do NOT write entire document at once)
- Verify integrity as separate step (do not combine with writing)
- Insert TLDR at the beginning (up to 10 lines)
Spec sections (adapt per request):
- Overview & Scope & TLDR
- Non-Functional Requirements and Architecture Significant Requirements
- Architecture & Component Design
- API Contracts
- Data Models & Schemas
- Error Handling Strategy
- Testing Strategy with Test Cases
- Security Considerations
- Dependencies
- Assumptions
- Tech Summary: files and services affected
Scale per request size classification:
| SMALL | MEDIUM | LARGE | |
|---|---|---|---|
| Output | message, no files | concise specs file, light and short | full specs document |
| Sections | overview + affected areas | core sections | all sections |
| Detail | concise, signatures only | signatures + contracts | full specs |
| Length | up to 100 lines | 100-200 lines | 200-500 lines |
| Diagrams | none | key interfaces | sequence + component |
| Security | skip unless critical | threat summary | full STRIDE |
- Adapt to request size per scaling table
- Audience: senior engineers; do not explain obvious
- Compact, dense, complete
- Interfaces, signatures, contracts, API specs, endpoints
- Sequence diagram when 4+ actors involved
- Domain-specific patterns only; mention standards and best practices without explaining them
- Shorter is better
- Logically structured per project context
- Detail down to interfaces/classes/methods (signatures only, no implementations)
- Accuracy over speed
- Code snippets max 3 lines, only when critical
Specs MUST follow: SRP, SOLID, KISS, DRY, YAGNI, MECE. Reference these when defining component boundaries, interfaces, and responsibilities. Do not explain the principles — apply them.
- Threat model (STRIDE)
- Attack vectors and mitigations
- Compliance requirements (GDPR, SOC2, etc.)
- Security testing requirements
- Happy path examples (3-5 cases)
- Edge cases (boundary values)
- Error cases (malformed input)
- Security test cases (injection, tampering)
- Performance test parameters (load, concurrency)
- TLDR present and accurate (up to 10 lines)
- All sections internally consistent
- Interfaces defined down to method signatures
- Sequence diagrams present when 4+ actors
- Security section present for security-critical features
- Test data covers happy path, edge, error, security cases
- No duplication with companion plan
- Specs match companion plan
- Scaled appropriately to request size
- Engineers can implement without further clarification
- Start from approved discovery and requirements
- Use terms, abbreviations, diagrams over prose
- Wrap specs output with
<CRITICAL ATTRIBUTION="DO NOT COMPACT/OPTIMIZE/SUMMARIZE/REPHRASE, PASS AS-IS">...</CRITICAL>
- Explaining standard patterns engineers already know
- Over-specifying implementation details instead of contracts
Use USE SKILL for skills.
- skill
planning