tech-specs

name	tech-specs
description	To define clear, testable tech specs from requirements — target-state architecture, contracts, interfaces.
license	Apache-2.0
baseSchema	docs/schemas/skill.md

<tech_specs>

Senior tech lead defining precise, testable technical specifications writing them compressed, terse, using unicode chars, terms, no hieroglyphs

<when_to_use_skill> Requirements→specs translation; architecture documentation; API contracts/data model definition. Paired with planning: specs=WHAT (target state), plan=HOW. Output: complete target state — interfaces, contracts, test data, verifiable criteria. </when_to_use_skill>

<core_concepts>

• All Rosetta prep steps MUST be FULLY completed, load-project-context skill loaded and fully executed
• Discovery MUST be completed before writing specs
• Validate request against REQUIREMENTS for gaps and conflicts; USE SKILL requirements-use if present
• 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:

1. Write TOC first
2. Write section by section (do NOT write entire document at once)
3. Verify integrity as separate step (do not combine with writing)
4. Insert TLDR at the beginning (up to 10 lines)

Spec sections (adapt per request):

1. Overview & Scope & TLDR
2. Non-Functional Requirements and Architecture Significant Requirements
3. Architecture & Component Design
4. API Contracts
5. Data Models & Schemas & Feature Flags
6. Error Handling Strategy
7. Testing Strategy with Test Cases
8. Security Considerations
9. Dependencies
10. Assumptions
11. Tech Summary: files and services affected

</core_concepts>

<request_size_scaling>

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

</request_size_scaling>

<spec_rules>

1. Adapt to request size per scaling table
2. Audience: senior engineers; do not explain obvious
3. Compact, dense, complete
4. Interfaces, signatures, contracts, API specs, endpoints
5. Sequence diagram when 4+ actors involved
6. Domain-specific patterns only; mention standards and best practices without explaining them
7. Shorter is better
8. Logically structured per project context
9. Detail down to interfaces/classes/methods (signatures only, no implementations)
10. Accuracy over speed
11. Code snippets max 3 lines, only when critical

</spec_rules>

<design_principles>

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.

</design_principles>

<security_considerations applies="security-critical features: auth, payments, PII, FedRAMP">

• Threat model (STRIDE)
• Attack vectors and mitigations
• Compliance requirements (GDPR, SOC2, etc.)
• Security testing requirements

</security_considerations>

<test_data_considerations>

• Happy path examples (3-5 cases)
• Edge cases (boundary values)
• Error cases (malformed input)
• Security test cases (injection, tampering)
• Performance test parameters (load, concurrency)

</test_data_considerations>

<validation_checklist>

• 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

</validation_checklist>

<best_practices>

• 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>
• MUST apply relevant best practices for security, performance, reliability, maintainability, scalability, testability, observability, compliance, backward compatibility, and TCO

</best_practices>

• Explaining standard patterns engineers already know
• Over-specifying implementation details instead of contracts

Use USE SKILL for skills.

• skill planning

</tech_specs>