Next Action

/next — Next Action Recommender

Dominant Variable

Is the proposed action actually high-impact based on current project state? — it must come from measured files, not guesses.

Purpose

Reads current project state and proposes the top 3 next actions by impact. Different from stepback (direction check) — stepback asks "am I doing the right thing right now", this asks "what should I do next". Different from session-start (handoff load) — session-start restores the prior session, this recommends actions from current state.

Discard if: right after session start (session-start already loaded the handoff + output state). User already gave a specific task.

Key Assumptions

1. Project has a CLAUDE.md — if broken: propose from git status alone (reduced scope).
2. Is a git repository — if broken: propose from filesystem scan alone.

Trigger

• /next
• "what should I do next"
• "next action"

Workflow

Step 1: Collect State (parallel, 30s cap)

Read the following 5 sources. Skip missing files.

1. memory/session-handoff-LATEST.md — "What to do now" section
2. git status --short — uncommitted changed files
3. git log --oneline -5 — recent work flow
4. tasks/lessons.md — conf≥0.7 lessons stale 30+ days (need re-application)
5. docs/STATE.md or ~/.claude/STATE.md — PENDING blockers

Step 2: Derive Candidates

Extract action candidates from collected data. Check each candidate's own underlying source for freshness (the specific lesson's seen date, the specific commit referenced) — not just whether the handoff file as a whole is old:

• Handoff "what to do now" → candidate as-is, but verify the specific file/commit it references is still current
• Uncommitted files → "commit + push" or "needs verification"
• PENDING blocker trigger satisfied → "resolve blocker"
• Stale lesson → "re-apply/verify lesson"
• git log pattern → "continue ongoing work" or "pivot direction"

Step 3: Sort by Impact

Narrow candidates to 3. Sort criteria:

1. Urgency — resolve blocker > verify uncommitted > handoff item
2. Dependency — prerequisites for other work take priority
3. Timeliness — time-sensitive items (data collection after market close, pre-deploy verification, etc.)

Step 4: Output

## Next Actions

1. **[action]** — [1-line rationale. State which source it came from]
2. **[action]** — [rationale]
3. **[action]** — [rationale]

Pick a number to proceed immediately.

Output and stop immediately. If the user picks a number, start that work.

Scope Boundary

Invariants (never violate)

1. Proposal only, never execute: recommend an action but never start it directly. Only proceed once the user picks. Violation → work executed without user intent.
2. Evidence-based proposals: derive candidates only from git status/Glob/Read results. Never guess "this is probably needed". Violation → phantom proposals for nonexistent files/issues.
3. 3-item cap: even with 10 candidates, narrow to 3. Prevents choice overload. Violation → user can't choose and defaults to "just handle it yourself".
4. 10-line cap: output exceeding 10 lines is over-explaining. Violation → no longer distinguishable from stepback.

Error Recovery

Rationalization Table

Truthful Reporting

1. no mock deception: never conclude "nothing to do" without actually reading files.
2. no silent brokenness: if a source fails to read, state ⚠️ failed to read [source name] explicitly.

Principles

• Current state is truth — the filesystem is authoritative, not memory
• Proposal is light, execution is heavy — this skill stays on the light side