blue/.blue/docs/spikes/2026-01-26T1941Z-rfc-id-collision-root-cause.wip.md

Spike: Rfc Id Collision Root Cause

Status	In Progress
Date	2026-01-26
Time Box	1 hour

---

Question

Why is there an RFC ID collision in blue.db when working on multiple RFCs simultaneously? What is the root cause and how do we prevent it?

---

Findings

Evidence

Two blue.db files exist:

• /Users/ericg/letemcook/blue/blue.db — empty (0 bytes), stale artifact at repo root
• /Users/ericg/letemcook/blue/.blue/blue.db — actual database (299KB)

11 RFC numbers have duplicate database entries:

number | count
-------|------
1      | 3
2      | 3
14     | 2
15     | 2
17     | 2
20     | 2
27     | 2
28     | 2
30     | 2
31     | 2
33     | 2

RFC 0033 collision details:

id  | number | title                           | status      | file_path                                          | created_at
----|--------|--------------------------------|-------------|----------------------------------------------------|-----------
24  | 33     | round-scoped-dialogue-files    | implemented | rfcs/0033-round-scoped-dialogue-files.impl.md     | 18:58:43
137 | 33     | Comprehensive Config Arch      | draft       | rfcs/0033-comprehensive-config-architecture.draft.md | 19:35:04

File timestamps:

14:33 — 0033-comprehensive-config-architecture.draft.md (created via Write tool)
14:39 — 0033-round-scoped-dialogue-files.plan.md
14:40 — 0033-round-scoped-dialogue-files.impl.md

Root Cause Analysis

Primary cause: reconcile() doesn't check for number collisions

In store.rs:2031-2034, the reconcile function finds existing documents by matching on file_path:

let existing = self.list_documents(dt)
    .into_iter()
    .find(|d| d.file_path.as_ref() == Some(&relative_path));

This means:

1. Two files with the same number but different filenames are both considered "unindexed"
2. Both get registered via register_from_file() without collision detection
3. Database ends up with multiple entries for the same RFC number

Secondary cause: Write tool bypasses Blue's numbering system

When I created 0033-comprehensive-config-architecture.draft.md using Claude's Write tool instead of blue_rfc_create, it bypassed:

1. Blue's next_number_with_fs() function that scans filesystem for max number
2. Blue's database registration

Then when blue_sync ran (or when the file was otherwise registered), it created a duplicate entry.

Tertiary cause: Concurrent sessions

Two Claude sessions working simultaneously may have:

1. Cached state that doesn't reflect filesystem changes from the other session
2. Race conditions where next_number_with_fs() returns the same number to both

Remediation Options

1. Fix reconcile() — Add collision detection before register_from_file():

   // Check if number already exists for this doc_type
   let number_exists = self.list_documents(dt)
       .into_iter()
       .any(|d| d.number == parsed.number);
   
   if number_exists {
       // Log warning about collision, don't create duplicate
       result.collisions.push(relative_path);
       continue;
   }
   

2. Fix the immediate collision — Delete duplicate database entries:

   -- Keep the older entry, delete the newer one
   DELETE FROM documents WHERE id = 137;  -- comprehensive-config (newer)
   

   Then rename the file to use the next available number.

3. Process improvement — Always use blue_rfc_create for new RFCs, never Write tool directly.

Recommendation

Outcome: recommends-implementation

1. Create RFC to add collision detection to reconcile() function
2. Manually fix current collisions by renaming files and cleaning database
3. Add CLAUDE.md guidance: "Always use blue_rfc_create for new RFCs"