---
name: next-step-generation
description: Generate ready-to-use, context-aware prompts for the most natural next steps based on recent conversation activity. Pure reasoning skill — no MCP tool calls. Infers completion state, suggests primary continuation, and offers 2-3 ranked alternatives.
contracts:
  - grep: "NextStepRecommendation"
  - grep: "context_only"
  - grep: "copy-pasteable"
---

## Spec

λ(context: ConversationContext) → NextStepRecommendation

# Next-Step Generation

**Infer what comes next from conversation context and generate immediately executable prompts.**

---

## When to Apply This Skill

Use this skill after any significant action completes:

- A file was edited and tests have not yet run
- Tests passed and changes have not been committed
- A plan was written and Stage 1 has not started
- An error occurred and a fix has not been applied
- A stage completed and the next stage is ready

---

## Step 1: Assess Completion State

Read the last 5–10 messages and classify the current state:

| State | Signal |
|-------|--------|
| `fully_complete` | Task finished with confirmation; natural handoff point |
| `partially_complete` | Task started but not done; continuation obvious |
| `blocked` | Waiting for user decision or missing information |
| `error_state` | Last action failed; fix is the immediate priority |

---

## Step 2: Infer the Primary Next Step

Apply the following inference rules in priority order:

```
error_occurred          → fix_the_error (include error message in prompt)
file_edited             → run_tests (name the test command if known)
tests_passed            → commit_changes (suggest commit message)
plan_written            → execute_stage_1
stage_N_complete        → execute_stage_N+1
implementation_done     → write_tests
tests_written           → run_tests
build_failed            → fix_build_error
docs_outdated           → update_docs
pr_ready                → create_pull_request
```

For the inferred primary step, craft a complete, copy-pasteable prompt that includes:

- The specific action to take
- Any `@file` references relevant to the context
- The expected outcome
- No unfilled placeholders

---

## Step 3: Generate Alternatives

Suggest 2–3 ranked alternative next steps for situations where the primary path is not the only valid option. Rank by likelihood of user intent. Common alternative clusters:

- `tests_passing` → [refactor, update_docs, optimize, create_pr]
- `planning_phase` → [start_implementation, review_plan, gather_more_requirements]
- `implementation_done` → [write_tests, update_docs, request_review]

---

## Step 4: Format Output

Present results in this structure:

```
## Recommended Next Step

**[Action label]**
[Ready-to-use prompt — complete, no placeholders]

Rationale: [1-sentence justification from recent context]
Estimated time: [< 5 min | 15–30 min | 1+ hour]

---

## Alternatives

1. **[Alternative 1]** — [one-line prompt or action description]
2. **[Alternative 2]** — [one-line prompt or action description]
3. **[Alternative 3 — optional]** — [one-line prompt or action description]
```

---

## Constraints

- `context_only`: infer from conversation; do not call any external tools
- `ready_to_use`: every prompt must be complete and copy-pasteable
- `concise`: primary recommendation + at most 3 alternatives
- `non_executable`: suggest ∧ ¬implement
- `evidence_based`: every suggestion must be grounded in recent context
- `file_aware`: include `@file` references when files are clearly relevant