beads-context-strategies

Use this skill when: Managing Claude Code context while working with Beads, preventing context bloat, or preserving critical workflow state across sessions

Beads Context Management Strategies

Use this skill when: Managing Claude Code context while working with Beads, preventing context bloat, or preserving critical workflow state across sessions

Overview

When working with Beads (bd CLI) across multiple sessions, strategic use of /context (preserve) and /compact (compress) commands is essential to maintain high-fidelity workflow state without hitting context limits.

The Context Problem

Without context management:

• Verbose bd JSON outputs accumulate
• Context fills with repetitive command outputs
• Critical state gets pushed out
• Lose track of complex dependency chains
• Waste time re-discovering workflow state

With strategic context management:

• Preserve only critical decisions and state
• Compress routine operations
• Maintain workflow continuity across sessions
• Keep dependency context accessible
• Recover quickly after interruptions

Two Commands, Two Purposes

/context - Preserve Critical State

Purpose: Create a checkpoint that preserves current state for future reference

Use when:

• Starting work on complex issues
• After discovering significant new work
• Before major refactoring or architectural changes
• When switching between unrelated issues
• After resolving merge conflicts
• At key decision points

Pattern:

/context "Brief description of what to preserve"

/compact - Compress Verbose State

Purpose: Summarize and remove verbose details while keeping essential information

Use when:

• After completing an issue
• After routine bd list, bd show operations
• Context approaching 75% full
• After bulk issue creation
• During long troubleshooting sessions
• After multiple dependency operations

Pattern:

/compact "What to preserve: [essentials]. What to remove: [verbosity]."

Context Preservation Points

1. Session Start

Trigger: Beginning a new session

Action:

# After: bd import + bd ready
/context "Session start: ready work queue [bd-5, bd-10, bd-15], current focus: bd-5 (implement auth), blockers: none"

Preserves:

• Available work
• Current focus
• Known blockers
• Session context

2. Complex Issue Start

Trigger: Starting work on issue with 3+ dependencies

Action:

# After: bd dep tree bd-42
/context "Working on bd-42 (refactor payment system). Depends on: bd-38 (schema), bd-40 (API). Discovered from: bd-35. Plan: [steps]"

Preserves:

• Issue context
• Dependency tree
• Implementation plan
• Discovery chain

3. Significant Discovery

Trigger: Discovering 3+ new issues during work

Action:

# After creating multiple issues
/context "Discovered from bd-50: bd-51 (validation bug, P0), bd-52 (missing tests, P2), bd-53 (docs, P3). Rationale: found during refactoring"

Preserves:

• Discovery context
• Issue priorities
• Rationale for creation
• Parent issue link

4. Architectural Decision

Trigger: Before/after major refactoring or design changes

Action:

/context "Pre-refactor: current architecture uses [X]. Planned changes: migrate to [Y]. Affected issues: bd-60, bd-61, bd-62. Risks: [list]"

Preserves:

• Current state
• Planned changes
• Impact scope
• Risk assessment

5. Issue Switching

Trigger: Switching between unrelated issues

Action:

/context "Switching: bd-70 -> bd-80. bd-70 status: [current state], next: [action]. bd-80 context: [background], plan: [approach]"

Preserves:

• State of paused issue
• Context for new issue
• Resume points
• Task continuity

6. Merge Conflict Resolution

Trigger: After resolving Beads merge conflicts

Action:

/context "Merge resolved: 5 issues remapped (bd-90->bd-95, ...), preserved dependencies, no data loss. New HEAD: [commit]"

Preserves:

• Remapping record
• Conflict resolution
• Verification steps
• Current state

Compaction Points

1. After Issue Completion

Trigger: Closed an issue

Action:

/compact "Preserve: bd-100 closed (reason: completed auth), unblocked: bd-101, bd-102. Remove: implementation details, verbose outputs."

Result:

• High-level outcome preserved
• Verbose JSON removed
• Impact preserved
• Details dropped

2. Routine Operations

Trigger: Multiple bd list, bd show commands

Action:

/compact "Preserve: current ready work [bd-110, bd-111], priorities, blockers. Remove: repetitive bd list outputs, unchanged issue details."

Result:

• Current state summary
• Removed duplication
• Essential info kept

3. Context Approaching Limit

Trigger: Context > 75% full

Action:

/compact "Preserve: active issue bd-120, dependencies, next 3 steps. Remove: completed work details, old discovery chains, routine command outputs."

Result:

• Lean, focused context
• Critical state preserved
• Old context archived

4. Bulk Issue Creation

Trigger: Created 5+ issues at once

Action:

/compact "Preserve: created issues [bd-130 to bd-135] with priorities [P0, P1, P1, P2, P3, P3], dependencies summarized. Remove: verbose JSON payloads."

Result:

• Issue list preserved
• Metadata summarized
• Verbose JSON removed

5. Long Troubleshooting

Trigger: Extended debugging session

Action:

/compact "Preserve: current hypothesis [X], tested approaches [A, B, C], next: try [D]. Remove: failed attempt details, verbose error outputs."

Result:

• Current understanding
• Progress preserved
• Dead ends summarized

Strategic Workflow Pattern

Complete multi-session workflow with context management:

SESSION START:
┌─────────────────────────────────────────────┐
│ 1. bd import -i .beads/issues.jsonl         │
│ 2. bd ready --json --limit 5                │
│ 3. /context "Session start: [summary]"      │
└─────────────────────────────────────────────┘
                    ↓
CLAIM WORK:
┌─────────────────────────────────────────────┐
│ 1. bd update bd-X --status in_progress      │
│ 2. bd dep tree bd-X                         │
│ 3. /context "Working on bd-X: [context]"    │
└─────────────────────────────────────────────┘
                    ↓
DURING WORK:
┌─────────────────────────────────────────────┐
│ Execute, discover, create sub-issues        │
│ At major checkpoints:                       │
│   /context "Checkpoint: [brief desc]"       │
│ After routine operations:                   │
│   /compact "Preserve: [key], Remove: [...]" │
└─────────────────────────────────────────────┘
                    ↓
COMPLETE WORK:
┌─────────────────────────────────────────────┐
│ 1. bd close bd-X --reason "..."             │
│ 2. /compact "Preserve: outcome, Remove: ..." │
└─────────────────────────────────────────────┘
                    ↓
SESSION END:
┌─────────────────────────────────────────────┐
│ 1. /context "Session summary: [...]"        │
│ 2. bd export -o .beads/issues.jsonl         │
│ 3. git add + commit                         │
└─────────────────────────────────────────────┘

Context Fidelity Triggers

High-Fidelity Required

Maintain detailed context when:

• Complex issue with 3+ dependencies
• Multi-file refactoring with intricate relationships
• Debugging subtle interaction bugs
• Architectural decisions in progress
• Resolving difficult merge conflicts
• First time working on codebase area

Action: Use /context with full details

Compaction Acceptable

Compress context when:

• Routine CRUD operations
• Simple bug fixes with clear solutions
• Repetitive issue creation/updates
• Status reviews on multiple issues
• After completing straightforward tasks
• Context >75% full

Action: Use /compact to summarize

Anti-Patterns

❌ Never Compact Without Preserving Key State

Wrong:

/compact "Remove everything from last hour"

Right:

/compact "Preserve: current issue bd-X, dependencies [list], next steps [list]. Remove: command outputs, completed work details"

❌ Never Context Everything

Wrong:

# After every single bd command
bd list --json
/context "Listed issues"
bd show bd-5 --json
/context "Showed bd-5"

Right:

# Only at decision points
bd list --json
bd show bd-5 --json
bd dep tree bd-5
/context "Working on bd-5 (auth feature). Blocked by bd-3 (schema). Plan: [implementation steps]"

❌ Never Lose Discovery Context

Wrong:

# Create issues without linking
bd create "Bug found" --json
bd create "Another bug" --json
# ... context lost

Right:

bd create "Bug in validation" --json  # bd-100
bd dep add bd-100 bd-95 --type discovered-from
/context "Discovered bd-100 from bd-95: validation fails on edge case [X]"

Recovery Patterns

Lost Context Recovery

Situation: Context lost after session interruption

Recovery:

# 1. Import latest state
bd import -i .beads/issues.jsonl

# 2. Find last worked issue
bd list --status in_progress --json

# 3. Reconstruct context
bd dep tree bd-X
/context "Resuming bd-X: [reconstruct from dependencies and git history]"

Context Bloat Recovery

Situation: Context nearly full, losing critical state

Recovery:

# 1. Identify essentials
# - Current active issue
# - Immediate dependencies
# - Next 2-3 steps

# 2. Aggressive compaction
/compact "PRESERVE ONLY: active issue bd-X, dependencies [bd-Y, bd-Z], next steps [A, B, C]. REMOVE: all completed work, all routine outputs, all discovery history except current chain."

Metrics for Context Health

Monitor these indicators:

• Context fullness: Should stay 30-70%
• Active issues: 1-3 maximum
• Preserved decisions: Key architectural choices
• Command output ratio: >80% should be compacted

Related Skills

• beads-workflow.md - Core bd commands
• beads-dependency-management.md - Dependency patterns to preserve
• beads-multi-session-patterns.md - Long-horizon task context

References

• See beads-context/references/context_examples.md for real-world examples