[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6ERT2MYVEPEM9YXX68F1SKF":3,"skill-same:01M6ERT2MYVEPEM9YXX68F1SKF":47},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M6ERT2MYVEPEM9YXX68F1SKF","using-beads",null,"nocksock\u002Fsuperpowers","nocksock","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F22164?v=4","01M6ERQWRTZARGFM7AX8HB89GZ","Nils Riedemann","01M6ERQWXFH5876Z6HEDH9TWYS",1,"MIT","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fusing-beads\u002FSKILL.md",[],[18,19],"beads","using beads","2026-11-10 10:12:30",false,"# Using Beads for Issue Tracking\n\n**Skill Type:** Hybrid (Mandatory Session Protocol + Flexible Issue Creation)  \n**When to Use:** Every development session on projects using Beads  \n**Announcement:** \"I'm using the using-beads skill for issue tracking during this development session.\"\n\n## Purpose\n\nThis skill guides you through using Beads during active development sessions. It covers:\n- Finding and selecting work (mandatory session start)\n- Creating issues during development (flexible, as needed)\n- Managing dependencies and progress\n- Session hygiene (mandatory session end)\n- Integration with other workflows\n\n## When to Use This Skill\n\n**Use this skill:**\n- ✅ At the start of every development session\n- ✅ When filing issues during work\n- ✅ When closing completed work\n- ✅ At the end of every session\n\n**This skill complements:**\n- TDD workflow (file test issues)\n- Debugging workflow (file bug issues)\n- Architecture workflow (reference decisions)\n\n---\n\n## MANDATORY: Session Start Protocol\n\n**Run these steps at the beginning of EVERY session.**\n\n### Step 1: Sync and Verify\n\n```bash\n# Ensure database is current\nbd sync\n\n# Verify Beads is working\nbd info --json\n```\n\n**What to check:**\n- ✅ Daemon is running (`daemon_status: \"healthy\"`)\n- ✅ Database path is correct\n- ✅ Issue count is non-zero (if project has issues)\n\n### Step 2: Find Ready Work\n\n```bash\n# Get all ready work\nbd ready --json\n\n# Filter by priority (start with highest)\nbd ready --priority 0 --json  # P0 critical\nbd ready --priority 1 --json  # P1 high\n\n# Filter by label\nbd ready --label backend --json\nbd ready --label frontend --json\n```\n\n**What \"ready\" means:**\n- Issue has no open blocking dependencies\n- Issue status is `open` (not in_progress or closed)\n- Can be started immediately\n\n**How to choose:**\n1. **Priority first:** Start with P0, then P1, then P2, then P3\n2. **Context second:** Pick work that matches your current context\n3. **Dependencies third:** Pick work that unblocks the most other tasks\n\n### Step 3: Review Dependencies\n\nBefore starting work, understand the context:\n\n```bash\n# View dependency tree\nbd dep tree \u003Cissue-id>\n\n# View full issue details\nbd show \u003Cissue-id> --json\n```\n\n**Look for:**\n- **What this blocks (dependents):** Other work waiting on this\n- **What blocks this (dependencies):** Should be empty for ready work\n- **Related issues:** Context and background\n- **Files mentioned:** Where to make changes\n\n### Step 4: Mark Issue In Progress\n\n```bash\nbd update \u003Cissue-id> --status in_progress --json\n```\n\n**CRITICAL RULE:** Only mark ONE issue as `in_progress` at a time.\n\n**Why:** Helps you focus, shows others what you're working on, prevents context switching.\n\n### Session Start Checklist\n\n- [ ] Database synced (`bd sync`)\n- [ ] Beads verified working (`bd info --json`)\n- [ ] Ready work reviewed (`bd ready --json`)\n- [ ] Issue selected (priority + context)\n- [ ] Dependencies checked (`bd dep tree \u003Cissue-id>`)\n- [ ] Issue marked in_progress (`bd update \u003Cissue-id> --status in_progress`)\n- [ ] Only ONE issue in_progress\n- [ ] Context understood (files, goals, deliverables)\n\n---\n\n## During Development: Filing Discovered Issues\n\n**CRITICAL RULE:** File issues IMMEDIATELY when you discover work. Don't defer.\n\n### When to File Issues (ALWAYS)\n\n**File immediately for:**\n\n? **Bugs discovered:**\n- Even small bugs (null checks, edge cases, off-by-one errors)\n- Crashes or exceptions\n- Incorrect behavior vs. spec\n- Performance issues\n\n? **TODOs identified:**\n- Can't address in current issue\n- Would expand scope too much\n- Need more information\u002Fresearch\n- Require separate discussion\n\n? **Feature ideas:**\n- Emerge during implementation\n- User requests\n- Better ways to solve problems\n- Integration opportunities\n\n? **Technical debt:**\n- Code smells (duplicated code, long functions)\n- Missing abstractions\n- Hardcoded values\n- Lack of error handling\n\n? **Documentation gaps:**\n- Missing docstrings\u002Fcomments\n- Unclear variable names\n- No README or setup guide\n- Missing architecture docs\n\n⚠️ **Edge cases:**\n- Unhandled user inputs\n- Race conditions\n- Security concerns\n- Boundary conditions\n\n? **Security concerns:**\n- Potential vulnerabilities\n- Missing input validation\n- Exposed secrets\n- Privilege escalation risks\n\n⚡ **Performance issues:**\n- Slow queries (N+1 problems)\n- Memory leaks\n- Inefficient algorithms\n- Missing caching\n\n### Quick Issue Creation\n\n**Bug discovered:**\n```bash\nbd create \"Fix null pointer in auth.py:42\" \\\n  -t bug \\\n  -p 0 \\\n  -l \"backend,auth,p0-critical\" \\\n  --json\n```\n\n**TODO identified:**\n```bash\nbd create \"Add validation for user email format\" \\\n  -t task \\\n  -p 2 \\\n  -l \"backend,validation\" \\\n  --json\n```\n\n**Feature idea:**\n```bash\nbd create \"Add OAuth login support\" \\\n  -t feature \\\n  -p 3 \\\n  -l \"auth,frontend,feature\" \\\n  --json\n```\n\n**Technical debt:**\n```bash\nbd create \"Refactor user service to reduce duplication\" \\\n  -t chore \\\n  -p 2 \\\n  -l \"backend,refactor,tech-debt\" \\\n  --json\n```\n\n**Documentation gap:**\n```bash\nbd create \"Add API documentation for auth endpoints\" \\\n  -t task \\\n  -p 2 \\\n  -l \"docs,backend\" \\\n  --json\n```\n\n### Link Discovered Work to Current Work\n\n**ALWAYS link new issues to what you're working on:**\n\n```bash\n# Capture new issue ID\nNEW_ISSUE=$(bd create \"Bug found during testing\" -t bug -p 1 --json | jq -r '.id')\n\n# Get current work issue ID\nCURRENT_ISSUE=\"\u003Cyour-current-issue-id>\"\n\n# Link with discovered-from dependency\nbd dep add $NEW_ISSUE $CURRENT_ISSUE --type discovered-from\n```\n\n**Why link with `discovered-from`:**\n- Creates audit trail (where was this found?)\n- Auto-inherits repository context\n- Shows related work\n- Helps with planning\u002Festimation\n\n### Mark Blockers Immediately\n\n**Found a blocker that prevents your current work?**\n\n```bash\n# Create blocker issue\nBLOCKER=$(bd create \"API endpoint returns 500 error\" -t bug -p 0 --json | jq -r '.id')\n\n# Mark current work as blocked\nbd dep add $CURRENT_ISSUE $BLOCKER --type blocks\n\n# Update current work status\nbd update $CURRENT_ISSUE --status blocked --json\n\n# Start working on blocker instead\nbd update $BLOCKER --status in_progress --json\n```\n\n### Filing Issues Checklist\n\n- [ ] Issue filed immediately when discovered\n- [ ] Descriptive title (what + where)\n- [ ] Correct type (bug, task, feature, chore)\n- [ ] Priority based on urgency\u002Fimpact\n- [ ] Labels applied (domain, technology)\n- [ ] Linked to current work with `discovered-from`\n- [ ] If blocker: marked with `blocks` dependency\n\n---\n\n## Closing Completed Work\n\n### When to Close\n\nClose an issue when ALL of these are true:\n\n- ✅ Implementation complete (code written)\n- ✅ Tests passing (if applicable)\n- ✅ Documentation updated (if needed)\n- ✅ Code committed to version control\n- ✅ No remaining TODOs for this specific issue\n\n**Don't close if:**\n- ❌ Tests not written\u002Fpassing\n- ❌ Code not committed\n- ❌ Documentation still needed\n- ❌ Found new work that should be part of this issue\n\n### How to Close\n\n```bash\nbd close \u003Cissue-id> --reason \"Implemented and tested\" --json\n```\n\n**Good close reasons:**\n- \"Implemented and tested\"\n- \"Fixed and verified\"\n- \"Documentation completed\"\n- \"Completed as designed\"\n- \"Won't fix - out of scope\"\n- \"Duplicate of \u003Cother-issue-id>\"\n- \"Superseded by \u003Cother-issue-id>\"\n\n**Bad close reasons (too vague):**\n- \"Done\"\n- \"Fixed\"\n- \"Complete\"\n\n### Check What Became Unblocked\n\nAfter closing, verify what's now ready:\n\n```bash\n# See newly unblocked work\nbd ready --json\n\n# See what depended on your work\nbd list --json | jq '.[] | select(.dependencies[] | contains(\"\u003Cyour-closed-issue-id>\"))'\n```\n\nIssues that depended on your work should now appear in ready work (if they have no other blockers).\n\n### Closing Work Checklist\n\n- [ ] All acceptance criteria met\n- [ ] Tests passing (if applicable)\n- [ ] Code committed and pushed\n- [ ] Documentation updated (if needed)\n- [ ] Closed with descriptive reason\n- [ ] Checked for newly unblocked work\n- [ ] Next work selected from ready work\n\n---\n\n## MANDATORY: Session End Protocol\n\n**Run these steps at the end of EVERY session.**\n\n### Step 1: File Remaining Discovered Work\n\n**CRITICAL:** Don't leave session with unfiled work in your head.\n\nCreate issues for EVERYTHING you discovered but didn't address:\n\n```bash\n# File TODOs\nbd create \"Add error handling for X\" -t task -p 2 --json\n\n# File bugs\nbd create \"Edge case: Y breaks when Z\" -t bug -p 1 --json\n\n# File ideas\nbd create \"Consider using library X for feature Y\" -t feature -p 3 --json\n\n# File tech debt\nbd create \"Refactor module X to reduce complexity\" -t chore -p 2 --json\n```\n\n### Step 2: Update In-Progress Issues\n\nUpdate status of anything you didn't finish:\n\n```bash\n# Still working on it (will continue next session)\nbd update \u003Cissue-id> --status in_progress \\\n  --notes \"Progress: implemented X, Y, Z. Still need: A, B. \n  Next step: Start with A.\"\n\n# Blocked on something external\nbd update \u003Cissue-id> --status blocked \\\n  --notes \"Blocked: waiting for API key from team. \n  Can continue when unblocked.\"\n\n# Pausing work (ready for others to pick up)\nbd update \u003Cissue-id> --status open \\\n  --notes \"Pausing here. Completed setup and initial implementation.\n  Next step: Add tests in test\u002Fmodule_test.py\"\n```\n\n### Step 3: Close Completed Issues\n\n```bash\n# Close everything finished in this session\nbd close \u003Cissue-1> --reason \"Implemented and tested\" --json\nbd close \u003Cissue-2> --reason \"Fixed and verified\" --json\nbd close \u003Cissue-3> --reason \"Documentation added\" --json\n```\n\n### Step 4: Sync Database\n\n```bash\n# Flush pending changes to JSONL\nbd sync\n\n# Verify clean state\nbd list --status in_progress --json\n```\n\n**Expected result:**\n- Should see 0-1 issues in_progress (what you're actively working on)\n- If > 1: you forgot to update status on some issues\n\n### Step 5: Commit Beads Changes\n\n```bash\n# Stage Beads database\ngit add .beads\u002Fissues.jsonl\n\n# Commit with informative message\ngit commit -m \"Work session: \u003Cbrief summary>\n\nCompleted:\n- \u003Cissue-id-1>: \u003Cwhat you did>\n- \u003Cissue-id-2>: \u003Cwhat you did>\n\nIn progress:\n- \u003Cissue-id-3>: \u003Ccurrent status>\n\nFiled for later:\n- \u003Cissue-id-4>: \u003Cdiscovered bug>\n- \u003Cissue-id-5>: \u003Cdiscovered TODO>\n\nSee: bd list --status in_progress --json\"\n\n# Push changes\ngit push\n```\n\n### Step 6: Verify Clean State\n\n```bash\n# Final verification\nbd list --status in_progress --json | jq '. | length'\n# Should be 0 or 1\n\n# Check ready work for next session\nbd ready --json | jq '.[:5] | .[] | {id, title, priority}'\n```\n\n### Session End Checklist\n\n- [ ] All discovered work filed (nothing left in head)\n- [ ] In-progress issues updated with notes\n- [ ] Completed issues closed with reasons\n- [ ] Database synced (`bd sync`)\n- [ ] Changes committed to git\n- [ ] Changes pushed to remote\n- [ ] Clean state verified (0-1 in_progress)\n- [ ] Ready work reviewed for next session\n\n---\n\n## Common Workflows\n\n### Workflow 1: Breaking Down Epics\n\nWhen starting work on an epic, break it into tasks:\n\n```bash\n# View epic details\nbd show \u003Cepic-id> --json\n\n# Create child tasks\nbd create \"Task 1: Set up infrastructure\" \\\n  -t task -p 1 -l \"phase-1,backend\" --json\n\nbd create \"Task 2: Implement core logic\" \\\n  -t task -p 1 -l \"phase-1,backend\" --json\n\nbd create \"Task 3: Add tests\" \\\n  -t task -p 2 -l \"phase-1,testing\" --json\n\n# Set up dependencies if sequential\nTASK1_ID=\"...\"\nTASK2_ID=\"...\"\nTASK3_ID=\"...\"\n\nbd dep add $TASK2_ID $TASK1_ID --type blocks  # Task 2 needs Task 1\nbd dep add $TASK3_ID $TASK2_ID --type blocks  # Task 3 needs Task 2\n```\n\n### Workflow 2: Checking Progress\n\n```bash\n# View phase progress\nbd list --label phase-1 --json | \\\n  jq 'group_by(.status) | map({status: .[0].status, count: length})'\n\n# Output example:\n# [\n#   {\"status\": \"open\", \"count\": 5},\n#   {\"status\": \"in_progress\", \"count\": 1},\n#   {\"status\": \"closed\", \"count\": 3}\n# ]\n\n# View your active work\nbd list --status in_progress --json\n\n# View recent activity (last 10 updates)\nbd list --json | \\\n  jq 'sort_by(.updated_at) | reverse | .[:10] | .[] | {id, title, updated_at}'\n```\n\n### Workflow 3: Filtering & Searching\n\n```bash\n# By label (AND - must have all labels)\nbd list --label backend,testing --json\n\n# By label (OR - must have at least one)\nbd list --label-any frontend,backend --json\n\n# By priority\nbd list --priority 0 --json  # P0 critical only\n\n# By type\nbd list --type bug --json\n\n# Combined filters\nbd list --status open --priority 1 --label backend --json\n\n# Search in titles\nbd list --json | jq '.[] | select(.title | contains(\"auth\"))'\n\n# Search in descriptions\nbd list --json | jq '.[] | select(.description | contains(\"database\"))'\n```\n\n### Workflow 4: Managing Labels\n\n```bash\n# Add single label\nbd label add \u003Cissue-id> backend\n\n# Add multiple labels (one at a time)\nbd label add \u003Cissue-id> backend\nbd label add \u003Cissue-id> python\nbd label add \u003Cissue-id> phase-1\n\n# List labels on issue\nbd label list \u003Cissue-id>\n\n# List all labels in project\nbd label list-all\n\n# Remove label\nbd label remove \u003Cissue-id> old-label\n```\n\n---\n\n## Labels Best Practices\n\n### Standard Label Categories\n\n**Phase\u002FFeature:**\n- `phase-1`, `phase-2`, `phase-3`\n- `feature-auth`, `feature-payments`, `feature-admin`\n\n**Domain:**\n- `backend` - Server-side code\n- `frontend` - Client-side code\n- `database` - Schema, migrations, queries\n- `devex` - Developer experience (tooling, CI\u002FCD)\n- `testing` - Test code and infrastructure\n- `docs` - Documentation\n\n**Technology:**\n- Languages: `python`, `javascript`, `rust`, `go`, `elixir`\n- Frameworks: `django`, `react`, `nextjs`, `phoenix`\n- Databases: `postgres`, `mongodb`, `redis`\n- Tools: `docker`, `kubernetes`, `terraform`\n\n**Priority Markers:**\n- `p0-critical` - System down, major blocker\n- `p1-high` - Important, should do soon\n- `p2-medium` - Normal priority\n- `p3-low` - Nice to have\n\n**Type Markers:**\n- `bug` - Something broken\n- `feature` - New functionality\n- `chore` - Maintenance, refactoring\n- `docs` - Documentation work\n- `tech-debt` - Technical debt\n- `security` - Security-related\n\n**Documentation References:**\n- `adr-001`, `adr-002` - Architecture decision records\n- `rfc-042` - Request for comments\n- `docs-needed` - Needs documentation\n\n### Label Usage Tips\n\n**Do:**\n- ✅ Use consistent naming (lowercase, hyphens)\n- ✅ Apply 3-5 labels per issue\n- ✅ Include domain + technology at minimum\n- ✅ Use labels for filtering (`bd list --label backend`)\n\n**Don't:**\n- ❌ Create too many labels (\u003C 30 total is good)\n- ❌ Use spaces in labels (use hyphens)\n- ❌ Duplicate information (e.g., `p0-critical` + `critical`)\n- ❌ Be too specific (e.g., `fix-bug-in-line-42`)\n\n---\n\n## Dependency Management\n\n### Dependency Types\n\n**`blocks` (hard blocker):**\n- Use when work CANNOT start until dependency resolves\n- Affects ready work detection\n- Creates critical path\n- Example: \"Implement API endpoint\" blocks on \"Design API schema\"\n\n**`related` (soft relationship):**\n- Use for context, not blocking\n- Good to know about\n- Doesn't affect ready work\n- Example: \"Write user guide\" related to \"Add feature\"\n\n**`parent-child` (hierarchical):**\n- Auto-set by Beads for hierarchical IDs (e.g., `proj-abc.1`)\n- Don't manually set\n- Represents epic → task relationship\n\n**`discovered-from` (audit trail):**\n- Use when filing issues during work\n- Shows where work was discovered\n- Auto-inherits source repo\n- Example: Found bug while implementing feature\n\n### Adding Dependencies\n\n```bash\n# Add hard blocker\nbd dep add \u003Cblocked-issue> \u003Cblocker-issue> --type blocks\n\n# Add soft relationship\nbd dep add \u003Cissue-1> \u003Cissue-2> --type related\n\n# Add discovered-from (when filing during work)\nbd dep add \u003Cnew-issue> \u003Ccurrent-work> --type discovered-from\n```\n\n### Removing Dependencies\n\n```bash\nbd dep remove \u003Cissue-1> \u003Cissue-2>\n```\n\n### Viewing Dependencies\n\n```bash\n# View dependency tree\nbd dep tree \u003Cissue-id>\n\n# Check for circular dependencies\nbd dep cycles\n\n# List blocked issues\nbd blocked --json\n```\n\n---\n\n## Integration with Other Workflows\n\n### Integration with TDD\n\n**Workflow:**\n1. Find ready work: `bd ready --json`\n2. Start work: `bd update \u003Cissue-id> --status in_progress`\n3. Write failing test (Red)\n4. Implement feature (Green)\n5. Refactor (Refactor)\n6. If discover bugs\u002FTODOs → file Beads issues immediately\n7. Tests pass → close Beads issue\n8. Session end → sync Beads\n\n**Filing test-related issues:**\n```bash\n# Missing test coverage\nbd create \"Add tests for edge case X\" \\\n  -t task -p 2 -l \"testing,backend\" --json\n\n# Test infrastructure needed\nbd create \"Set up integration test framework\" \\\n  -t task -p 1 -l \"testing,devex\" --json\n```\n\n### Integration with Debugging\n\n**Workflow:**\n1. Bug reported or discovered\n2. File Beads issue if not exists:\n   ```bash\n   bd create \"App crashes when X\" -t bug -p 0 -l \"backend,p0-critical\" --json\n   ```\n3. Mark issue in_progress: `bd update \u003Cbug-id> --status in_progress`\n4. Debug using debugging skill\n5. Fix identified → close issue with details:\n   ```bash\n   bd close \u003Cbug-id> --reason \"Fixed: was null pointer in auth.py:42\"\n   ```\n6. Root cause suggests more work → file new issues:\n   ```bash\n   bd create \"Add null checks throughout auth module\" \\\n     -t task -p 2 -l \"backend,tech-debt\" --json\n   ```\n\n### Integration with Architecture\n\n**Workflow:**\n1. Architecture decision needed\n2. File Beads issue for decision:\n   ```bash\n   bd create \"Decide: Database migration strategy\" \\\n     -t task -p 1 -l \"architecture,database\" --json\n   ```\n3. Create ADR (architecture decision record)\n4. Reference ADR in issue:\n   ```bash\n   bd update \u003Cissue-id> --notes \"Decision recorded in doc\u002Fadr\u002F0042-migration-strategy.md\"\n   ```\n5. Close decision issue\n6. File implementation tasks:\n   ```bash\n   bd create \"Implement chosen migration strategy\" \\\n     -t task -p 1 -l \"backend,database,adr-042\" --json\n   ```\n\n---\n\n## Tips & Best Practices\n\n### Do's ✅\n\n**Issue Creation:**\n- ✅ File issues immediately when discovered\n- ✅ Use descriptive titles (what + where)\n- ✅ Link discovered work to current task\n- ✅ Include file paths in descriptions\n- ✅ Apply labels for organization\n\n**Status Management:**\n- ✅ Update status as you work\n- ✅ Only mark ONE issue in_progress\n- ✅ Close issues when truly complete\n- ✅ Use descriptive close reasons\n\n**Dependencies:**\n- ✅ Check dependencies before starting\n- ✅ Mark blockers immediately\n- ✅ Use `blocks` for hard dependencies\n- ✅ Use `related` for context only\n\n**Session Hygiene:**\n- ✅ Run session start protocol\n- ✅ Sync database at session end\n- ✅ Commit Beads changes with code\n- ✅ Verify clean state before ending\n\n### Don'ts ❌\n\n**Issue Creation:**\n- ❌ Skip filing issues to \"save time\"\n- ❌ File vague\u002Funclear issues\n- ❌ Forget to link discovered work\n- ❌ Create duplicate issues\n\n**Status Management:**\n- ❌ Mark multiple issues in_progress\n- ❌ Close issues before tests pass\n- ❌ Leave issues in limbo status\n- ❌ Use vague close reasons\n\n**Dependencies:**\n- ❌ Ignore dependency chains\n- ❌ Create circular dependencies\n- ❌ Over-constrain with dependencies\n- ❌ Use wrong dependency type\n\n**Session Hygiene:**\n- ❌ Skip session start protocol\n- ❌ Forget session end protocol\n- ❌ Leave work unfiled at session end\n- ❌ Forget to commit Beads changes\n\n### Time Investment vs. Value\n\n**Time to file issue:** 30-60 seconds\n- Don't overthink, just capture the thought\n- Can refine description later\n\n**Time for session start:** 2-3 minutes\n- Sync, review ready work, pick issue\n- Small investment, huge clarity gain\n\n**Time for session end:** 5-10 minutes\n- File remaining work, update status, sync, commit\n- Ensures no lost work, clean handoff\n\n**Cost of NOT using Beads:**\n- Lost work (forgot what you discovered)\n- Context switching (what was I working on?)\n- Blocked team members (didn't know issue was done)\n- Duplicate work (someone else did same thing)\n- Technical debt (TODOs never filed)\n\n**The 10-minute session protocol saves hours of lost context.**\n\n---\n\n## Troubleshooting\n\n### Problem: No ready work available\n\n**Symptoms:**\n```bash\nbd ready --json\n# Returns: []\n```\n\n**Diagnosis:**\n```bash\n# Check what's blocking\nbd blocked --json\n\n# View dependency tree\nbd dep tree \u003Cepic-id>\n\n# Check for circular dependencies\nbd dep cycles\n```\n\n**Solutions:**\n- Complete blocking issues\n- Remove incorrect dependencies: `bd dep remove \u003Cissue-1> \u003Cissue-2>`\n- Fix circular dependencies\n- Break down large blocked tasks into smaller unblocked tasks\n\n### Problem: Too much ready work (> 20 issues)\n\n**Symptoms:**\n```bash\nbd ready --json | jq '. | length'\n# Returns: 47\n```\n\n**Diagnosis:**\n- Dependencies not set correctly\n- Issues that should be blocked aren't\n\n**Solutions:**\n- Review critical path, add missing blockers\n- Increase priorities on less important work (push to P2\u002FP3)\n- Break into phases with phase-level blockers\n\n### Problem: Lost context on what issue was about\n\n**Solutions:**\n```bash\n# View full details\nbd show \u003Cissue-id> --json\n\n# Search by partial ID\nbd list --json | jq '.[] | select(.id | contains(\"\u003Cpartial>\"))'\n\n# Search by title keyword\nbd list --json | jq '.[] | select(.title | contains(\"auth\"))'\n\n# View related issues\nbd dep tree \u003Cissue-id>\n```\n\n### Problem: Forgot to link discovered work\n\n**Solution:**\n```bash\n# Find the issue you were working on\nbd list --status closed --json | jq '.[-5:] | .[] | {id, title}'\n\n# Add the missing link\nbd dep add \u003Cnew-issue> \u003Cparent-issue> --type discovered-from\n```\n\n### Problem: Issue marked in_progress but forgot what I was doing\n\n**Solution:**\n```bash\n# View issue details\nbd show \u003Cissue-id> --json\n\n# Check recent commits\ngit log --oneline -10\n\n# Update with notes about current state\nbd update \u003Cissue-id> --notes \"Current state: implemented X, Y. Next: Z\"\n```\n\n### Problem: Accidentally closed wrong issue\n\n**Solution:**\n```bash\n# Reopen issue\nbd update \u003Cissue-id> --status open\n\n# Add note about mistake\nbd update \u003Cissue-id> --notes \"Reopened: closed by mistake\"\n```\n\n---\n\n## Success Metrics\n\n**You're using Beads effectively when:**\n\n- ✅ Never lose track of discovered work\n- ✅ Always know what to work on next (ready work is clear)\n- ✅ Can reconstruct work history from issues\n- ✅ Dependencies prevent premature work\n- ✅ Issues provide context weeks\u002Fmonths later\n- ✅ Team knows what everyone is working on\n- ✅ Technical debt gets tracked, not forgotten\n- ✅ Bugs get filed, not lost\n- ✅ Session transitions are smooth (no context loss)\n- ✅ Can step away and come back easily\n\n**You know it's working when:**\n- No one asks \"what should I work on?\" (they check `bd ready`)\n- No one asks \"what are you working on?\" (they check `bd list --status in_progress`)\n- Discovered bugs don't get forgotten\n- TODOs become tracked tasks\n- Dependencies prevent wasted work\n- Progress is visible and measurable\n\n**Beads is infrastructure for your memory. Use it like you use git.**\n",{},"main","52d2d5a29297631b5e3ff61fbc8ca3c6505a26e2","skills\u002Fusing-beads",0,"https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers","https:\u002F\u002Fgithub.com\u002Fnocksock","http:\u002F\u002Fbleepbloop.studio\u002F","Hi, I'm Nils. I build interfaces for the web.","2026-03-19 04:55:50",{"source":7,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add nocksock\u002Fsuperpowers --skill using-beads",{"tool":39,"command":40},"bunx","bunx skills add nocksock\u002Fsuperpowers --skill using-beads",{"tool":42,"command":43},"pnpm","pnpm dlx skills add nocksock\u002Fsuperpowers --skill using-beads","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fusing-beads\u002FSKILL.md",true,[],[48,74,90,107,120,131],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":67,"publishedAt":20},"01M6ERV5R58PKM81EH15XEYPMF","writing-skills","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[54,59,62],{"categoryNo":55,"categoryName":56,"taxonomyType":57,"taxonomyTypeDesc":58},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":60,"categoryName":61,"taxonomyType":57,"taxonomyTypeDesc":58},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":63,"categoryName":64,"taxonomyType":65,"taxonomyTypeDesc":66},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[68,69,70,71,72,73],"writing skills","writing","use","deployment","work","editing",{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":82,"publishedAt":20},"01M6ERV2JX5DJV2EHSC6FXHEHN","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-plans\u002FSKILL.md",[80,81],{"categoryNo":60,"categoryName":61,"taxonomyType":57,"taxonomyTypeDesc":58},{"categoryNo":63,"categoryName":64,"taxonomyType":65,"taxonomyTypeDesc":66},[83,84,69,85,86,70,87,88,89],"plans","writing plans","spec","code","task","requirements","multi",{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":101,"publishedAt":20},"01M6ERTZS70NCVS375DTD8HGKE","writing good code","use this skill whenever you write code. it provides a process for creating good, composable apis.","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-good-code\u002FSKILL.md",[96,97,100],{"categoryNo":60,"categoryName":61,"taxonomyType":57,"taxonomyTypeDesc":58},{"categoryNo":98,"categoryName":99,"taxonomyType":65,"taxonomyTypeDesc":66},"01JBSEEDCAT000000000000030","开发工程师",{"categoryNo":63,"categoryName":64,"taxonomyType":65,"taxonomyTypeDesc":66},[92,102,86,69,103,70,104,105,106],"good","it","process","write","composable",{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":20},"01M6ERTVVRPKZVWK6M8EXPB5QE","write-review-elixir","Review Elixir code. ALWAYS use this skill before or after you added code written in elixir to ensure high code quality. Also use use this when asked to review existing elixir code.","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fwrite-or-review-elixir\u002FSKILL.md",[],[114,105,115,116,117,70,118,86,119],"write review elixir","elixir","review","elixir code","quality","code quality",{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":20},"01M6ERTRAM8PSJ9JTAW5J4ABFD","whats-next","Answers what to do next, what to work on next, where we're at","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fwhats-next\u002FSKILL.md",[],[127,128,129,72,130],"next","whats next","work on","do",{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":137,"publishedAt":20},"01M6ERTNG9NT8SQH5FHN91JRTS","verification-before-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002Fnocksock\u002Fsuperpowers\u002Fblob\u002Fmain\u002Fskills\u002Fverification-before-completion\u002FSKILL.md",[],[138,139,140,141,142,70,72,143,144,145],"verification before completion","verification","commands","claim","evidence","complete","output","about"]