# Dedupe Beads

> Merge duplicate or excessively overlapping beads in .beads/beads.jsonl into canonical ones. Run after any batch where 20+ new beads were created.

- Skill: `hoangsonww/dedupe-beads` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hoangsonww/dedupe-beads`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangsonww/dedupe-beads/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hoangsonww (https://skillmd.com/u/hoangsonww)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hoangsonww/dedupe-beads

---


# /dedupe-beads

Large bead batches (100+) always develop duplicates. Run this as a
dedicated pass; don't try to do it inline during polishing.

## Prompt

Use the verbatim prompt at `.flywheel/prompts/dedupe-beads.md`.

## Merge rules

For each pair merged:

- Keep the **richest description** between the pair.
- Take the **union** of `depends_on` and `blocks` edges (dedupe).
- Keep the **higher priority** (lower number wins).
- Preserve **every** test obligation from both beads.
- Update any bead in `.beads/beads.jsonl` that referenced the
  deprecated id.

## Close vs delete

Prefer closing merged-away beads with a `closed_reason` pointing to
the canonical id, rather than deleting the line. Keeps the audit
trail clean.