spec
- Repo stars 38
- License MIT
- Author repo builder-skills
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @kazdenc · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Step 1: Read the Requirements
Before writing, gather the inputs. A spec without requirements is guesswork. Source · What to pull from it PRD · Problem, goals, functional requirements, non-functional requirements, scope boundaries Job stories · User workflows, acceptance criteria, edge cases Conversation · If neither exists, interview the user to establish what the system must do and for whom
Step 2: Write the Spec
Use this structure. Adapt headings to the project — not every section applies every time.
# Technical Specification
A tech spec answers **how** we'll build something — without over-prescribing implementation details that engineers should own. It bridges product requirements to engineering execution.
## Step 1: Read the Requirements
Before writing, gather the inputs. A spec without requirements is guesswork.
| Source | What to pull from it |
|--------|---------------------|
| **PRD** | Problem, goals, functional requirements, non-functional requirements, scope boundaries |
| **Job stories** | User workflows, acceptance criteria, edge cases |
| **Conversation** | If neither exists, interview the user to establish what the system must do and for whom |
Flag anything ambiguous. A spec built on vague requirements produces vague engineering.
## Step 2: Write the Spec
Use this structure. Adapt headings to the project — not every section applies every time.
```
# Tech Spec: [Feature / System Name]
## Overview
One paragraph. What this is, why we're building it, and what it connects to.
Link to the PRD or source requirements.
## Technical Approach
The core design decision. How this fits into the existing system.
Keep it to the architecture level — components, their responsibilities,
how they interact. Don't write pseudocode unless it clarifies a tricky algorithm.
## Data Model
New tables, fields, or schema changes. Include:
- Field name, type, constraints
- Relationships to existing models
- Migration notes (new table vs altering existing)
## API Design
Endpoints, methods, request/response shapes.
For each endpoint:
- Method + path
- Request body / params
- Response shape
- Error cases
## Edge Cases
What happens when things go wrong or get weird.
| Case | Behavior | Rationale |
|------|----------|-----------|
| User submits duplicate | Return existing record, don't create new | Prevents data bloat |
| Payload exceeds size limit | Reject with 413, log for monitoring | Protects downstream services |
## Testing Strategy
What gets tested and how.
- Unit tests: which modules, what coverage target
- Integration tests: which workflows end-to-end
- Manual QA: what can't be automated and why
## Migration Plan
Only if changing existing systems. Cover:
- Data migration steps
- Backward compatibility (can old and new coexist during rollout?)
- Rollback procedure
## Rollout Plan
How this gets to users.
- Feature flag strategy
- Phased rollout stages (internal → beta → GA)
- Monitoring and alerting during rollout
- Success/failure criteria for each stage
```
## Decision Log
Every non-obvious choice gets logged. This prevents re-litigating decisions later and helps future engineers understand why things are the way they are.
```
## Decisions
### D-1: [Short description of the decision]
**Options considered:**
1. Option A — [brief description]
2. Option B — [brief description]
3. Option C — [brief description]
**Decision:** Option B
**Rationale:** [Why this option wins. Reference constraints, trade-offs,
or requirements that drove the choice.]
```
Keep decisions numbered (D-1, D-2) so they can be referenced in code comments and PR descriptions.
## Quality Checks
Before delivering the spec, verify:
- **Does it answer "how" without dictating unnecessary "what exactly"?** The spec should constrain the architecture, not micromanage the implementation. Engineers need room to make local decisions.
- **Are edge cases covered?** If you only describe the happy path, the implementation will only handle the happy path.
- **Is the data model complete?** Missing a field or relationship here means a migration later.
- **Do API contracts match the requirements?** Walk each job story through the API. Does the data flow support every acceptance criterion?
- **Is the testing strategy proportional?** Critical paths get thorough tests. Low-risk utilities get basic coverage. Don't spec 100% coverage everywhere.
- **Is the rollout reversible?** If something goes wrong in production, can you roll back without data loss?
## Scope Boundaries
A tech spec is not:
- **A tutorial.** Don't explain how frameworks work. Assume engineering competence.
- **A PRD.** Don't redefine what we're building. Reference the PRD and focus on how.
- **A project plan.** Don't include timelines or task assignments. That's a separate artifact.
## When the Spec Is Done
Ship it with:
1. **Clear status** — Draft, In Review, or Approved
2. **Open questions** — What still needs answers before building starts
3. **Review ask** — Who should review (engineering, security, platform) and what feedback you need
Sections and files
Listed in source order.
sections -> Step 1: Read the Requirements → Step 2: Write the Spec → Decision Log → Quality Checks → Scope Boundaries → When the Spec Is Done
terms -> how · PRD · Job stories · Conversation · Options considered · Decision · Rationale · Does it answer "how" without dictating unnecessary "what exactly"?
files/cmd -> request/response · Success/failure
body sha256 -> 0742b2197f15
Step 1: Read the Requirements
Before writing, gather the inputs. A spec without requirements is guesswork. Source · What to pull from it PRD · Problem, goals, functional requirements, non-functional requirements, scope boundaries Job stories · User workflows, acceptance criteria, edge cases Conversation · If neither exists, interview the user to establish what the system must do and for whom
Step 2: Write the Spec
Use this structure. Adapt headings to the project — not every section applies every time.
Decision Log
Every non-obvious choice gets logged. This prevents re-litigating decisions later and helps future engineers understand why things are the way they are. Keep decisions numbered (D-1, D-2) so they can be referenced in code comments and PR descriptions.
Quality Checks
Before delivering the spec, verify: Does it answer "how" without dictating unnecessary "what exactly"? The spec should constrain the architecture, not micromanage the implementation. Engineers need room to make local decisions. Are edge cases covered? If you only describe the happy path, the implementation will only handle the happy path. Is the data model complete? Missing a field or relationship here means a migration later.
Scope Boundaries
A tech spec is not: A tutorial. Don't explain how frameworks work. Assume engineering competence. A PRD. Don't redefine what we're building. Reference the PRD and focus on how. A project plan. Don't include timelines or task assignments. That's a separate artifact.