Next Task

Find work from beads issues.

Architecture Note: This skill uses beads as the source of truth for session state. Use /comment to save session notes to the current task.

Decision Tree

/next
├── $ARGUMENTS is issue-id? → Claim → Display → ASK ACTION
├── Beads installed?
│   ├── No → Suggest /project-init
│   └── Yes → Check in_progress
│       ├── Single issue → Display → ASK ACTION
│       └── Multiple → ASK FOCUS → Display → ASK ACTION
├── Beads ready? → Smart Pick → ASK PICK → Display → ASK ACTION
└── Nothing → Offer to create new work

AskUserQuestion Guide

This skill uses AskUserQuestion 3 times, each for a distinct purpose:

Step	Header	Purpose	When
ASK FOCUS	Focus	Choose which in-progress task to focus on	Multiple in-progress issues
ASK PICK	Pick	Choose which ready task to claim	Multiple ready tasks with close scores
ASK ACTION	Action	Decide what to do with the displayed task	Always, after displaying any task

Step 1: Check Arguments

Case A: Issue ID provided

If $ARGUMENTS is provided, check if it's a beads issue ID:

br show "$ARGUMENTS" 2>/dev/null | head -1

If valid, claim and display it:

br update "$ARGUMENTS" --status=in_progress
br show "$ARGUMENTS"

Display the issue using the Display Format below, then call AskUserQuestion as specified.

Case B: No arguments

Continue to Step 2.

Step 2: Check Work Sources

2a: Check for Beads

test -d .beads && echo "beads:yes" || echo "beads:no"

If beads exists, check for in-progress work:

br list --status=in_progress 2>/dev/null

If SINGLE in-progress issue found:

Show it directly without asking:

br show <issue-id>

Display the issue using the Display Format below, then call AskUserQuestion as specified.

If MULTIPLE in-progress issues found:

USE AskUserQuestion:

{
  "questions": [{
    "question": "Which issue are you actively working on?",
    "header": "Focus",
    "options": [
      {"label": "<issue-1-id>", "description": "<title-1>"},
      {"label": "<issue-2-id>", "description": "<title-2>"}
    ],
    "multiSelect": false
  }]
}

Display the selected issue using the Display Format below, then call AskUserQuestion as specified.

If no in-progress issue, check for ready work:

br ready --limit 5 2>/dev/null

Note the ready issues count for Step 3.

2b: Not Installed

If no beads directory:

NO WORK TRACKING CONFIGURED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Beads is not configured in this project.

Run /project-init to set up issue tracking across sessions.

Or manually:
- br init          # Initialize beads

STOP.

Step 3: Smart Pick from Ready Work

3-pre: Epic Context Priority

Before selecting from general ready work, check conversation context:

1. If the user mentioned an epic ID in this conversation:

   • Check for open children of that epic
   • Suggest the next unclaimed child

2. Otherwise, proceed to 3a.

3a: Score and Rank

1. Get ready tasks (returns JSON array of issue objects):

br ready --json 2>/dev/null

2. For each ready task, get dependents count:

br show <task-id> --json 2>/dev/null

IMPORTANT: br show --json returns a JSON array [{...}], even for a single issue. Always access the first element. Use jq (never inline Python — shell escapes break !=):

br show <task-id> --json 2>/dev/null | jq '(if type == "array" then .[0] else . end) | (.dependents // []) | length'

3. Calculate score for each task:

score = (dependents_count × 3) + priority_weight + epic_recency_bonus

Where:
- dependents_count: how many tasks get unblocked when this completes
- priority_weight: P0=5, P1=3, P2=2, P3=1, P4=0
- epic_recency_bonus: +2 if same epic as recently completed task in this session

4. Sort by score descending.

5. If single clear winner (score gap > 3):

Show recommendation directly:

RECOMMENDED NEXT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

→ <issue-id>: <title>
  Score: <N> (unblocks <M> tasks, P<X>)

Claim this task? (yes to claim, or "skip" for full list)

6. If multiple close scores (gap <= 3):

Show ranked list with scores:

READY WORK (ranked by impact)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. <id>: <title> — score <N> (unblocks <M>)
2. <id>: <title> — score <N> (unblocks <M>)
3. <id>: <title> — score <N>

USE AskUserQuestion (ASK PICK):

{
  "questions": [{
    "question": "Which task should we pick up next?",
    "header": "Pick",
    "options": [
      {"label": "<id-1>", "description": "<title-1> — score <N> (unblocks <M>)"},
      {"label": "<id-2>", "description": "<title-2> — score <N> (unblocks <M>)"}
    ],
    "multiSelect": false
  }]
}

After selection, claim the task (br update <id> --status=in_progress), display it using Display Format, then call ASK ACTION.

3b: Nothing Ready

If no ready beads issues:

NO WORK AVAILABLE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

No ready beads issues found.

To add work:
- br create --title "..." --type task --priority 2

Display Format for Beads Issue

Branch Detection (for Display)

If the task has a parent epic:

1. br show <parent-id> --json → find label matching branch:*
2. If found → show branch name (e.g., feat/tdd-integration)
3. If not found → show (auto: will create on /impl)

If no parent → omit the Branch line entirely.

When displaying a claimed issue, output this text block:

NEXT TASK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Issue:   [issue-id]
Title:   [title]
Type:    [type] | Priority: [priority]
Status:  in_progress
Branch:  [branch name]

Description:
[issue description — first 10 lines, or full if short]

Related:
- Parent: [parent-id if exists]
- Depends on: [dependencies if any]
- Blocks: [blocked issues if any]

💡 Rename session: /rename [issue-id]: [title (truncated to ~40 chars)]

The rename line helps track which task this session is working on. Generate it by combining the issue ID and a short version of the title (truncate at ~40 chars if needed). Example: /rename nzas.2: Native SQLite + JSONL storage

After Display: ASK ACTION (REQUIRED)

After displaying any issue, you MUST call AskUserQuestion with exactly these options. Do NOT output your own text, questions, or suggestions instead.

{
  "questions": [{
    "question": "What would you like to do with this task?",
    "header": "Action",
    "options": [
      {"label": "Implement", "description": "Start /impl for this task"},
      {"label": "Implement epic", "description": "Start /impl --epic <parent-id> for all children"},
      {"label": "Switch task", "description": "Pick a different task instead"},
      {"label": "Just show", "description": "No action needed, just wanted to see the task"}
    ],
    "multiSelect": false
  }]
}

Option rules:

• "Implement epic" — only include if the issue has a parent epic. Replace <parent-id> with actual ID.
• "Switch task" — runs br ready --limit 5 and shows ASK PICK to select a different task.

When user selects an action, execute it immediately using Skill tool:

• Implement → Skill(skill: "mindcontext-core:impl")
• Implement epic → Skill(skill: "mindcontext-core:impl", args: "--epic <parent-id>")
• Switch task → show ready tasks via ASK PICK flow (Step 3)
• Just show → STOP, do nothing more

Error Handling

If any br command fails, show the error but continue gracefully:

Warning: br command failed - [error message]
Continuing without beads tracking.