Create Linear Spec

Create Linear Spec

Iron Law: Same process as /spec, different output target. Discovery Mode → Linear Project.

Overview

This skill runs the brainstorm skill in Discovery Mode and outputs the result to a Linear Project instead of a file.

/spec [feature]           → brainstorm (Discovery) → docs/specs/*.md
/create-linear-spec       → brainstorm (Discovery) → Linear Project

Both use the same process. Only the output differs.

The Spec Rule

A spec contains WHAT and WHY. Never HOW. Never rejected decisions.

Content Guidelines

Project descriptions should be CLEAR and FOCUSED:

✅ GOOD: "Users need real-time notifications so they don't miss important updates"
❌ BAD:  "We considered polling but rejected it due to performance concerns"

What Goes Where

No Code in Specs

Projects contain prose and diagrams only. No code examples, no pseudo-code.

✅ GOOD: "The system validates user input before processing"
✅ GOOD: Mermaid diagram showing data flow
❌ BAD:  `if (!isValid(input)) throw new Error()`

Use /create-linear-design for technical approach with code patterns.

The Workflow

Step 1: Run Discovery Mode (Brainstorming Skill)

This is identical to /spec:

1. EXPLORE    → What problems exist? Who has them?
2. BRAINSTORM → What are ALL the things this could do?
3. PRIORITIZE → What's essential vs nice-to-have? (MoSCoW)
4. SPECIFY    → Write user stories + acceptance criteria
5. VALIDATE   → Review with user before creating

Step 2: Explore the Problem Space

## Problem Exploration

**Who has this problem?**
- Primary user: [persona]
- Secondary users: [others affected]

**What's the pain today?**
- [Current workaround 1]
- [Current workaround 2]

**What triggers the need?**
- [Trigger event 1]

**What does success look like?**
- [Outcome 1]
- [Outcome 2]

Step 3: Brainstorm Requirements

Generate ALL possible requirements without filtering:

## Raw Requirements (Unfiltered)

### Core Functionality
- [ ] [Requirement] - even if obvious
- [ ] [Requirement] - even if complex

### User Experience
- [ ] [UX requirement]

### Edge Cases
- [ ] What if [edge case]?

Quantity over quality at this stage.

Step 4: Prioritize (MoSCoW)

## Prioritized Requirements

### Must Have (P0) - Without these, feature is useless
- [ ] [Requirement 1]

### Should Have (P1) - Important but not critical
- [ ] [Requirement 2]

### Could Have (P2) - Nice to have
- [ ] [Requirement 3]

### Won't Have (This Release)
- [Requirement 4] - Reason: [why deferred]

Step 5: Write User Stories

## User Stories

### US-1: [Title]

**As a** [user type]
**I want to** [action]
**So that** [benefit]

**Acceptance Criteria:**
- [ ] Given [context], when [action], then [result]
- [ ] Given [context], when [action], then [result]

Step 6: Validate Before Creating

Show the user the complete spec for approval:

## Proposed Linear Project

**Name:** [Feature Name]
**Summary:** [One-line summary, max 255 chars]

**Description:** (Full spec below)

---
[Full spec content]
---

Create this Linear Project? I can adjust before creating.

Step 7: Select Initiative & Create Linear Project

List available initiatives:

mcp__linear-server__list_projects({ state: "started", limit: 50 })

Once approved, use Linear MCP:

mcp__linear-server__create_project({
  name: "[Feature Name]",
  summary: "[One-line summary]",  // Max 255 chars
  description: `[Full spec content in Markdown]`,
  team: "[Team Name]",
  initiative: "[Initiative ID]",  // Optional
  state: "planned"
});

Step 8: Confirm Creation

## Linear Spec Created

**Project:** [Feature Name]
**Team:** [Team Name]
**Initiative:** [Initiative Name]
**URL:** https://linear.app/[workspace]/project/[slug]

**Next Steps:**
- Technical approach: `/brainstorm how to implement [feature]`
- Create plan: `/plan [feature]`
- Sync plan to Linear: `/create-linear-plan`

Project Description Template

The project description should be clear, focused, and free of clutter.

# [Feature Name]

## Why This Matters
[2-3 sentences on the problem being solved and why it's important]

## What We're Building
[Clear description of the solution - prose only, no code]

## Target Users
- **Primary**: [Who] - [What they need]
- **Secondary**: [Who] - [What they need]

## Success Metrics
| Metric | Current | Target |
|--------|---------|--------|
| [Metric] | X | Y |

---

## User Stories

### US-1: [Title]

**As a** [user type]
**I want to** [action]
**So that** [benefit]

**Acceptance Criteria:**
- [ ] Given [context], when [action], then [result]
- [ ] Given [context], when [action], then [result]

### US-2: [Title]
[Same format]

---

## Scope Boundaries
- ✅ **In scope**: [What IS included]
- ❌ **Out of scope**: [What is NOT included - without explaining why]

## Open Questions
- [ ] [Question needing resolution]

Notice what's NOT in the template:

• No "rejected alternatives" section
• No "decision log" in description
• No code snippets
• No technical implementation details

Creating Supporting Documents (Optional)

If you have valuable context that shouldn't clutter the main description, create separate documents:

// Decision Log (if many alternatives were considered)
mcp__linear-server__create_document({
  title: "[Feature] Decision Log",
  project: "project-uuid",
  content: `# Decision Log

## [Decision 1]: [Topic]
**Chosen:** [What we picked]
**Rejected:**
- [Alternative 1] - [Why rejected]
- [Alternative 2] - [Why rejected]

## [Decision 2]: [Topic]
...`
});

Only create these documents if the context is valuable for future reference. Don't create them just to have them.

Example

User says: /create-linear-spec user notifications

Steps 1-5 - Discovery Mode:

Problem: Users miss important updates, have to refresh manually
Who: All authenticated users
Triggers: New message, status change, mention

Requirements (brainstormed):
- Real-time in-app notifications
- Email fallback for away users
- Notification preferences
- Read/unread status
- Notification center
- Push notifications
- Do not disturb
- Digest mode

Prioritized:
- P0: In-app real-time, read status
- P1: Email fallback, preferences
- P2: Push, digest mode

Step 6 - Validate:

## Proposed Linear Project

**Name:** User Notifications
**Summary:** Real-time notifications for important events with email fallback

**Description:**
[Full spec with 4 user stories, acceptance criteria, metrics]

Create this Linear Project?

Step 7 - Create:

mcp__linear-server__create_project({
  name: "User Notifications",
  summary: "Real-time notifications for important events with email fallback",
  description: "[Full spec content]",
  team: "Engineering",
  initiative: "app-beta-uuid",
  state: "planned"
})

Step 8 - Confirm:

## Linear Spec Created

**Project:** User Notifications
**URL:** https://linear.app/pea/project/user-notifications

Next: `/brainstorm how to implement notifications`
Then: `/plan notifications` → `/create-linear-plan`

Quick Reference

PROCESS: Same as /spec (brainstorm Discovery Mode)
OUTPUT:  Linear Project (spec in description)
TOOLS:   mcp__linear-server__create_project

1. EXPLORE    → Problem space
2. BRAINSTORM → All requirements
3. PRIORITIZE → MoSCoW (P0/P1/P2)
4. SPECIFY    → User stories + AC
5. VALIDATE   → User approval
6. SELECT     → Choose initiative
7. CREATE     → Linear Project
8. CONFIRM    → Return URL

CONTENT RULES:
✅ WHAT and WHY only
✅ Prose and diagrams
✅ User stories with AC
❌ NO code snippets
❌ NO rejected alternatives
❌ NO implementation details
❌ NO decision logs (use separate document)

Red Flags - STOP

• Skipping Discovery Mode and just converting a file
• Adding implementation details to spec
• Including code snippets in project description
• Including rejected alternatives in main description
• Bloating description with decision logs
• No user stories, just feature list
• Missing acceptance criteria
• No prioritization
• Creating without user validation

Content Audit Checklist

Before creating the project, verify:

• No code in description (prose and diagrams only)
• No rejected decisions (move to separate document if valuable)
• Clear WHAT and WHY - reader understands the goal in 30 seconds
• Concise - no unnecessary sections or bloat
• User stories have acceptance criteria

Integration

Uses:

• brainstorm skill (Discovery Mode) - Same process
• Linear MCP - Output target

Mirrors:

• /spec - Same process, different output (file vs Linear)

Pairs with:

• /brainstorm how... - Technical approach after spec
• /create-linear-plan - Implementation issues