---
name: write-spec
description: >
  Write a feature spec (*-spec.md) for an issue. The spec is the human-written
  requirements document that feeds into the planning agent. Part of the
  spec → plan → implement pipeline.
triggers:
  - write spec
  - write-spec
  - create spec
  - feature spec
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - ToolSearch
version: "1.0.0"
author: "Ed Becker"
license: "MIT"
---

# Write Feature Spec

**Trigger:** `/write-spec <issue-id>` or `/write-spec <issue-id> <title>`

## The Spec → Plan Pipeline

Overdeck uses a two-stage planning process:

1. **Spec** (`*-spec.md`) — Human-written (often with AI assistance). Defines WHAT to build and WHY. Contains requirements, constraints, scope, research, and design decisions.
2. **Plan** (`*-plan.md`) — Generated by the planning agent. Defines HOW to build it. Contains architecture, tasks with dependencies, file-level changes, and difficulty estimates.

The planning agent reads the spec as its primary input, explores the codebase, asks clarifying questions, then produces the implementation plan.

## When to Write a Spec

- **Complex features** (multi-file, cross-cutting, architectural) — always write a spec first
- **Features with research** — when you've explored options, talked to stakeholders, or analyzed competitors
- **Features with constraints** — when there are specific technical or UX requirements the agent needs to know
- **Simple bug fixes or small changes** — skip the spec, go directly to planning or implementation

## Execution Steps

### 1. Identify the Issue

Parse the issue ID from the command argument. Determine the project:
- `MIN-XXX` → MYN project, docs at `~/Projects/myn/docs/`
- `PAN-XXX` → Overdeck project, docs at `~/Projects/panopticon-cli/docs/`

### 2. Gather Context

- Fetch the issue from the tracker (Linear for MIN, GitHub for PAN) to get title, description, comments
- Check if a spec already exists at `docs/prds/active/{issue-id-lowercase}-*-spec.md`
- If updating an existing spec, read it first

### 3. Research (Interactive)

Use AskUserQuestion or discussion to understand:
- What problem does this solve?
- Who benefits?
- What's in scope vs out of scope?
- Any technical constraints or preferences?
- Are there related specs or prior art to reference?

### 4. Write the Spec

Create the file at: `docs/prds/active/{issue-id-lowercase}-{short-title}-spec.md`

Use this structure:

```markdown
# {Issue ID}: {Title}

## Problem Statement
What problem does this solve? Why does it matter?

## Requirements
### Must Have
- Requirement 1
- Requirement 2

### Should Have
- Nice-to-have 1

### Out of Scope
- Explicitly excluded items

## Design
### User Experience
How should it work from the user's perspective?

### Technical Approach
High-level technical direction (NOT implementation details — that's for the plan).

### Constraints
- Performance requirements
- Compatibility requirements
- Security considerations

## References
- Related issues: MIN-XXX, MIN-YYY
- Prior art: links to existing code, docs, or external references
- Research: any analysis or competitor research

## Open Questions
- Questions to resolve during planning
```

### 5. Confirm File Location

After writing, confirm:
```
Spec written: docs/prds/active/{filename}-spec.md

Next steps:
1. Review and edit the spec as needed
2. Click "Plan" on the issue in the dashboard
3. The planning agent will read this spec and produce an implementation plan
```

## File Naming Convention

| Type | Pattern | Created By | Example |
|------|---------|-----------|---------|
| Spec | `{issue-id}-{title}-spec.md` | Human (this skill) | `min-734-kaia-openclaw-a2a-spec.md` |
| Plan | `{issue-id}-plan.md` | Planning agent | `min-734-plan.md` |

Both live in `docs/prds/active/`. Specs are never overwritten by agents.

## Important Notes

- **Specs are for humans** — write clearly, include context and rationale
- **Plans are for agents** — the planning agent produces structured, actionable tasks
- **Don't over-specify implementation** — the planning agent + codebase exploration will figure out the HOW
- **DO specify constraints** — things the agent can't discover on its own (performance targets, UX requirements, API contracts)
- **Reference existing code** — point to patterns, files, or modules the agent should follow