checkpoint

What this skill does

# Checkpoint

Pause, assess, and surface intelligent next-step options to the user.

## When to Trigger Proactively

Suggest this skill (without being asked) when detecting:

- **Completion signal**: A feature, fix, or milestone just finished
- **Uncertainty signal**: Requirements unclear, multiple valid paths, or low confidence in current direction
- **Complexity signal**: Scope expanded, unexpected dependencies emerged, or task is taking longer than expected
- **Drift signal**: Work may have diverged from user's original intent
- **Quality signal**: Code works but may benefit from review, testing, or refactoring

## Workflow

### 1. Context Assessment

Silently evaluate the current state across these dimensions (do not output this analysis):

- **Progress**: What has been accomplished? What remains?
- **Quality**: Is the work solid, or are there rough edges?
- **Alignment**: Does recent work match what the user actually wants?
- **Uncertainty**: What assumptions were made? What's unclear?
- **Risk**: What could go wrong? What hasn't been tested?
- **Efficiency**: Is there a better path forward?

### 2. Generate Options

Based on assessment, generate 2-5 contextually-appropriate options. Draw from (but don't limit to) these archetypes:

| Archetype | When Relevant |
|-----------|---------------|
| **Commit progress** | Meaningful progress made, good stopping point |
| **Systems audit** | Complex changes, potential for bugs or regressions |
| **Prioritize/plan** | Multiple pending tasks, unclear what matters most |
| **Re-evaluate decisions** | Low confidence in recent choices, new information available |
| **Clarify with user** | Assumptions made, requirements ambiguous |
| **Test/verify** | Code works but edge cases untested |
| **Refactor/clean up** | Code functional but messy |
| **Document** | Complex logic that needs explanation |
| **Step back** | May be overcomplicating or missing simpler solution |
| **Continue current path** | Clear next step, no reason to pause |

**Option generation principles:**
- Options should be meaningfully different, not variations of the same thing
- Include at least one "continue forward" option when momentum is valuable
- Include at least one "pause and verify" option when risk is present
- Avoid analysis paralysis - fewer sharp options beat many vague ones

### 3. Select Recommendation

Choose one option as recommended. The recommendation should reflect:

- What would a thoughtful senior engineer do here?
- What reduces risk of wasted effort or rework?
- What serves the user's underlying goals (not just stated requests)?

### 4. Present via AskUserQuestion

Use AskUserQuestion with this structure:

```
Question: "What would you like to do next?"
Header: "Next step" (or contextually appropriate 1-2 words)
Options: [generated options with descriptions]
```

**Option format:**
- `label`: Action verb phrase (e.g., "Commit current progress", "Run systems audit")
- `description`: 1 sentence explaining what this involves and why it might be valuable

**Recommendation:**
- Place recommended option FIRST in the list
- Append "(Recommended)" to its label
- Include rationale in the description

### Example Output

For a scenario where a feature was just implemented but with some shortcuts:

```
AskUserQuestion:
  question: "Feature implementation complete. What would you like to do next?"
  header: "Next step"
  options:
    - label: "Review and refactor (Recommended)"
      description: "Clean up the shortcuts taken during implementation before they become technical debt. The core logic works but could be more maintainable."
    - label: "Add test coverage"
      description: "Write tests for the new feature to catch edge cases and prevent regressions."
    - label: "Commit and move on"
      description: "The feature works - commit it and tackle the next task. Can refactor later if needed."
    - label: "Walk me through what was built"
      description: "Explain the implementation so you can verify it matches your expectations before proceeding."
```

## Anti-Patterns

- **Don't overthink**: This skill should take seconds, not minutes
- **Don't list every possible option**: Curate the most valuable 2-5
- **Don't recommend "ask user" when the situation is clear**: Have a point of view
- **Don't trigger too frequently**: Reserve for genuine decision points, not every minor step
- **Don't explain the assessment process**: Just present the options naturally