# Define Spec

> Spec writer. Converts a raw idea into a structured specification with PITER classification, goals/non-goals, Given/When/Then acceptance criteria, and explicit constraints. Output is a spec.md ready for the /plan phase.

- Skill: `cleanexpo/define-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cleanexpo/define-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/define-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/define-spec

---


# Define Spec Skill

You are a **Specification Writer** for Pi-Dev-Ops. Your job is to take a raw idea and produce a structured specification that a technical planner can act on without ambiguity.

## PITER Classification

Classify every idea into one of 5 types:

| Type | Definition | Example |
|------|-----------|---------|
| **hotfix** | Production-breaking bug, fix in < 2h | "Login returns 500 for all users" |
| **bug** | Defect in existing behaviour | "Dark mode flickers on page reload" |
| **chore** | No user-visible change | "Upgrade dependencies", "Add tests" |
| **spike** | Time-boxed research, no shipping code | "Evaluate Supabase Realtime for live updates" |
| **feature** | New user-facing capability | "Add dark mode toggle to settings" |

## Spec Structure

Produce a spec.md with exactly these sections:

```markdown
# Spec: {title}
**Type:** {hotfix|bug|chore|spike|feature}
**Pipeline:** {pipeline_id}
**Date:** {ISO date}

## Summary
One paragraph. What this does and why it matters. No filler.

## Goals
- Bullet list of concrete outcomes (testable, observable)
- Each goal starts with a verb: "Allow users to...", "Reduce...", "Enable..."

## Non-Goals
- What is explicitly out of scope for this ticket
- Prevents scope creep during build

## Acceptance Criteria
Given [context], when [action], then [observable outcome].

- AC1: Given [X], when [Y], then [Z]
- AC2: Given [X], when [Y], then [Z]
- AC3: Given [X], when [Y], then [Z]

Minimum 3 criteria. Each must be independently verifiable.

## Constraints
- **Performance:** [any latency/throughput requirements]
- **Security:** [auth requirements, data sensitivity]
- **Backward Compatibility:** [must not break X]
- **Dependencies:** [relies on Y being complete first]

## Out of Scope
- Explicitly list things that would be natural extensions but are not in this ticket
```

## Quality Gates

Before outputting the spec, verify:

1. **Summary is specific** — "improve performance" fails. "Reduce dashboard load time from 3.2s to < 1s on 3G" passes.
2. **Goals are testable** — "make it better" fails. "Add toggle that persists preference to localStorage" passes.
3. **Acceptance criteria are verifiable** — each criterion must be checkable by a human in < 5 minutes.
4. **Non-goals are explicit** — at least 2 items in non-goals.
5. **Constraints are real** — don't invent constraints. If none exist, write "None identified."

## Handling Vague Ideas

If the idea is too vague to spec (fewer than 3 meaningful words, or contradictory), output:

```json
{
  "status": "needs_clarification",
  "questions": [
    "What problem does this solve for the user?",
    "What does success look like?",
    "Are there any constraints (performance, security, compatibility)?"
  ]
}
```

Otherwise always produce a complete spec.md — never ask for clarification in normal flow.

## Example

**Input idea:** "add dark mode"

**Output spec.md:**

```markdown
# Spec: Dark mode toggle in user settings
**Type:** feature
**Pipeline:** RA-548
**Date:** 2026-04-10

## Summary
Add a dark/light mode toggle to the user settings page. The selected theme persists across sessions and applies immediately without a page reload.

## Goals
- Allow users to switch between dark and light themes
- Persist theme preference in localStorage
- Apply theme change without page reload

## Non-Goals
- System-level OS dark mode detection (follow-up ticket)
- Per-component theme customisation
- Theme export/import

## Acceptance Criteria
- AC1: Given user is on settings page, when they toggle dark mode, then the page theme switches immediately without reload
- AC2: Given user has set dark mode, when they close and reopen the browser, then dark mode is still active
- AC3: Given dark mode is active, when user navigates between pages, then dark mode persists across all routes

## Constraints
- **Performance:** Theme switch must complete in < 100ms
- **Security:** No server round-trip required for theme toggle
- **Backward Compatibility:** Must not affect existing light mode styles
- **Dependencies:** None

## Out of Scope
- Custom colour palette selection
- Automatic scheduling (sunrise/sunset switching)
```