---
name: feature-from-backlog
description: Start a new feature from Linear backlog. Refines backlog item, breaks into sub-tasks if needed, and starts work.
---

# Feature from Backlog — Linear Workflow

Refines backlog items into actionable features and starts work on them.

## Project Configuration

Read project configuration from `.claude/project.json`:
- `linear.teamId`, `linear.teamName`, `linear.projectId`

If `.claude/project.json` doesn't exist, suggest running `/setup-project` first.

## Instructions for Claude

### Step 0: Load Configuration

```bash
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
```

Read `$PROJECT_ROOT/.claude/project.json`.

### Step 1: Show Backlog Items

```
Use mcp__linear__list_issues:
- team: [from config.linear.teamName]
- project: [from config.linear.projectId]
- state: "Backlog"
- includeArchived: false
- orderBy: "updatedAt"
- limit: 20
```

Display:

```
## Backlog Items

Select an item to refine and start working on:

1. **ABC-XX**: [title]
   Priority: [priority or "Not set"]
   Size: [size or "Not estimated"]
   Description: [first line]

[... show all backlog items]

Which item would you like to work on? (Enter number or issue ID)
```

### Step 2: Refine the Selected Item

Fetch full details:
```
Use mcp__linear__get_issue with selected ID
```

**IMPORTANT: Read and display the FULL issue description.** Do NOT truncate or summarize.

Then ask clarifying questions:

```
Let's refine [Issue ID]: [Issue Title]

1. **What type of work is this?** (new feature, enhancement, integration)
2. **Who will use this?** (admins, users, API consumers)
3. **Is this large enough to need sub-tasks?** (yes/no)
4. **Any specific requirements or constraints?**
5. **Priority level?** (Critical/High/Medium/Low)
6. **Estimated size?** (Small: 1-2h / Medium: 0.5-1d / Large: 2+d)
```

### Step 3: Decide on Approach

**If simple feature (Small/Medium, no sub-tasks):** skip plan mode, go to Step 4.

**If complex feature (Large, needs sub-tasks):** do codebase research, then enter plan mode (Step 3a).

### Step 3a: Plan Mode for Complex Features

1. **Before planning**: Use the Task tool with `subagent_type="Explore"` and `thoroughness="medium"` to understand existing patterns and find similar features. Pass the refined feature description as context.

2. **Enter plan mode** using `EnterPlanMode`.

3. **Write the plan file** with this EXACT structure:

   ```markdown
   # Plan: [Issue ID] — [Issue Title]

   ## Phase 0: Setup (execute IMMEDIATELY after plan approval)

   > These steps MUST be completed before writing any code.

   ### 0.1 Update parent issue in Linear
   - Tool: `mcp__linear__update_issue`
   - id: [issue-id]
   - description: [full refined description with requirements and acceptance criteria]
   - labels: ["Feature", priority label, size label]
   - state: "Todo"
   - priority: [0-4]

   ### 0.2 Create sub-issues in Linear
   For each implementation step below:
   - Tool: `mcp__linear__create_issue`
   - team: [config.linear.teamName]
   - project: [config.linear.projectId]
   - parentId: [parent-issue-id]
   - state: "Todo"

   Sub-issues to create:
   1. [Sub-task title] — [brief description]
   2. [Sub-task title] — [brief description]

   ### 0.3 Create git branch
   ```bash
   git checkout -b feature/[ISSUE-ID]-[slugified-title]
   ```

   ### 0.4 Move issue to "In Progress"
   - Tool: `mcp__linear__update_issue`
   - id: [issue-id]
   - state: "In Progress"
   - assignee: "me"

   ## Phase 1: Implementation

   ### 1.1 [First sub-task title]
   - Files: [files to modify/create]
   - Details: [what to implement]

   ### 1.2 [Second sub-task title]
   - Files: [files to modify/create]
   - Details: [what to implement]

   ## Phase 2: Verification
   - [ ] All sub-tasks implemented
   - [ ] Build passes
   - [ ] Manual testing complete
   - [ ] Ready for `/create-pr`
   ```

4. **Exit plan mode** using `ExitPlanMode`.

5. **After plan approval**: execute Phase 0 in order (0.1 → 0.2 → 0.3 → 0.4), then display the Step 5 summary before starting Phase 1.

### Step 4: Update Linear (Simple Features)

For simple features that skipped plan mode:

```
Use mcp__linear__update_issue:
- id: [issue-id]
- description: [refined description with requirements]
- labels: [type label, priority label, size label]
- priority: [0-4]
- state: "Todo"
```

Then create branch and move to In Progress:

```bash
git checkout -b feature/[ISSUE-ID]-[slugified-title]
```

```
Use mcp__linear__update_issue:
- id: [issue-id]
- state: "In Progress"
- assignee: "me"
```

### Step 5: Display Summary

```
## Feature Ready: [Issue ID] — [Issue Title]

**Branch**: feature/ABC-XX-issue-title (created and checked out)
**Linear Status**: In Progress
**Assignee**: You

**Updated Description**:
[refined description summary]

**Sub-tasks Created** (if applicable):
- ABC-XX: [sub-task title]
- ABC-XX: [sub-task title]

Ready to start implementing! Which sub-task would you like to begin with?
```

## Best Practices

1. **Always refine before starting** — Don't jump into code without understanding
2. **Break down large features** — Anything > 1 day should have sub-tasks
3. **Add acceptance criteria** — Clear definition of "done"
4. **Estimate realistically** — Better to overestimate than under
5. **Link related issues** — Reference similar work or dependencies

## Integration with Other Skills

- **After refinement**: Branch is created — just start coding
- **For status checks**: `/new-feature` doubles as a status checker
- **When done**: `/create-pr` to create pull request
- **Check backlog size**: `/backlog` to maintain healthy backlog