Write Tech Spec

---
name: write-tech-spec
description: This skill should be used when the user asks to "write a tech spec", "create a technical specification", "document the architecture", "write an ADR", or mentions "tech spec", "technical spec", "architecture decision record", "design document", or "component spec". Produces technical specifications and ADRs.
---
<!-- Generated by dev-standards plugin. Customize as needed. -->

# Write Technical Specification

Create a technical specification for a component, feature, or architecture decision. Tech specs are the bridge between requirements (user stories) and implementation (code). They answer "how" and "why" before code is written.

## Pre-Flight Checks

1. Confirm what needs to be specified with the user
2. Read `.claude/rules/architecture.md` for active decisions and constraints
3. Read `.claude/rules/documentation.md` for documentation standards
4. Identify related user stories or requirements
5. Determine spec type: **Component Spec**, **Feature Spec**, or **ADR**

## Spec Type Selection

### Component Spec

For new components or significant changes to existing components:
- A new service, module, or subsystem
- A significant refactoring of an existing component
- A new integration with an external system

### Feature Spec

For features that span multiple components:
- A new user-facing capability
- A cross-cutting concern (auth, logging, caching)
- A feature that changes multiple existing components

### ADR (Architecture Decision Record)

For significant architectural decisions:
- Technology choices (framework, database, library)
- Pattern adoption (event sourcing, CQRS, microservices)
- Infrastructure decisions (hosting, deployment, scaling)
- Migration decisions (old pattern to new pattern)

---

## Component Spec

### Format

```markdown
# Component: [Name]

## Status: [Draft | Review | Approved | Implemented]

## Purpose
[One sentence: what does this component do and why does it exist?]

## Context
[What problem does this solve? What existing code does it replace or extend?]

## Interface

### Public API
| Method/Function | Input | Output | Description |
|----------------|-------|--------|-------------|
| [name] | [params with types] | [return type] | [what it does] |

### Events Emitted
| Event | Payload | When |
|-------|---------|------|
| [name] | [data shape] | [trigger condition] |

### Events Consumed
| Event | Source | Action |
|-------|--------|--------|
| [name] | [context] | [what this component does] |

## Dependencies

### Required
| Dependency | Purpose | Interface |
|-----------|---------|-----------|
| [name] | [why needed] | [how accessed] |

### Optional
| Dependency | Purpose | Fallback |
|-----------|---------|----------|
| [name] | [why useful] | [behavior when absent] |

## Data Model

### State Shape
[Key data structures, schemas, types]

### Persistence
[How and where state is stored — database table, cache, file, memory]

### Migrations
[If this changes existing data, what migration is needed?]

## Behavior

### Core Algorithm / Logic
[How the component works — decision logic, transformations, state transitions]

### Side Effects
[What I/O does this component perform? Isolated at boundaries per architecture rules.]

### Concurrency
[Thread safety, race conditions, ordering guarantees]

## Error Handling
| Error Condition | Detection | Recovery | User Impact |
|----------------|-----------|----------|-------------|
| [what fails] | [how detected] | [how handled] | [what user sees] |

## Performance
- Expected throughput: [requests/sec, items/sec]
- Latency target: [p50, p95, p99]
- Resource limits: [memory, connections, file handles]
- Scaling approach: [horizontal, vertical, none]

## Security
- Authentication: [how callers are authenticated]
- Authorization: [what permissions are required]
- Data sensitivity: [PII, secrets, financial data]
- Attack surface: [input validation, injection prevention]

## Testing Strategy
| Tier | What to Test | Approach |
|------|-------------|----------|
| Unit | Pure logic, validation, transformations | Direct function calls, no mocks |
| Integration | Data access, external service calls | Real database, replay proxies |
| E2E | User-facing behavior | Full stack, highest fidelity |

## Open Questions
[Anything unresolved that needs input before implementation]

## Related
- User Stories: [US-NNN]
- User Flows: [flow links]
- ADRs: [ADR-NNN]
- Bounded Context: [context name]
```

---

## Feature Spec

### Format

```markdown
# Feature: [Name]

## Status: [Draft | Review | Approved | Implemented]

## Summary
[One paragraph: what does this feature do for the user?]

## User Stories
[List of user stories this feature implements]

## Components Affected
| Component | Change Type | Description |
|-----------|------------|-------------|
| [name] | New / Modified / Removed | [what changes] |

## Data Flow
[How data moves through the system for this feature — entry to exit]

```
User Input -> API Handler -> Service -> Repository -> Database
                                    -> Event Bus -> Handler -> Notification
```

## Implementation Plan

### Vertical Slices
[Break the feature into vertical slices — each delivers working functionality]

| Slice | Scope | Dependencies |
|-------|-------|-------------|
| 1. [name] | [what it delivers] | None |
| 2. [name] | [what it delivers] | Slice 1 |
| 3. [name] | [what it delivers] | Slice 1 |

### TDD Approach
For each slice, follow RED/GREEN/REFACTOR:
1. Write smoke test (RED)
2. Implement slice behaviors (RED -> GREEN -> REFACTOR per behavior)
3. Verify smoke test (GREEN)

## API Changes
[New or modified endpoints, request/response shapes, status codes]

## Database Changes
[New tables, columns, indexes, migrations]

## Configuration Changes
[New environment variables, feature flags, settings]

## Rollback Plan
[How to revert this feature if something goes wrong after deployment]

## Related
- User Flows: [flow links]
- ADRs: [ADR-NNN]
- Component Specs: [links]
```

---

## Architecture Decision Record (ADR)

### Format

```markdown
# ADR-NNN: [Title — the decision in imperative form]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-NNN]

## Date
[YYYY-MM-DD]

## Context
[What is the situation that requires a decision?
What forces are at play? What constraints exist?
What is the current state and why is it insufficient?]

## Decision
[What was decided? Be specific about what will be done.
Include the chosen approach AND the key reason it was chosen.]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Neutral
- [Side effect that's neither good nor bad]

## Alternatives Considered

### [Alternative 1]
- Description: [what this approach would look like]
- Rejected because: [specific reason]

### [Alternative 2]
- Description: [what this approach would look like]
- Rejected because: [specific reason]

## Implementation Notes
[Anything the implementing developer needs to know]

## Related
- Previous ADR: [if superseding]
- User Stories: [US-NNN]
- Components Affected: [list]
```

### ADR Rules

- ADRs are immutable once accepted — supersede with a new ADR, don't edit
- Number sequentially (ADR-001, ADR-002, etc.)
- Record the decision in `.claude/rules/architecture.md` with the ADR reference
- One ADR per decision — don't bundle multiple decisions

---

## Output

Write the spec to the appropriate location:

```
docs/specs/<component-or-feature-name>.md     — Component or Feature spec
docs/decisions/ADR-NNN-<slug>.md              — Architecture Decision Record
```

## Completion Checklist

### Component Spec
- [ ] Purpose is one clear sentence
- [ ] Public API fully documented with types
- [ ] Dependencies listed with purpose and interface
- [ ] Data model defined with persistence approach
- [ ] Error handling covers all failure modes
- [ ] Performance targets stated
- [ ] Security considerations addressed
- [ ] Testing strategy defined per tier
- [ ] Open questions listed (none remaining for implementation)

### Feature Spec
- [ ] User stories referenced
- [ ] Components affected identified
- [ ] Data flow documented end-to-end
- [ ] Vertical slices planned (not horizontal layers)
- [ ] TDD approach defined per slice
- [ ] API and database changes specified
- [ ] Rollback plan defined

### ADR
- [ ] Context explains the problem clearly
- [ ] Decision is specific and actionable
- [ ] Consequences include positives AND negatives
- [ ] Alternatives documented with rejection reasons
- [ ] Architecture rule updated with decision reference