checkpoint

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