using-beads

Using Beads for Issue Tracking

Skill Type: Hybrid (Mandatory Session Protocol + Flexible Issue Creation)
When to Use: Every development session on projects using Beads
Announcement: "I'm using the using-beads skill for issue tracking during this development session."

Purpose

This skill guides you through using Beads during active development sessions. It covers:

• Finding and selecting work (mandatory session start)
• Creating issues during development (flexible, as needed)
• Managing dependencies and progress
• Session hygiene (mandatory session end)
• Integration with other workflows

When to Use This Skill

Use this skill:

• ✅ At the start of every development session
• ✅ When filing issues during work
• ✅ When closing completed work
• ✅ At the end of every session

This skill complements:

• TDD workflow (file test issues)
• Debugging workflow (file bug issues)
• Architecture workflow (reference decisions)

---

MANDATORY: Session Start Protocol

Run these steps at the beginning of EVERY session.

Step 1: Sync and Verify

# Ensure database is current
bd sync

# Verify Beads is working
bd info --json

What to check:

• ✅ Daemon is running (daemon_status: "healthy")
• ✅ Database path is correct
• ✅ Issue count is non-zero (if project has issues)

Step 2: Find Ready Work

# Get all ready work
bd ready --json

# Filter by priority (start with highest)
bd ready --priority 0 --json  # P0 critical
bd ready --priority 1 --json  # P1 high

# Filter by label
bd ready --label backend --json
bd ready --label frontend --json

What "ready" means:

• Issue has no open blocking dependencies
• Issue status is open (not in_progress or closed)
• Can be started immediately

How to choose:

1. Priority first: Start with P0, then P1, then P2, then P3
2. Context second: Pick work that matches your current context
3. Dependencies third: Pick work that unblocks the most other tasks

Step 3: Review Dependencies

Before starting work, understand the context:

# View dependency tree
bd dep tree <issue-id>

# View full issue details
bd show <issue-id> --json

Look for:

• What this blocks (dependents): Other work waiting on this
• What blocks this (dependencies): Should be empty for ready work
• Related issues: Context and background
• Files mentioned: Where to make changes

Step 4: Mark Issue In Progress

bd update <issue-id> --status in_progress --json

CRITICAL RULE: Only mark ONE issue as in_progress at a time.

Why: Helps you focus, shows others what you're working on, prevents context switching.

Session Start Checklist

• [ ] Database synced (bd sync)
• [ ] Beads verified working (bd info --json)
• [ ] Ready work reviewed (bd ready --json)
• [ ] Issue selected (priority + context)
• [ ] Dependencies checked (bd dep tree <issue-id>)
• [ ] Issue marked in_progress (bd update <issue-id> --status in_progress)
• [ ] Only ONE issue in_progress
• [ ] Context understood (files, goals, deliverables)

---

During Development: Filing Discovered Issues

CRITICAL RULE: File issues IMMEDIATELY when you discover work. Don't defer.

When to File Issues (ALWAYS)

File immediately for:

? Bugs discovered:

• Even small bugs (null checks, edge cases, off-by-one errors)
• Crashes or exceptions
• Incorrect behavior vs. spec
• Performance issues

? TODOs identified:

• Can't address in current issue
• Would expand scope too much
• Need more information/research
• Require separate discussion

? Feature ideas:

• Emerge during implementation
• User requests
• Better ways to solve problems
• Integration opportunities

? Technical debt:

• Code smells (duplicated code, long functions)
• Missing abstractions
• Hardcoded values
• Lack of error handling

? Documentation gaps:

• Missing docstrings/comments
• Unclear variable names
• No README or setup guide
• Missing architecture docs

⚠️ Edge cases:

• Unhandled user inputs
• Race conditions
• Security concerns
• Boundary conditions

? Security concerns:

• Potential vulnerabilities
• Missing input validation
• Exposed secrets
• Privilege escalation risks

⚡ Performance issues:

• Slow queries (N+1 problems)
• Memory leaks
• Inefficient algorithms
• Missing caching

Quick Issue Creation

Bug discovered:

bd create "Fix null pointer in auth.py:42" \
  -t bug \
  -p 0 \
  -l "backend,auth,p0-critical" \
  --json

TODO identified:

bd create "Add validation for user email format" \
  -t task \
  -p 2 \
  -l "backend,validation" \
  --json

Feature idea:

bd create "Add OAuth login support" \
  -t feature \
  -p 3 \
  -l "auth,frontend,feature" \
  --json

Technical debt:

bd create "Refactor user service to reduce duplication" \
  -t chore \
  -p 2 \
  -l "backend,refactor,tech-debt" \
  --json

Documentation gap:

bd create "Add API documentation for auth endpoints" \
  -t task \
  -p 2 \
  -l "docs,backend" \
  --json

Link Discovered Work to Current Work

ALWAYS link new issues to what you're working on:

# Capture new issue ID
NEW_ISSUE=$(bd create "Bug found during testing" -t bug -p 1 --json | jq -r '.id')

# Get current work issue ID
CURRENT_ISSUE="<your-current-issue-id>"

# Link with discovered-from dependency
bd dep add $NEW_ISSUE $CURRENT_ISSUE --type discovered-from

Why link with discovered-from:

• Creates audit trail (where was this found?)
• Auto-inherits repository context
• Shows related work
• Helps with planning/estimation

Mark Blockers Immediately

Found a blocker that prevents your current work?

# Create blocker issue
BLOCKER=$(bd create "API endpoint returns 500 error" -t bug -p 0 --json | jq -r '.id')

# Mark current work as blocked
bd dep add $CURRENT_ISSUE $BLOCKER --type blocks

# Update current work status
bd update $CURRENT_ISSUE --status blocked --json

# Start working on blocker instead
bd update $BLOCKER --status in_progress --json

Filing Issues Checklist

• [ ] Issue filed immediately when discovered
• [ ] Descriptive title (what + where)
• [ ] Correct type (bug, task, feature, chore)
• [ ] Priority based on urgency/impact
• [ ] Labels applied (domain, technology)
• [ ] Linked to current work with discovered-from
• [ ] If blocker: marked with blocks dependency

---

Closing Completed Work

When to Close

Close an issue when ALL of these are true:

• ✅ Implementation complete (code written)
• ✅ Tests passing (if applicable)
• ✅ Documentation updated (if needed)
• ✅ Code committed to version control
• ✅ No remaining TODOs for this specific issue

Don't close if:

• ❌ Tests not written/passing
• ❌ Code not committed
• ❌ Documentation still needed
• ❌ Found new work that should be part of this issue

How to Close

bd close <issue-id> --reason "Implemented and tested" --json

Good close reasons:

• "Implemented and tested"
• "Fixed and verified"
• "Documentation completed"
• "Completed as designed"
• "Won't fix - out of scope"
• "Duplicate of <other-issue-id>"
• "Superseded by <other-issue-id>"

Bad close reasons (too vague):

• "Done"
• "Fixed"
• "Complete"

Check What Became Unblocked

After closing, verify what's now ready:

# See newly unblocked work
bd ready --json

# See what depended on your work
bd list --json | jq '.[] | select(.dependencies[] | contains("<your-closed-issue-id>"))'

Issues that depended on your work should now appear in ready work (if they have no other blockers).

Closing Work Checklist

• [ ] All acceptance criteria met
• [ ] Tests passing (if applicable)
• [ ] Code committed and pushed
• [ ] Documentation updated (if needed)
• [ ] Closed with descriptive reason
• [ ] Checked for newly unblocked work
• [ ] Next work selected from ready work

---

MANDATORY: Session End Protocol

Run these steps at the end of EVERY session.

Step 1: File Remaining Discovered Work

CRITICAL: Don't leave session with unfiled work in your head.

Create issues for EVERYTHING you discovered but didn't address:

# File TODOs
bd create "Add error handling for X" -t task -p 2 --json

# File bugs
bd create "Edge case: Y breaks when Z" -t bug -p 1 --json

# File ideas
bd create "Consider using library X for feature Y" -t feature -p 3 --json

# File tech debt
bd create "Refactor module X to reduce complexity" -t chore -p 2 --json

Step 2: Update In-Progress Issues

Update status of anything you didn't finish:

# Still working on it (will continue next session)
bd update <issue-id> --status in_progress \
  --notes "Progress: implemented X, Y, Z. Still need: A, B. 
  Next step: Start with A."

# Blocked on something external
bd update <issue-id> --status blocked \
  --notes "Blocked: waiting for API key from team. 
  Can continue when unblocked."

# Pausing work (ready for others to pick up)
bd update <issue-id> --status open \
  --notes "Pausing here. Completed setup and initial implementation.
  Next step: Add tests in test/module_test.py"

Step 3: Close Completed Issues

# Close everything finished in this session
bd close <issue-1> --reason "Implemented and tested" --json
bd close <issue-2> --reason "Fixed and verified" --json
bd close <issue-3> --reason "Documentation added" --json

Step 4: Sync Database

# Flush pending changes to JSONL
bd sync

# Verify clean state
bd list --status in_progress --json

Expected result:

• Should see 0-1 issues in_progress (what you're actively working on)
• If > 1: you forgot to update status on some issues

Step 5: Commit Beads Changes

# Stage Beads database
git add .beads/issues.jsonl

# Commit with informative message
git commit -m "Work session: <brief summary>

Completed:
- <issue-id-1>: <what you did>
- <issue-id-2>: <what you did>

In progress:
- <issue-id-3>: <current status>

Filed for later:
- <issue-id-4>: <discovered bug>
- <issue-id-5>: <discovered TODO>

See: bd list --status in_progress --json"

# Push changes
git push

Step 6: Verify Clean State

# Final verification
bd list --status in_progress --json | jq '. | length'
# Should be 0 or 1

# Check ready work for next session
bd ready --json | jq '.[:5] | .[] | {id, title, priority}'

Session End Checklist

• [ ] All discovered work filed (nothing left in head)
• [ ] In-progress issues updated with notes
• [ ] Completed issues closed with reasons
• [ ] Database synced (bd sync)
• [ ] Changes committed to git
• [ ] Changes pushed to remote
• [ ] Clean state verified (0-1 in_progress)
• [ ] Ready work reviewed for next session

---

Common Workflows

Workflow 1: Breaking Down Epics

When starting work on an epic, break it into tasks:

# View epic details
bd show <epic-id> --json

# Create child tasks
bd create "Task 1: Set up infrastructure" \
  -t task -p 1 -l "phase-1,backend" --json

bd create "Task 2: Implement core logic" \
  -t task -p 1 -l "phase-1,backend" --json

bd create "Task 3: Add tests" \
  -t task -p 2 -l "phase-1,testing" --json

# Set up dependencies if sequential
TASK1_ID="..."
TASK2_ID="..."
TASK3_ID="..."

bd dep add $TASK2_ID $TASK1_ID --type blocks  # Task 2 needs Task 1
bd dep add $TASK3_ID $TASK2_ID --type blocks  # Task 3 needs Task 2

Workflow 2: Checking Progress

# View phase progress
bd list --label phase-1 --json | \
  jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Output example:
# [
#   {"status": "open", "count": 5},
#   {"status": "in_progress", "count": 1},
#   {"status": "closed", "count": 3}
# ]

# View your active work
bd list --status in_progress --json

# View recent activity (last 10 updates)
bd list --json | \
  jq 'sort_by(.updated_at) | reverse | .[:10] | .[] | {id, title, updated_at}'

Workflow 3: Filtering & Searching

# By label (AND - must have all labels)
bd list --label backend,testing --json

# By label (OR - must have at least one)
bd list --label-any frontend,backend --json

# By priority
bd list --priority 0 --json  # P0 critical only

# By type
bd list --type bug --json

# Combined filters
bd list --status open --priority 1 --label backend --json

# Search in titles
bd list --json | jq '.[] | select(.title | contains("auth"))'

# Search in descriptions
bd list --json | jq '.[] | select(.description | contains("database"))'

Workflow 4: Managing Labels

# Add single label
bd label add <issue-id> backend

# Add multiple labels (one at a time)
bd label add <issue-id> backend
bd label add <issue-id> python
bd label add <issue-id> phase-1

# List labels on issue
bd label list <issue-id>

# List all labels in project
bd label list-all

# Remove label
bd label remove <issue-id> old-label

---

Labels Best Practices

Standard Label Categories

Phase/Feature:

• phase-1, phase-2, phase-3
• feature-auth, feature-payments, feature-admin

Domain:

• backend - Server-side code
• frontend - Client-side code
• database - Schema, migrations, queries
• devex - Developer experience (tooling, CI/CD)
• testing - Test code and infrastructure
• docs - Documentation

Technology:

• Languages: python, javascript, rust, go, elixir
• Frameworks: django, react, nextjs, phoenix
• Databases: postgres, mongodb, redis
• Tools: docker, kubernetes, terraform

Priority Markers:

• p0-critical - System down, major blocker
• p1-high - Important, should do soon
• p2-medium - Normal priority
• p3-low - Nice to have

Type Markers:

• bug - Something broken
• feature - New functionality
• chore - Maintenance, refactoring
• docs - Documentation work
• tech-debt - Technical debt
• security - Security-related

Documentation References:

• adr-001, adr-002 - Architecture decision records
• rfc-042 - Request for comments
• docs-needed - Needs documentation

Label Usage Tips

Do:

• ✅ Use consistent naming (lowercase, hyphens)
• ✅ Apply 3-5 labels per issue
• ✅ Include domain + technology at minimum
• ✅ Use labels for filtering (bd list --label backend)

Don't:

• ❌ Create too many labels (< 30 total is good)
• ❌ Use spaces in labels (use hyphens)
• ❌ Duplicate information (e.g., p0-critical + critical)
• ❌ Be too specific (e.g., fix-bug-in-line-42)

---

Dependency Management

Dependency Types

blocks (hard blocker):

• Use when work CANNOT start until dependency resolves
• Affects ready work detection
• Creates critical path
• Example: "Implement API endpoint" blocks on "Design API schema"

related (soft relationship):

• Use for context, not blocking
• Good to know about
• Doesn't affect ready work
• Example: "Write user guide" related to "Add feature"

parent-child (hierarchical):

• Auto-set by Beads for hierarchical IDs (e.g., proj-abc.1)
• Don't manually set
• Represents epic → task relationship

discovered-from (audit trail):

• Use when filing issues during work
• Shows where work was discovered
• Auto-inherits source repo
• Example: Found bug while implementing feature

Adding Dependencies

# Add hard blocker
bd dep add <blocked-issue> <blocker-issue> --type blocks

# Add soft relationship
bd dep add <issue-1> <issue-2> --type related

# Add discovered-from (when filing during work)
bd dep add <new-issue> <current-work> --type discovered-from

Removing Dependencies

bd dep remove <issue-1> <issue-2>

Viewing Dependencies

# View dependency tree
bd dep tree <issue-id>

# Check for circular dependencies
bd dep cycles

# List blocked issues
bd blocked --json

---

Integration with Other Workflows

Integration with TDD

Workflow:

1. Find ready work: bd ready --json
2. Start work: bd update <issue-id> --status in_progress
3. Write failing test (Red)
4. Implement feature (Green)
5. Refactor (Refactor)
6. If discover bugs/TODOs → file Beads issues immediately
7. Tests pass → close Beads issue
8. Session end → sync Beads

Filing test-related issues:

# Missing test coverage
bd create "Add tests for edge case X" \
  -t task -p 2 -l "testing,backend" --json

# Test infrastructure needed
bd create "Set up integration test framework" \
  -t task -p 1 -l "testing,devex" --json

Integration with Debugging

Workflow:

1. Bug reported or discovered
2. File Beads issue if not exists:

   bd create "App crashes when X" -t bug -p 0 -l "backend,p0-critical" --json
   

3. Mark issue in_progress: bd update <bug-id> --status in_progress
4. Debug using debugging skill
5. Fix identified → close issue with details:

   bd close <bug-id> --reason "Fixed: was null pointer in auth.py:42"
   

6. Root cause suggests more work → file new issues:

   bd create "Add null checks throughout auth module" \
     -t task -p 2 -l "backend,tech-debt" --json
   

Integration with Architecture

Workflow:

1. Architecture decision needed
2. File Beads issue for decision:

   bd create "Decide: Database migration strategy" \
     -t task -p 1 -l "architecture,database" --json
   

3. Create ADR (architecture decision record)
4. Reference ADR in issue:

   bd update <issue-id> --notes "Decision recorded in doc/adr/0042-migration-strategy.md"
   

5. Close decision issue
6. File implementation tasks:

   bd create "Implement chosen migration strategy" \
     -t task -p 1 -l "backend,database,adr-042" --json
   

---

Tips & Best Practices

Do's ✅

Issue Creation:

• ✅ File issues immediately when discovered
• ✅ Use descriptive titles (what + where)
• ✅ Link discovered work to current task
• ✅ Include file paths in descriptions
• ✅ Apply labels for organization

Status Management:

• ✅ Update status as you work
• ✅ Only mark ONE issue in_progress
• ✅ Close issues when truly complete
• ✅ Use descriptive close reasons

Dependencies:

• ✅ Check dependencies before starting
• ✅ Mark blockers immediately
• ✅ Use blocks for hard dependencies
• ✅ Use related for context only

Session Hygiene:

• ✅ Run session start protocol
• ✅ Sync database at session end
• ✅ Commit Beads changes with code
• ✅ Verify clean state before ending

Don'ts ❌

Issue Creation:

• ❌ Skip filing issues to "save time"
• ❌ File vague/unclear issues
• ❌ Forget to link discovered work
• ❌ Create duplicate issues

Status Management:

• ❌ Mark multiple issues in_progress
• ❌ Close issues before tests pass
• ❌ Leave issues in limbo status
• ❌ Use vague close reasons

Dependencies:

• ❌ Ignore dependency chains
• ❌ Create circular dependencies
• ❌ Over-constrain with dependencies
• ❌ Use wrong dependency type

Session Hygiene:

• ❌ Skip session start protocol
• ❌ Forget session end protocol
• ❌ Leave work unfiled at session end
• ❌ Forget to commit Beads changes

Time Investment vs. Value

Time to file issue: 30-60 seconds

• Don't overthink, just capture the thought
• Can refine description later

Time for session start: 2-3 minutes

• Sync, review ready work, pick issue
• Small investment, huge clarity gain

Time for session end: 5-10 minutes

• File remaining work, update status, sync, commit
• Ensures no lost work, clean handoff

Cost of NOT using Beads:

• Lost work (forgot what you discovered)
• Context switching (what was I working on?)
• Blocked team members (didn't know issue was done)
• Duplicate work (someone else did same thing)
• Technical debt (TODOs never filed)

The 10-minute session protocol saves hours of lost context.

---

Troubleshooting

Problem: No ready work available

Symptoms:

bd ready --json
# Returns: []

Diagnosis:

# Check what's blocking
bd blocked --json

# View dependency tree
bd dep tree <epic-id>

# Check for circular dependencies
bd dep cycles

Solutions:

• Complete blocking issues
• Remove incorrect dependencies: bd dep remove <issue-1> <issue-2>
• Fix circular dependencies
• Break down large blocked tasks into smaller unblocked tasks

Problem: Too much ready work (> 20 issues)

Symptoms:

bd ready --json | jq '. | length'
# Returns: 47

Diagnosis:

• Dependencies not set correctly
• Issues that should be blocked aren't

Solutions:

• Review critical path, add missing blockers
• Increase priorities on less important work (push to P2/P3)
• Break into phases with phase-level blockers

Problem: Lost context on what issue was about

Solutions:

# View full details
bd show <issue-id> --json

# Search by partial ID
bd list --json | jq '.[] | select(.id | contains("<partial>"))'

# Search by title keyword
bd list --json | jq '.[] | select(.title | contains("auth"))'

# View related issues
bd dep tree <issue-id>

Problem: Forgot to link discovered work

Solution:

# Find the issue you were working on
bd list --status closed --json | jq '.[-5:] | .[] | {id, title}'

# Add the missing link
bd dep add <new-issue> <parent-issue> --type discovered-from

Problem: Issue marked in_progress but forgot what I was doing

Solution:

# View issue details
bd show <issue-id> --json

# Check recent commits
git log --oneline -10

# Update with notes about current state
bd update <issue-id> --notes "Current state: implemented X, Y. Next: Z"

Problem: Accidentally closed wrong issue

Solution:

# Reopen issue
bd update <issue-id> --status open

# Add note about mistake
bd update <issue-id> --notes "Reopened: closed by mistake"

---

Success Metrics

You're using Beads effectively when:

• ✅ Never lose track of discovered work
• ✅ Always know what to work on next (ready work is clear)
• ✅ Can reconstruct work history from issues
• ✅ Dependencies prevent premature work
• ✅ Issues provide context weeks/months later
• ✅ Team knows what everyone is working on
• ✅ Technical debt gets tracked, not forgotten
• ✅ Bugs get filed, not lost
• ✅ Session transitions are smooth (no context loss)
• ✅ Can step away and come back easily

You know it's working when:

• No one asks "what should I work on?" (they check bd ready)
• No one asks "what are you working on?" (they check bd list --status in_progress)
• Discovered bugs don't get forgotten
• TODOs become tracked tasks
• Dependencies prevent wasted work
• Progress is visible and measurable

Beads is infrastructure for your memory. Use it like you use git.