spec-writer

What this skill does

# Spec Writer - Rigorous Project Specification

Use this skill when the user mentions "write spec", "project spec", "define goals", "spec properties", "project definition", or wants to create or update a comprehensive project specification.

---

## Purpose

A spec is the **source of truth** for a project's direction. It answers: What are we building? Why? What's in scope? How do we know when we're done?

This skill guides the creation of rigorous specs through **property-based validation** - ensuring all necessary aspects are addressed without enforcing a rigid format.

## Required Properties

Every good spec must address these properties. The format can vary, but the information must be present.

### 1. Purpose (Required)
**Question**: Why does this project exist? What problem does it solve?

- Not just "what it does" but "why it matters"
- Who benefits and how
- What would be missing if this didn't exist

### 2. Scope (Required)
**Question**: What's explicitly IN and OUT?

**In Scope**:
- Concrete capabilities the project will have
- Features that are committed

**Out of Scope** (equally important):
- What this project deliberately won't do
- Adjacent problems it won't solve
- Features explicitly deferred

### 3. Success Criteria (Required)
**Question**: How do we know when this is "done" or "working"?

- Observable, verifiable conditions
- Not vague ("works well") but specific ("passes all integration tests", "handles 1000 concurrent users")
- Can be different for different phases

### 4. Current Phase (Required)
**Question**: Where are we now in the project lifecycle?

- What phase/milestone is active
- What "done" looks like for THIS phase
- What triggers moving to next phase

## Contextual Properties

Include these when relevant to the project:

### Architecture Decisions
Key technical choices and their rationale.

- What was decided
- Why (constraints, tradeoffs)
- Alternatives considered
- Consequences/implications

### Constraints
Limitations that shape the solution.

- Technical (language, platform, dependencies)
- Business (timeline, budget, resources)
- External (APIs, regulations, compatibility)

### Dependencies
What this project relies on.

- External services/APIs
- Libraries/frameworks
- Other internal projects
- People/expertise

### Risks
What could derail the project.

- Technical risks (complexity, unknowns)
- External risks (dependencies, changes)
- Mitigation strategies

### Open Questions
Unresolved decisions that need answers.

- What's uncertain
- What information would help decide
- When decisions need to be made

## Writing a Spec

### Process

1. **Start with Purpose**: Write 2-3 sentences on why this exists
2. **Define Scope**: List what's in, what's out
3. **Set Success Criteria**: How will we verify success?
4. **Identify Current Phase**: Where are we now?
5. **Add Context**: Architecture, constraints, risks as relevant
6. **Review for Gaps**: Does someone reading this know what to build?

### Validation Checklist

A spec is complete when you can answer YES to all:

- [ ] Could a new team member understand the project's purpose?
- [ ] Is it clear what's NOT in scope?
- [ ] Are success criteria specific and verifiable?
- [ ] Is the current phase and its goals clear?
- [ ] Are key technical decisions documented with rationale?
- [ ] Are significant risks identified?

### Style Guidelines

- **Be specific**: "Fast" → "Responds within 200ms"
- **Be honest**: Include unknowns and risks
- **Be concise**: Dense information, not lengthy prose
- **Update regularly**: A stale spec is worse than no spec

## Probing Questions

When helping write a spec, ask:

**Purpose**:
- "If this project succeeds, what's different in the world?"
- "Who is the primary user/beneficiary?"
- "What's the one-sentence pitch?"

**Scope**:
- "What's the most common misconception about what this does?"
- "What adjacent problem will you NOT solve?"
- "If you had to cut half the features, which half stays?"

**Success**:
- "How would you demo this to prove it works?"
- "What would make you say 'this phase is done'?"
- "What metrics matter?"

**Decisions**:
- "What's the most controversial technical choice you've made?"
- "What would you do differently if starting over?"
- "What's the hardest constraint you're working with?"

See `references/spec-properties.md` for detailed property definitions.