Beads

# Beads Anti-Patterns

Hard-won lessons from production beads usage. Avoid these mistakes.

---

## Critical Anti-Patterns

### 1. Treating `.beads/issues.jsonl` as the Canonical Tracker

**DON'T**: Use `.beads/issues.jsonl` as your primary source for what is ready or what notes say when live `bd` commands are available

```bash
# WRONG
jq '.[] | select(.status=="open")' .beads/issues.jsonl
```

**DO**: Use live `bd` queries first

```bash
# CORRECT
bd ready --json
bd show <id> --json
```

**Why it breaks**:
- Export files can lag behind live tracker state
- Autonomous runs make bad routing decisions when they trust stale JSONL
- Parent notes and status can already be reconciled in Dolt even if the export was not refreshed

---

### 2. Molecule-Style Issue IDs

**DON'T**: Create issues with dot-separated hierarchical IDs

```bash
# WRONG - These IDs corrupt the database
code-map-validation.calculate-coverage
etl-throughput-optimization.enable-parallel-sync
kagent-openwebui-bridge.admin-functions
```

**DO**: Use standard `prefix-xxxx` format

```bash
# CORRECT - Standard beads ID format
ap-7tc6
ap-euoy
ap-cr7k
```

**Why it breaks**:
- bd expects IDs in `prefix-hash` format
- Dot-separated IDs fail prefix validation during import
- JSONL-based repair via `bd doctor --fix --source=jsonl` errors with "invalid suffix"
- Database becomes corrupted, requiring full rebuild

**Root cause**: Early formula/molecule templates created non-standard IDs. This was a design mistake.

**Fix**: If you have molecule-style IDs, filter them out or rebuild:
```bash
# Filter to standard format only
grep -E '"id":"[a-z]+-[a-z0-9]+' .beads/issues.jsonl > clean.jsonl
mv clean.jsonl .beads/issues.jsonl
bd doctor --fix --source=jsonl --yes
```

---

### 3. Prefix Proliferation

**DON'T**: Mix multiple prefixes in one database

```bash
# WRONG - Multiple prefixes in same .beads/
code-map-validation
etl-throughput-optimization
kagent-openwebui-bridge
ap-1234
```

**DO**: One prefix per beads database

```bash
# CORRECT - Single prefix
ap-1234
ap-5678
ap-abcd
```

**Why it breaks**:
- JSONL-based repair fails with "prefix mismatch detected"
- Database configured for one prefix rejects others
- Cross-prefix dependencies don't resolve correctly

**Root cause**: Formulas/molecules created issues with their own prefixes instead of the database's prefix.

**Fix**: Enforce single prefix policy:
```bash
# Check for prefix violations
grep -o '"id":"[^-]*' .beads/issues.jsonl | sort -u
# Should show only ONE prefix
```

---

### 4. Assuming Tracked JSONL Stays Synced Automatically

**DON'T**: Mutate tracker state and assume `.beads/issues.jsonl` will stay current by itself

```bash
# WRONG
bd update ap-1234 --notes "Remaining gap narrowed to CLI parity"
# keep working without exporting tracked JSONL
```

**DO**: Refresh the tracked export explicitly after tracker writes

```bash
# CORRECT
bd update ap-1234 --notes "Remaining gap narrowed to CLI parity"
bd export -o .beads/issues.jsonl   # if tracked
```

**Why it matters**:
- The export is a git artifact, not a guaranteed live mirror
- Git history becomes misleading when tracked exports are stale
- Other agents may diff the export and see outdated state

---

### 5. Closing Child Issues Without Reconciling the Parent

**DON'T**: Close a child bead and leave the parent's stale "remaining gap" notes untouched

```bash
# WRONG
bd close pl-vnu.4 --reason "Fixed the exact remaining gap"
# parent still says the gap is open
```

**DO**: Reconcile the open parent in the same session

```bash
# CORRECT
bd close <child-id> --reason "Closed concrete remaining gap"
bd show <parent-id>
bd update <parent-id> --notes "Remaining gap now ..."
# or bd close <parent-id> when nothing real remains
```

**Why it matters**:
- Stale parent notes create false backlog
- `bd ready` can surface umbrella work that is already effectively done
- Autonomous loops lose trust in tracker state

---

### 6. Implementing Broad Parent Beads Directly

*