fixing-beads-problems
Made by JeffFix malformed beads database corruption and JSONL drift. Use when br show or br doctor fail, both stores changed, .beads/beads.db is wrong, or DB-only changes must be recovered before rebuild.
Works With
Quality and Utility come from canonical skill metadata. Community ratings appear separately as stars when subscriber reviews exist.
Subscribe to download
Public previews are available, but downloads, CLI sync, and premium content require an active subscription.
Sign In to Subscribe- Full skill content with deterministic versioning
- CLI sync + local search index
- Access to Jeffrey’s premium library
Save to your account
Saved skills live in your cloud list. Run jsm sync on each machine to pull them locally.
What's New with this Skill
1Updates, enhancements, and release notes for this skill.
New skill: fixing-beads-problems, recover a beads store without losing what only the database knew
When .beads/beads.db is malformed and issues.jsonl has drifted, each store usually holds something the other lacks. This skill snapshots everything, reads the dirty issues out of the old DB, carries those changes into the JSONL, rebuilds into a separate temp DB, and promotes it by rename only after br show, br sync --status and br doctor all pass. Nothing under .beads is deleted.
- Nothing under .beads is deleted. Bad files are renamed aside or copied into a timestamped recovery directory, and the snapshot is taken before any rebuild, rename or import.
- br doctor alone is not a health check. A DB can pass doctor and still fail br show with "database disk image is malformed", so show is treated as a required read test.
- When br sync --status reports both jsonl_newer and db_newer, each store holds changes the other lacks, and the skill refuses a blind export or a blind rebuild.
- The old DB's dirty_issues table is read without writing to it. scripts/compare-dirty-issues.sh prints each dirty issue's JSONL line, or MISSING_IN_JSONL.
- DB-only changes worth keeping (comments, status changes, title and notes edits, dependency intent) are reapplied through br and flushed, so the JSONL stays valid instead of being hand-edited.
- The rebuild goes into a separate temp DB with --no-auto-import and --no-auto-flush, never over the broken canonical file.
- Promotion waits until br show, br sync --status and br doctor pass on the temp DB. They run again on the default path, where the target is dirty_count 0 with neither store newer.
- A rebuild from the harmonized JSONL re-materializes only logical issue data, so bad pages and stale WAL state from the old file stay behind.
- A UNIQUE constraint failure on blocked_issues_cache during br dep add, after a verified rebuild, is recorded as a separate br bug instead of undoing a good recovery.
- Failure signatures cover malformed images, a WAL too small for its header, a zero-byte beads.db, legacy comments.created_at integrity complaints, and a config pointing at a non-canonical DB.
The failure this handles looks like br show returning "database disk image is malformed", or a stale WAL reporting "WAL file too small for header", sometimes while br doctor still passes. When br sync --status reports both jsonl_newer and db_newer, each store holds changes the other lacks: a blind export overwrites the JSONL's, and a blind rebuild drops the database's. The skill's rule is to decide nothing until you know what each store uniquely contains.