beads-issue-tracking

What this skill does

# beads Issue Tracking

## Overview

beads is a graph-based issue tracker for persistent memory across sessions. Use for multi-session work with complex dependencies; use TodoWrite for simple single-session tasks.

## When to Use beads vs TodoWrite

### Use beads when

- **Multi-session work** - Tasks spanning multiple compaction cycles or days
- **Complex dependencies** - Work with blockers, prerequisites, or hierarchical structure
- **Knowledge work** - Strategic documents, research, or tasks with fuzzy boundaries
- **Side quests** - Exploratory work that might pause the main task
- **Project memory** - Need to resume work after weeks away with full context

### Use TodoWrite when

- **Single-session tasks** - Work that completes within current session
- **Linear execution** - Straightforward step-by-step tasks with no branching
- **Immediate context** - All information already in conversation
- **Simple tracking** - Just need a checklist to show progress

**Key insight**: If resuming work after 2 weeks would be difficult without beads, use beads. If the work can be picked up from a markdown skim, TodoWrite is sufficient.

### Test Yourself: beads or TodoWrite?

Ask these questions to decide:

**Choose beads if:**

- ❓ "Will I need this context in 2 weeks?" → Yes = beads
- ❓ "Could conversation history get compacted?" → Yes = beads
- ❓ "Does this have blockers/dependencies?" → Yes = beads
- ❓ "Is this fuzzy/exploratory work?" → Yes = beads

**Choose TodoWrite if:**

- ❓ "Will this be done in this session?" → Yes = TodoWrite
- ❓ "Is this just a task list for me right now?" → Yes = TodoWrite
- ❓ "Is this linear with no branching?" → Yes = TodoWrite

**When in doubt**: Use beads. Better to have persistent memory you don't need than to lose context you needed.

**For detailed decision criteria and examples, read:** [references/boundaries.md](references/boundaries.md)

## Surviving Compaction Events

**Critical**: Compaction events delete conversation history but preserve beads. After compaction, beads state is your only persistent memory.

**What survives compaction:**

- All bead data (issues, notes, dependencies, status)
- Complete work history and context

**What doesn't survive:**

- Conversation history
- TodoWrite lists
- Recent discussion context

**Writing notes for post-compaction recovery:**

Write notes as if explaining to a future agent with zero conversation context:

**Pattern:**

```markdown
notes field format:
- COMPLETED: Specific deliverables ("implemented JWT refresh endpoint + rate limiting")
- IN PROGRESS: Current state + next immediate step ("testing password reset flow, need user input on email template")
- BLOCKERS: What's preventing progress
- KEY DECISIONS: Important context or user guidance
```

**After compaction:** `beads show <issue-id>` reconstructs full context from notes field.

### Notes Quality Self-Check

Before checkpointing (especially pre-compaction), verify your notes pass these tests:

❓ **Future-me test**: "Could I resume this work in 2 weeks with zero conversation history?"

- [ ] What was completed? (Specific deliverables, not "made progress")
- [ ] What's in progress? (Current state + immediate next step)
- [ ] What's blocked? (Specific blockers with context)
- [ ] What decisions were made? (Why, not just what)

❓ **Stranger test**: "Could another developer understand this without asking me?"

- [ ] Technical choices explained (not just stated)
- [ ] Trade-offs documented (why this approach vs alternatives)
- [ ] User input captured (decisions that came from discussion)

**Good note example:**

```
COMPLETED: JWT auth with RS256 (1hr access, 7d refresh tokens)
KEY DECISION: RS256 over HS256 per security review - enables key rotation
IN PROGRESS: Password reset flow - email service working, need rate limiting
BLOCKERS: Waiting on user decision: reset token expiry (15min vs 1hr trade-off)
NEXT: Implement rate limiting (5 attempts/15min) once expiry decided
```

**Bad note example:**

```
Working on auth. Made some progress. More to do.
```

**For complete compaction recovery workflow, read:** [references/workflows.md](references/workflows.md#compaction-survival)

## Session Start Protocol

**beads is available when:**

- Project has a `.beads/` directory (project-local database), OR
- `~/.beads/` exists (global fallback database for any directory)

**At session start, always check for beads availability and run ready check.**

### Session Start Checklist

Copy this checklist when starting any session where beads is available:

```
Session Start:
- [ ] Run beads ready --json to see available work
- [ ] Run beads list --status in_progress --json for active work
- [ ] If in_progress exists: beads show <issue-id> to read notes
- [ ] Report context to user: "X items ready: [summary]"
- [ ] If using global ~/.beads, mention this in report
- [ ] If nothing ready: beads blocked --json to check blockers
```

**Pattern**: Always check both `beads ready` AND `beads list --status in_progress`. Read notes field first to understand where previous session left off.

**Report format**:

- "I can see X items ready to work on: [summary]"
- "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?"

This establishes immediate shared context about available and active work without requiring user prompting.

**For detailed collaborative handoff process, read:** [references/workflows.md](references/workflows.md#session-handoff)

**Note**: beads auto-discovers the database:

- Uses `.beads/*.db` in current project if exists
- Falls back to `~/.beads/default.db` otherwise
- No configuration needed

### When No Work is Ready

If `beads ready` returns empty but issues exist:

```sh
beads blocked --json
```

Report blockers and suggest next steps.

---

## Progress Checkpointing

Update beads notes at these checkpoints (don't wait for session end):

**Critical triggers:**

- **WARNING: Context running low** - User says "running out of context" / "approaching compaction" / "close to token limit"
- **Token budget > 70%** - Proactively checkpoint when approaching limits
- **Major milestone reached** - Completed significant piece of work
- **Hit a blocker** - Can't proceed, need to capture what was tried
- **Task transition** - Switching issues or about to close this one
- ❓ **Before user input** - About to ask decision that might change direction

**Proactive monitoring during session:**

- At 70% token usage: "We're at 70% token usage - good time to checkpoint beads notes?"
- At 85% token usage: "Approaching token limit (85%) - checkpointing current state to beads"
- At 90% token usage: Automatically checkpoint without asking

**Current token usage**: Check `<system-warning>Token usage:` messages to monitor proactively.

**Checkpoint checklist:**

```
Progress Checkpoint:
- [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format
- [ ] Document KEY DECISIONS or BLOCKERS since last update
- [ ] Mark current status (in_progress/blocked/closed)
- [ ] If discovered new work: create issues with discovered-from
- [ ] Verify notes are self-explanatory for post-compaction resume
```

**Most important**: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.

**Test yourself**: "If compaction happened right now, could future-me resume from these notes?"

---

### Database Selection

beads automatically selects the appropriate database:

- **Project-local** (`.beads/` in project): Used for project-specific work
- **Global fallback** (`~/.beads/`): Used when no project-local database exists

**Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.

**When to use --db flag explicitly:**

- Accessing a specific database outside current directory
- Working with multiple databases (e.g., project database + reference database)
- Example: `beads --db /path/t