spec

What this skill does

# Spec - Progressive Disclosure Specification

## Core Philosophy

**Write what's needed. Skip what's not.**

Most specs fail because they're either:
- Too thin (unclear, leads to rework)
- Too thick (nobody reads them, decisions buried in prose)

This skill routes you to the right depth:
- **Quick task?** → Write a clear issue
- **Feature?** → Write a lite PRD
- **AI feature?** → Add context requirements and behavior examples

The templates are already excellent. This skill helps you use them.

---

## Linear Method Principles

These principles guide every level:

1. **Issues, not user stories** - Plain language wins. "Add export button to dashboard" beats "As a user, I want to export data so that I can..."

2. **Scope down** - If it can't be done in 1-3 weeks by 1-3 people, break it down further.

3. **Short specs get read** - Long specs get skipped. Write for clarity, not completeness.

4. **Prototype > documentation** - A working demo + 3 paragraphs beats a 10-page spec.

5. **Make decisions, not descriptions** - Every section should decide something.

**See:** `skills/spec/references/philosophy.md` for the full philosophy.

---

## Entry Point

When this skill is invoked, start with:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SPEC
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What are you speccing?

  1. Quick task (hours to days)
     → Clear title + optional description
     → If it fits in one sentence, just write an issue

  2. Feature (1-3 weeks)
     → Problem, solution, success metric, scope
     → Use what's helpful, skip the rest

  3. AI feature (any size)
     → Core AI questions + context requirements + behavior examples
     → Evals are non-negotiable. Model costs early.

  4. Not sure
     → Tell me what you're building, I'll help you decide

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Parse intent from context:**
- If user says "issue" or mentions a quick task → Level 1
- If user mentions a feature, project, or gives detail → Level 2
- If user mentions AI, ML, LLM, context, prompts → Level 3
- If user provides a Linear issue ID → fetch it, then determine level

**Command-line shortcuts:**
- `/spec --quick` → Skip to Level 1
- `/spec --feature` → Skip to Level 2
- `/spec --ai` → Skip to Level 3
- `/spec LIN-123` → Fetch Linear issue, determine level

---

## Level 1: Quick Task (Linear Issue)

### When to Use
- Task is clear and focused
- Can be done in hours to a few days
- Title alone is almost enough
- No ambiguity about what "done" means

### Template
Use `templates/linear-issue.md` as reference.

### Flow

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 LEVEL 1: Quick Task
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The goal: A title that makes it obvious what you're doing.
Everything else is optional.
```

**Questions to ask:**

1. **What's the action?** (Add, Fix, Design, Refactor, Remove...)

2. **What's being changed?** (The specific thing)

3. **Where?** (Optional: location in product)

**Good titles:**
- `Add CSV export to dashboard`
- `Fix: Login fails on Safari`
- `Design mobile navigation`
- `Refactor auth middleware`

**Bad titles:**
- `Export feature` (vague)
- `Bug` (what bug?)
- `Updates` (what updates?)

**When to add a description:**
- Context isn't obvious
- Specific requirements exist
- Edge cases need clarification
- Need to link to designs/specs

**When to skip description:**
- Title says it all
- Task is straightforward
- Team already understands context

### Output

Generate a clear issue ready for Linear:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ISSUE READY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Title: [Generated title]

Description:
[Optional description if needed]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What next?

  1. Create in Linear
  2. Edit title/description
  3. Add more context (→ Level 2)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**If Linear MCP available:** Offer to create the issue directly.

---

## Level 2: Feature (Lite PRD)

### When to Use
- Feature needs alignment across team
- Scope is 1-3 weeks
- Need to document problem, solution, success criteria
- More than just "implement X"

### Template
Use `templates/lite-prd.md` as reference.

### Flow

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 LEVEL 2: Feature Spec
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The goal: Shared understanding. Not completeness.

We'll answer 5 essential questions. Everything else is optional.
```

### The Essentials (Always answer)

**1. What problem are we solving?**
- 2-3 sentences
- Customer pain or opportunity
- Push for specificity

**2. For whom?**
- Specific user segment
- Not "users" - which users?

**3. How do we know this matters?**
- Evidence: research, data, feedback
- Not assumptions - what do you actually know?

**4. What are we building?**
- High-level solution
- Link to prototype if you have one (you should!)

**5. How will we know it worked?**
- 1-2 key metrics with targets
- Not "improve X" - what number?

### Optional Sections

After the essentials, offer relevant optional sections:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ESSENTIALS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

That might be all you need. Want to add any of these?

  □ Scope & Decisions (in/out of scope, open questions)
  □ Risks (assumptions, four risks check)
  □ Discovery Insights (research, data)
  □ Technical Notes (estimate, challenges, dependencies)
  □ Launch Notes (rollout strategy, communication)
  □ Timeline (Now/Next/Later)

Skip what doesn't help create shared understanding.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Output

Generate the spec in markdown:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SPEC READY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# [Feature Name]

## The Essentials

**What problem:** [2-3 sentences]

**For whom:** [Specific segment]

**Evidence:** [What you know]

**Solution:** [What you're building + prototype link]

**Success:** [Metric with target]

[Optional sections if added]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What next?

  1. Create Linear project (parent + child issues)
  2. Export markdown
  3. Go deeper (→ Level 4 options)
  4. Start over

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Level 3: AI Feature

### When to Use
- Building anything with AI/ML/LLM
- Need to define context requirements
- Need behavior examples for evals
- Cost modeling matters

### Templates
Use `templates/ai-product-spec.md` + context requirements table.

### Flow

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 LEVEL 3: AI Feature Spec
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

AI products need more upfront thinking - but not overly complex docs.

We'll cover:
  • Core AI questions (what, quality, testing, cost, failures)
  • Context requirements (what data the AI needs)
  • Behavior examples (what good/bad looks like)

Evals are non-negotiable. Model costs early.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Phase 1: Core AI Questions

Walk through these 5 questions (from `templates/ai-product-spec.md`):

**1. What's the AI doing?**
- What problem? What task?
- Push for precision: Not "recommendations" → "3 ranked options with rationale"

**2. How will you know if it's good?**
- What does "good" output look like?
- What's "bad"? What should never happen?

**3. How will you test it?**
- Eval strategy (even simple evals > no evals)
- Test dataset categories: happy path, edge cases, adversarial, boundary

**4. What will it cost?**
- Cost per query/user
- Projected at scale

**5. What happens when it