Next Action Recommendation

Overview

Analyzes current project state and provides prioritized, context-aware recommendations for what to work on next. Returns actionable popkit commands with explanations.

Core principle: Don't just list commands - recommend the RIGHT command based on actual project state.

Trigger: When user expresses uncertainty ("what should I do", "where to go", "stuck") or runs /popkit:next.

When to Use

Invoke this skill when:

• User asks "what should I do next?"
• User seems stuck or unsure of direction
• User mentions "popkit" and needs guidance
• Starting a new session and need orientation
• Returning to a project after time away

Analysis Process

Step 1: Gather Project State

Collect information from multiple sources:

# Git status
git status --short 2>/dev/null

# Branch info
git branch -vv 2>/dev/null | head -5

# Recent commits
git log --oneline -5 2>/dev/null

# Fetch remotes to detect research branches
git fetch --all --prune 2>/dev/null

RECORDING: After gathering git state, record initial analysis:

from popkit_shared.utils.session_recorder import is_recording_enabled, record_reasoning
import subprocess

if is_recording_enabled():
    # Get uncommitted file count
    result = subprocess.run(
        ["git", "status", "--short"],
        capture_output=True,
        text=True
    )
    uncommitted_lines = len([l for l in result.stdout.strip().split('\n') if l])

    record_reasoning(
        step="Analyze git status",
        reasoning=f"Checked working directory, branch status, and recent activity",
        data={"uncommitted_files": uncommitted_lines}
    )

Continue bash commands:

# Check for TypeScript errors (if tsconfig exists)
if [ -f "tsconfig.json" ]; then
  npx tsc --noEmit 2>&1 | tail -10
fi

# Check for package.json (Node project)
if [ -f "package.json" ]; then
  echo "Node project detected"
fi

# Check for TECHNICAL_DEBT.md
if [ -f "TECHNICAL_DEBT.md" ]; then
  head -50 TECHNICAL_DEBT.md
fi

# Check for open GitHub issues
gh issue list --limit 5 2>/dev/null || echo "No gh CLI or not a repo"

RECORDING: After running bash commands above, record context files:

from popkit_shared.utils.session_recorder import is_recording_enabled, record_file_read
from pathlib import Path

if is_recording_enabled():
    # Record STATUS.json if it exists
    status_file = Path.cwd() / ".claude" / "STATUS.json"
    if status_file.exists():
        record_file_read(
            str(status_file),
            "Previous session context loaded",
            relevant=True
        )

    # Record TECHNICAL_DEBT.md if it exists
    tech_debt_file = Path.cwd() / "TECHNICAL_DEBT.md"
    if tech_debt_file.exists():
        record_file_read(
            str(tech_debt_file),
            "Technical debt items reviewed",
            relevant=True
        )

Step 1.5: Detect Research Branches (NEW - Issue #181)

Check for research branches from Claude Code Web sessions:

import sys
from popkit_shared.utils.research_branch_detector import (
    get_research_branches,
    format_branch_table
)
# RECORDING: Import session recording utilities
from popkit_shared.utils.session_recorder import (
    is_recording_enabled,
    record_reasoning,
    record_file_read
)

# Detect research branches
branches = get_research_branches()

# RECORDING: Log research branch detection
if is_recording_enabled():
    record_reasoning(
        step="Detect research branches",
        reasoning=f"Scanning remote branches for research content from web sessions",
        data={"branches_found": len(branches)}
    )

if branches:
    print("## Research Branches Detected\n")
    print(format_branch_table(branches))
    print("\nThese branches contain research from Claude Code Web sessions.")
    print("Use `pop-research-merge` skill to process them.")

Research Branch Patterns:

• origin/claude/research-* - Explicit research branches
• origin/claude/*-research-* - Topic-specific research
• Branches with docs/research/*.md or RESEARCH*.md files

Step 2: Detect Project Context

Identify what kind of project and what state it's in:

Step 2.5: Fetch Issue Votes (NEW)

If GitHub issues exist, fetch community votes to prioritize:

from popkit_shared.utils.priority_scorer import get_priority_scorer, fetch_open_issues
from popkit_shared.utils.session_recorder import is_recording_enabled, record_reasoning

# Fetch and rank issues by combined priority score
scorer = get_priority_scorer()
issues = fetch_open_issues(limit=10)
ranked = scorer.rank_issues(issues)

# RECORDING: Log issue prioritization
if is_recording_enabled():
    record_reasoning(
        step="Prioritize GitHub issues",
        reasoning=f"Fetched {len(issues)} issues, ranked by votes + staleness + labels",
        data={
            "total_issues": len(issues),
            "top_3_scores": [i.priority_score for i in ranked[:3]]
        }
    )

# Top-voted issues get recommendation priority
for issue in ranked[:3]:
    # issue.priority_score combines votes, staleness, labels, epic status
    print(f"#{issue.number} {issue.title} - Score: {issue.priority_score}")

Vote Weights:

• 👍 (+1) = 1 point (community interest)
• ❤️ (heart) = 2 points (strong support)
• 🚀 (rocket) = 3 points (approved/prioritized)
• 👎 (-1) = -1 point (deprioritize)

Step 3: Score Recommendations

For each potential recommendation, calculate a relevance score:

Score = Base Priority + Context Multipliers

Base Priorities:
- Fix build errors: 90
- Process research branches: 85  # NEW - important to merge findings
- Commit uncommitted work: 80
- Push ahead commits: 60
- Address open issues: 50
- Tackle tech debt: 40
- Start new feature: 30

Context Multipliers:
- Has uncommitted changes: +20 to commit
- TypeScript errors: +30 to fix
- Research branches detected: +25 to process  # NEW
- Many open issues: +10 to issue work
- Long time since commit: +15 to commit

Step 4: Generate Recommendations

Create 3-5 prioritized recommendations based on scores.

For each recommendation, provide:

1. Command - The exact popkit command to run
2. Why - Context-specific reason (not generic)
3. What it does - Brief description
4. Benefit - What user gains

Output Format

Use the next-action-report output style:

## Current State

| Indicator | Status | Urgency |
|-----------|--------|---------|
| Uncommitted | X files | [HIGH/MEDIUM/LOW] |
| Branch Sync | [status] | [urgency] |
| TypeScript | [clean/errors] | [urgency] |
| Open Issues | X open | [urgency] |

## Recommended Actions

### 1. [Primary Action] (Score: XX)
**Command:** `/popkit:[command]`
**Why:** [Specific reason based on detected state]
**What it does:** [Brief description]
**Benefit:** [What you gain]

### 2. [Secondary Action] (Score: XX)
...

### 3. [Tertiary Action] (Score: XX)
...

## Quick Reference

| If you want to... | Use this command |
|-------------------|------------------|
| Commit changes | `/popkit:git commit` |
| Review code | `/popkit:git review` |
| Get project health | `/popkit:routine morning` |
| Plan a feature | `/popkit:dev brainstorm` |
| Debug an issue | `/popkit:debug` |

## Alternative Paths

Based on your context, you could also:
- [Alternative 1]
- [Alternative 2]

Recommendation Logic

If Uncommitted Changes Detected

### 1. Commit Your Current Work
**Command:** `/popkit:commit`
**Why:** You have [X] uncommitted files including [key files]
**What it does:** Auto-generates commit message matching repo style
**Benefit:** Clean working directory, changes safely versioned

If TypeScript Errors

### 1. Fix Build Errors
**Command:** `/popkit:debug`
**Why:** TypeScript has [X] errors blocking build
**What it does:** Systematic debugging with root cause analysis
**Benefit:** Unblocked development, passing CI

If Research Branches Detected (NEW - Issue #181)

### 1. Process Research Branches
**Command:** Invoke `pop-research-merge` skill
**Why:** Found [X] research branch(es) from Claude Code Web sessions
**Branches:**
| Branch | Topic | Created |
|--------|-------|---------|
| `research-claude-code-features` | Claude Code Integration | 2h ago |

**What it does:** Merges research content, organizes docs, creates GitHub issues
**Benefit:** Research findings become actionable issues in your backlog

When research branches are detected, prompt the user:

Use AskUserQuestion tool with:
- question: "Found [X] research branch(es) from web sessions. Process them now?"
- header: "Research"
- options:
  - label: "Yes, process"
    description: "Merge findings and create issues (recommended)"
  - label: "Review first"
    description: "Show me what's in the branches"
  - label: "Skip for now"
    description: "Continue to other recommendations"
- multiSelect: false

If user selects "Yes, process" or "Review first", invoke the pop-research-merge skill.

If Open Issues Exist

### 2. Work on Open Issue
**Command:** `/popkit:dev work #[number]`
**Why:** Issue #[X] "[title]" is high priority (Score: XX)
**Votes:** 👍5 ❤️2 🚀1
**What it does:** Issue-driven development workflow
**Benefit:** Structured progress on community-prioritized work

When multiple issues exist, use priority scoring to recommend the best one:

from popkit_shared.utils.priority_scorer import get_priority_scorer
from popkit_shared.utils.session_recorder import is_recording_enabled, record_recommendation

scorer = get_priority_scorer()
ranked = scorer.rank_issues(issues)

# Recommend highest-scored issue
top = ranked[0]
print(f"Work on #{top.number} '{top.title}' (Score: {top.priority_score:.1f})")
if top.vote_breakdown:
    print(f"Community votes: {scorer.vote_fetcher.format_vote_display(top, compact=True)}")

# RECORDING: Log the recommendation
if is_recording_enabled():
    record_recommendation(
        recommendation_type="issue",
        command=f"/popkit:dev work #{top.number}",
        priority_score=int(top.priority_score),
        reason=f"Issue #{top.number} '{top.title}' has highest community priority (votes + staleness + labels)"
    )

If No Urgent Items

### 1. Check Project Health
**Command:** `/popkit:routine morning`
**Why:** No urgent items - good time for health check
**What it does:** Comprehensive project status with "Ready to Code" score
**Benefit:** Identify hidden issues before they become urgent

Quick Mode

When called with quick argument, provide condensed output:

## /popkit:next (quick)

**State:** 5 uncommitted | branch synced | TS clean | 3 issues

**Top 3:**
1. `/popkit:git commit` - Commit 5 files (HIGH)
2. `/popkit:dev work #42` - Work on "Add auth" (MEDIUM)
3. `/popkit:routine morning` - Health check (LOW)

Error Handling

Visual Style

Use components from output-styles/visual-components.md:

• Status indicators: ✓ (success), ✗ (failure), → (in progress)
• Urgency levels: HIGH (red), MEDIUM (yellow), LOW (blue), OK (green)
• Tables with status columns
• Quick reference tables

Related

• /popkit:next command - User-facing wrapper
• /popkit:routine morning - Detailed health check
• /popkit:dev brainstorm - For when direction is truly unclear
• pop-research-merge skill - Process detected research branches
• output-styles/next-action-report.md - Full output template
• output-styles/visual-components.md - Reusable visual elements
• user-prompt-submit.py - Uncertainty trigger patterns
• hooks/utils/vote_fetcher.py - GitHub reaction fetching
• hooks/utils/priority_scorer.py - Combined priority calculation
• hooks/utils/research_branch_detector.py - Research branch detection