Technical specification

technical-specification

When to use

Use this skill when:

• Writing a technical specification for a new feature or system
• Writing a Product Requirements Document (PRD) when user pain leads and solution shape follows
• Creating an architecture decision record (ADR)
• Documenting a technical RFC (Request for Comments)
• Planning a significant technical change that needs team review

Do NOT use when:

• Trivial changes (a good PR description is enough)
• Implementation work (use feature-planning or php-coder skill)

Procedure: Write a spec

1. Inspect existing specs and ADRs — Read agents/features/, agents/decisions/ (or docs/adr/) and any linked tickets to identify prior art, naming, and status conventions.
2. Pick the document shape — Choose Technical Spec, PRD, RFC, or ADR based on audience (engineering vs. product) and decision irreversibility.
3. Draft the document — Use the template below; fill Status, Summary, Problem, Goals, Non-Goals, Proposed Solution.
4. Verify — Confirm goals are measurable, non-goals are explicit, and at least one reviewer is named before circulating.

Technical Specification (full)

For complex features or systems. Stored in agents/features/ or module agents/features/.

# Technical Specification: {Title}

## Status
{ Draft | In Review | Approved | Implemented | Superseded }

## Summary
{2-3 sentences explaining what this spec proposes and why.}

## Problem
{What pain point or limitation does this address?}

## Goals
- {Specific, measurable goal}
- {Another goal}

## Non-Goals
- {What this spec explicitly does NOT cover}

## Proposed Solution

### Overview
{High-level description of the approach.}

### Detailed Design
{Technical details — data models, APIs, algorithms, flows.}

### Alternatives Considered
| Alternative | Pros | Cons | Why rejected |
|---|---|---|---|

## Migration Plan
{How to transition from current state to the proposed solution.}

## Risks and Mitigations
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|

## Open Questions
- [ ] {Unresolved question}

## References
- {Links to related docs, tickets, or external resources}

Product Requirements Document (PRD)

For features whose shape is product-driven rather than implementation-driven — when "what users get" matters more than "how the code is wired". Use a PRD when a Technical Specification would over-index on internals and under-index on user value. Stored in agents/features/ next to the technical spec when both exist.

# PRD: {Title}

## Status
{ Draft | In Review | Approved | Shipped | Parked }

## Problem
{The user-visible pain. One paragraph. Cite evidence — support tickets,
analytics, user quotes — not assumptions.}

## Success Criteria
- {Measurable outcome with a number and a timeframe}
- {Another measurable outcome}

## Non-Goals
- {What this PRD explicitly does NOT cover — protect scope}

## User Stories
- As a {role}, I want to {action}, so that {outcome}.
- As a {role}, I want to {action}, so that {outcome}.

## Major Modules
{The 3-7 functional building blocks the feature decomposes into. One
sentence each — what it does, not how. Implementation lives in the
technical spec, not here.}

- **{Module name}** — {one-sentence responsibility}
- **{Module name}** — {one-sentence responsibility}

## Open Questions
- [ ] {Unresolved product question — pricing, permission, copy, edge case}

## References
- {Links to research, related PRDs, technical spec when it exists}

PRD vs Technical Specification — when to pick which:

• PRD first when the user pain is clear but the solution shape is not ("users can't share dashboards" → PRD scopes the problem; spec follows).
• Spec first when the solution shape is clear but the implementation is non-trivial ("rebuild auth on OAuth2" → spec leads; PRD often skipped).
• Both when the feature is large enough that product and engineering decisions belong in different artifacts.

Architecture Decision Record (ADR)

For significant technical decisions. Stored in agents/decisions/.

# ADR-{number}: {Title}

## Status
{ Proposed | Accepted | Deprecated | Superseded by ADR-{N} }

## Context
{What is the issue? What forces are at play?}

## Decision
{What is the change that we're proposing or have agreed to implement?}

## Consequences

### Positive
- {Benefit}

### Negative
- {Drawback or tradeoff}

### Neutral
- {Other notable consequences}

Lightweight RFC

For smaller decisions that need team input. Can be a PR description or a short doc.

# RFC: {Title}

## Proposal
{What do you want to do?}

## Why
{Why is this needed?}

## How
{Brief technical approach.}

## Impact
{What does this change? Who is affected?}

## Open for feedback until: {date}

Writing guidelines

Be specific, not vague

❌ "The system should be fast"
✅ "API response time should be < 200ms at p95 for list endpoints"

Include constraints

• Performance requirements (latency, throughput)
• Compatibility requirements (PHP version, browser support)
• Security requirements (authentication, data sensitivity)
• Scale requirements (data volume, concurrent users)

Show your reasoning

Don't just present the solution — show why it was chosen over alternatives. The "Alternatives Considered" section is often the most valuable part.

Keep it actionable

A spec should be implementable by someone who wasn't in the original discussion. If a developer reads only this document, they should be able to build it.

Integration with other systems

• Feature plans reference specs when technical depth is needed.
• Roadmaps are generated from specs after approval.
• ADRs are referenced from AGENTS.md or module docs for historical context.
• Sessions link to the spec being implemented.

Output format

1. Technical specification document with architecture decisions
2. API contracts, data models, and sequence diagrams
3. Implementation plan with dependencies

Auto-trigger keywords

• technical spec
• PRD
• product requirements
• RFC
• ADR
• architecture decision

Validate

• Verify every section of the spec template is filled in (no placeholders left).
• Confirm constraints and limitations are explicit, not implied.
• Check that the spec answers: What, Why, How, What not, and When.

Gotcha

• A spec without constraints is fiction — always include technical limitations, timeline, and scope boundaries.
• The model tends to write specs that describe the ideal solution without acknowledging existing code.
• Don't write specs for trivial features — a spec is overhead that's only worth it for complex changes.

Do NOT

• Do NOT write specs without researching the codebase first.
• Do NOT present only one option — always consider alternatives.
• Do NOT leave specs in "Draft" forever — push for a decision.
• Do NOT implement before the spec is reviewed (for significant changes).