# Beads Checkpoint

> Session wind-down action to capture learnings into issue graph and prepare for handoff.

- Skill: `justin-delano/beads-checkpoint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add justin-delano/beads-checkpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justin-delano/beads-checkpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: justin-delano (https://skillmd.com/u/justin-delano)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/justin-delano/beads-checkpoint

---

# Session checkpoint

Action prompt for session wind-down.
Capture learnings into the issue graph before context is lost.

**Purpose**: End of session status updates and handoff preparation.
If you need to refactor the issue graph structure during checkpoint (e.g., split epics, merge issues, restructure dependencies), use beads-evolve first, then complete the checkpoint workflow.

## Run wind-down diagnostics

Execute these commands now:

```bash
# Current state (compare to session start)
bd status

# What changed this session
bd activity

# Epic progress change
bd epic status

# Health check before commit
bd dep cycles
```

The activity feed shows what happened this session.
Epic status shows progress advancement.
Cycle check prevents committing a corrupted graph.

For structured session summary:

```bash
# Create repo-specific temp file
REPO=$(basename "$(git rev-parse --show-toplevel)")
SUMMARY=$(mktemp "/tmp/bd-${REPO}-checkpoint.XXXXXX.json")
bv --robot-triage > "$SUMMARY"

# Session-relevant extractions
jq '.quick_ref' "$SUMMARY"                    # current counts
jq '.project_health.graph_metrics' "$SUMMARY" # health metrics
jq '.stale_alerts' "$SUMMARY"                 # attention needed

# Clean up when done
rm "$SUMMARY"
```

## Scale-aware session summary

Determine session scope by counting issues touched:

```bash
# Count issues modified this session (from activity feed)
bd activity | grep -E "^[→✓✗⊘+]" | wc -l
```

Tailor summary depth to session scope:

**Small sessions (1-3 issues touched)**:
- Full detail on each change with complete before/after state
- Include full descriptions for modified issues
- Show complete dependency changes with rationale

**Medium sessions (4-10 issues touched)**:
- Summary table of changes by category:
  - Closed: list with brief completion notes
  - Updated: list with what changed
  - Created: list with traceability
  - Dependencies: count of additions/removals
- Highlight key closures and discoveries

**Large sessions (10+ issues touched)**:
- Epic-level aggregation of changes
- Statistics only: "8 closed, 3 created, 12 dependencies modified"
- Only highlight critical changes:
  - Blockers discovered during work
  - Scope corrections that affect downstream
  - Priority changes based on new understanding
- Per-epic progress deltas: "Domain layer: 42% → 58% (+5 closed)"

Determine scope tier:

```bash
# Rough session scope from recent activity
bd activity --limit 50 | head -20
```

## Graph health verification

Before committing, verify graph integrity:

```bash
# Must be zero — cycles corrupt the graph
bd dep cycles

# Check for structural issues
bd lint

# Confirm ready queue makes sense
bd ready | head -5
```

If cycles are detected:

```bash
# Identify the cycle
bd dep cycles --verbose

# Break the cycle by removing the inappropriate dependency
bd dep remove <upstream> <downstream>
```

If lint issues are found, resolve before committing.
This prevents corrupting the graph during wind-down.

## Reflect

Consider what was learned this session that the issue graph does not yet reflect.

**Scope changes**
- Was the work larger or smaller than the issue described?
- Did implementation reveal complexity not anticipated?
- Should the issue description be updated to reflect actual scope?

**Discovered work**
- Were bugs found during implementation?
- Was technical debt identified that should be tracked?
- Are there follow-up enhancements worth capturing?

**Dependency corrections**
- Were any listed blockers not actually blocking?
- Were hidden prerequisites discovered?
- Can work that was assumed sequential actually proceed in parallel?

**Priority shifts**
- Did this work reveal that other issues are more/less critical than assigned?
- Were any P3 items actually critical blockers?
- Were any P1 items actually low-impact?

## Priority recalibration

If reflection revealed priority mismatches, update before committing:

```bash
# Issue proved more critical than marked
bd update <id> --priority 1

# Issue proved less critical than marked
bd update <id> --priority 3

# Add context for the change
bd comments add <id> "Priority adjusted: discovered this blocks X during implementation"
```

Common recalibration patterns:
- Infrastructure issues often prove higher priority once downstream work begins
- Optional enhancements sometimes prove necessary for core functionality
- Assumed blockers sometimes prove to have workarounds

## Capture

For each learning identified above, execute the appropriate update.

**Scope/understanding changes:**
```bash
bd update <issue-id> --description "Revised: <what changed and why>"
```

**Discovered issues:**
```bash
# Create with traceability to current work
bd create "<title>" -t <bug|task|feature> -p <priority>
bd dep add <new-id> <current-issue-id> --type discovered-from
```

**Dependency corrections:**
```bash
# Remove false dependencies
bd dep remove <not-actually-blocking> <issue-id>

# Add discovered dependencies
bd dep add <actual-blocker> <issue-id>
```

**Progress state** (if work incomplete):
```bash
bd comments add <issue-id> "Checkpoint: <summary of state>"
```

**Completed work:**
```bash
# Option A: Close with reason
bd close <issue-id> --reason "Implemented in commit $(git rev-parse --short HEAD). <any notable learnings>"

# Option B: Close and see what was unblocked
bd close <issue-id> --reason "Implemented in..." --suggest-next

# Option C: Separate close and comment
bd close <issue-id>
bd comments add <issue-id> "Implemented in commit $(git rev-parse --short HEAD). <learnings>"
```

## Unblock chain visibility

When closing issues, show the cascade effect:

```bash
# See what completing this unblocked
bd close <id> --reason "..." --suggest-next

# Show full unblock chain
bd dep tree <closed-id> --direction up
```

Extract structured unblock data:

```bash
# Count direct and transitive unblocks
bd dep tree <closed-id> --direction up --json | jq '{
  direct: [.children[] | .id],
  direct_count: [.children[]] | length,
  total_downstream: [.. | .id? // empty] | unique | length
}'
```

Present the cascade:
- "Closing nix-50f.2 unblocked 3 issues (nix-50f.1, nix-l2a.2, nix-l2a.5)"
- "These 3 issues unblock 7 more downstream"
- "Total downstream impact: 10 issues now closer to ready"

This demonstrates session impact and helps users understand graph flow.

## Epic impact aggregation

For medium and large sessions, show epic-level progress change:

```bash
# Epic progress overview
bd epic status
```

Present as progress deltas:
- "Domain layer: 42% → 58% (closed 5 issues)"
- "Infrastructure: 20% → 35% (closed 3 issues, created 2)"
- "Frontend: unchanged (0 issues touched)"

For large sessions, aggregate by epic rather than listing individual issues:

```bash
# Extract issues by epic from activity
bd activity | grep "✓" | while read line; do
  id=$(echo "$line" | awk '{print $2}')
  bd show "$id" --short
done
```

This provides high-level progress visibility without overwhelming detail.

## Handoff

Prepare for the next session to pick up cleanly.

**If work is complete:**
```bash
# Option A: Close and immediately see what was unblocked
bd close <issue-id> --reason "Implemented in..." --suggest-next

# Option B: Manual review of dependencies
bd dep tree <completed-id> --direction up

# Check if any epics can close
bd epic close-eligible --dry-run
```

Review unblocked issues — do their descriptions need updating given what was learned?

**If work is incomplete:**

Leave a checkpoint comment on the in-progress issue:
```bash
bd comments add <issue-id> "$(cat <<'EOF'
Checkpoint: <date/session identifier>

Done:
- <what was accomplished>

Remaining:
- <what still needs to be done>

Learnings:
- <key insights that affected approach>

Suggested next steps:
- <where to pick up>
EOF
)"
```

Note: Use `bd update <id> --claim` to atomically claim an issue when resuming work (sets assignee + status to in_progress, fails if already claimed).

## Narrative handoff synthesis

Produce a prose summary for the next session:

```
Session Summary:

Completed:
- <issue-id>: <brief description of what was implemented>
- <issue-id>: <brief description>

Discovered:
- <issue-id>: <why this was created, what triggered discovery>

Learned:
- <key insight that changed understanding>
- <assumption that proved incorrect>

Next:
- Recommended starting point: <issue-id> (<why this is the logical next step>)
- Alternative entry points: <issue-id>, <issue-id>

Warnings:
- <blockers discovered but not resolved>
- <scope risks identified>
- <concerns that may affect future work>
```

This mirrors beads-orient's synthesis section but for session end.
The next session can use this summary plus `/issues:beads-orient` to quickly resume.

## Final commit

Execute the commit sequence:

```bash
# Validate beads database integrity
bd hooks run pre-commit

# Ensure DB file is staged
git add .beads/issues.jsonl

# Commit with meaningful message
git commit -m "chore(issues): <describe what changed>"
```

The commit message should explain WHAT changed in the issue graph, not just generic sync messages.

**Small sessions**: Name specific issues
- "chore(issues): close bd-xyz auth implementation, discover bd-abc blocker"

**Medium sessions**: Summarize by category
- "chore(issues): close 5 domain issues, update infrastructure dependencies"

**Large sessions**: Epic-level summary
- "chore(issues): advance domain epic to 58%, infrastructure sprint complete"

## Verify next work is discoverable

Before ending the session, ensure the next agent can pick up cleanly via `/issues:beads-orient`.

```bash
# Quick check of top recommendation
bv --robot-triage | jq '.quick_ref'

# Or minimal: just the top pick
bv --robot-next

# Review its description
bd show <top-recommendation-id>
```

If the description is stale or incomplete based on what was learned this session:
```bash
bd update <top-recommendation-id> --description "Updated: <incorporate session learnings that affect this issue>"
```

This applies whether work was completed or interrupted:
- **Completed milestone**: Next issue's description should reflect any context discovered during the completed work
- **Interrupted work**: Current issue should have checkpoint comment, AND next logical issue should be accurate

The issue graph becomes the handoff — no complex session notes needed.
When descriptions are accurate, `/issues:beads-orient` in the next session will find actionable, up-to-date work.

## Summary for user

Provide the user a summary scaled to session scope.

**Small sessions**: Full detail
- Issues closed: <list with completion notes>
- Issues updated: <list with what changed>
- Issues created: <list with traceability>
- Dependencies modified: <list with rationale>
- Unblock cascade: <what is now ready>

**Medium sessions**: Category summary
- Closed: X issues (<key ones named>)
- Updated: Y issues
- Created: Z issues
- Dependencies: N additions, M removals
- Epic progress: <deltas for affected epics>
- Next session: <top recommendation>

**Large sessions**: Executive summary
- Statistics: "8 closed, 3 created, 12 dependencies modified"
- Epic progress: <deltas>
- Key changes: <only critical items>
- Next session: <top recommendation with rationale>

The next session can run beads-orient to see the updated project state.

---

*Reference docs (read only if deeper patterns needed):*
- beads-evolve — comprehensive adaptation patterns
- beads — comprehensive reference for all beads workflows and commands