---
name: linear-plan-tracker
description: Manages Linear ticket lifecycle for plan work. Searches for related tickets, creates tickets when missing, and updates board status through workflow states (Design spec → Implementation spec → Agent implementing → Agent reviewing). Invoked before brainstorming, writing-plans, executing-plans, or code review per CLAUDE.md workflow rules.
---

# Linear Plan Tracker

Every piece of plan work in this project has a corresponding Linear ticket. This skill ensures tickets stay in sync with what the agent is doing — finding or creating the right ticket, then moving it to the correct workflow state before the actual work begins.

Without this, tickets fall out of sync and the human loses visibility into what's being worked on. A quick status update at the start of each phase keeps everything aligned with minimal overhead.

## Activity to Status Mapping

| What you're about to do | Linear status to set |
|--------------------------|----------------------|
| Create a design spec (brainstorming) | **Design spec** |
| Write an implementation plan (writing-plans) | **Implementation spec** |
| Implement code from a plan (executing-plans) | **Agent implementing** |
| Review an implementation (code review) | **Agent reviewing** |

## Workflow Ordering

Statuses are ordered. Use this to evaluate guard rails:

```
Backlog (1) → Design spec (2) → Implementation spec (3) → Agent implementing (4) → Agent reviewing (5) → Done (6)
```

"Later" means a higher position number. Moving from position 4 to position 3 is backward movement.

## Step 1: Correlate Document ↔ Ticket

Find the Linear ticket that corresponds to the current work. Try these paths in order — stop at the first that succeeds:

### Path A: Direct ticket reference
The user mentioned a ticket ID (e.g., "implement RII-23"). Use `mcp__linear__get_issue` directly. One call, done.

### Path B: Document → Ticket
Check if a relevant spec/plan file exists for this topic. If so, read the file and look for:
- `**Linear issue:** [RII-XX](...)` in the header
- Any `RII-\d+` reference in the document

This path is worth trying even before Path C — if the user says "design the observability stack" and you know there's a file at `docs/superpowers/specs/*observability*`, read it first. It may already contain a Linear reference, saving you a search.

### Path C: Topic-based search
If no ticket reference was found via A or B:
1. Call `mcp__linear__list_issues` **once** with relevant keywords from the user's request
2. Pick the best title match from the results
3. If there's a clear match, call `mcp__linear__get_issue` on that one ticket for full details
4. If multiple candidates could match, present them to the user and ask which one
5. If no match at all, proceed to Step 2 (create ticket)

Do not make multiple `list_issues` calls with different query variations. One search with the most descriptive keywords is sufficient.

**Examples:**
- "implement RII-23" → Path A
- "write an impl plan for parquet backtesting" → Path B (check the existing impl plan file for a `**Linear issue:**` header)
- "let's design the observability stack" → Path B first (check `docs/superpowers/specs/*observability*`), then Path C if no file/reference found

### Correlation failed
- **For design or implementation plan work:** Ask if the user wants a ticket created (Step 2)
- **For implementation or review work:** Warn — these phases should trace back to an existing ticket

## Step 2: Create Ticket (when needed)

1. Suggest a title, type label (Bug/Feature/Improvement), component label(s), and priority
2. Get user confirmation before creating
3. Create using `mcp__linear__save_issue` with:
   - Team: Riive-home, Project: Weatherman v1
   - Status set from the activity mapping
   - Labels from the reference tables below
   - Description including spec file path pointers:
     ```
     **Design spec:** `docs/superpowers/specs/YYYY-MM-DD-<name>-design.md`
     **Impl spec:** `docs/superpowers/plans/YYYY-MM-DD-<name>-impl.md`
     ```
4. Add `**Linear issue:** [RII-XX](url)` to the spec/plan document header — this enables Path B for all future sessions

## Step 3: Update Ticket Status

1. Determine the target status from the activity mapping
2. Compare the ticket's current position to the target position using the workflow ordering above
3. Apply guard rails:

| Situation | Action |
|-----------|--------|
| Already at target status | Skip update, confirm and proceed |
| Current is earlier than target (forward move) | Update status with `mcp__linear__save_issue` |
| Skipping multiple positions forward (e.g., Backlog → Agent implementing) | Update, but note to the user that intermediate steps may have been skipped |
| Current is later than target (backward move) | Do NOT update. Warn the user that the ticket has progressed past this phase. Ask before moving backwards. |

## Step 4: Verify Bidirectional Linking

After finding or creating a ticket, quickly verify that both sides of the link exist:
- **Document → Ticket:** spec/plan file contains `**Linear issue:** [RII-XX](...)`
- **Ticket → Document:** Linear issue description contains spec file path pointers

If either link is missing, add it. This takes seconds and saves minutes of Path C searching in future sessions.

## Step 5: Confirm and Continue

One line: "Moved RII-XX to [status]" or "RII-XX already at [status]" or "Created RII-XX in [status]". Then proceed with the actual plan work.

## Pre-Design Requirements

Before design work (brainstorming phase), two things must happen in order:

1. **Run `/research_codebase`** — design specs written without codebase research propose solutions that conflict with existing patterns
2. **Use `superpowers:brainstorming`** — ensures collaborative exploration of requirements before committing to an approach

## Linear Reference Data

### Status IDs (ordered by workflow position)

| # | Status | ID |
|---|--------|-----|
| 1 | Backlog | `bd620cd0-cb22-41a1-901b-8e8e45e6eabe` |
| 2 | Design spec | `0ca6b56e-8b33-4bb1-b03c-e2b6e492cd59` |
| 3 | Implementation spec | `f71dff75-6272-48ef-951e-d9299fec5324` |
| 4 | Agent implementing | `cd16e163-0deb-4943-b39e-c8b30f7f6d61` |
| 5 | Agent reviewing | `4361c0f7-1bb7-490d-9d8e-e1ae80736ed2` |
| 6 | Done | `6d74b599-a2f7-4b8d-a8a4-6ae26b9d8e1b` |

### Type Labels

| Name | ID |
|------|-----|
| Bug | `d120b2cb-bc34-4d96-9c6b-2d910a369a2c` |
| Feature | `64e5d658-37fd-498b-ae48-93aaf1cb8af8` |
| Improvement | `3e11ab5d-c975-413d-a091-5fcd86141fac` |

### Component Labels

| Name | ID |
|------|-----|
| cli | `bda5f52b-b2dc-4551-b0f2-982bb2deed8f` |
| execution | `0001cf29-69d1-4e98-a51e-d812c7562738` |
| infrastructure | `c11ce30f-1674-4e83-ae49-15f24b493e7b` |
| observability | `efb10b92-b54a-4179-8f2f-00089fad8f80` |
| persistence | `04db71c2-bfcb-410a-a21d-98f90695d083` |
| polymarket-client | `f47c8b8a-d438-4102-b7e5-cc061f766a32` |
| strategy | `04d43616-1b06-4d4f-a6a9-89227771b3c8` |