Question about traceability and patching up incorrect work

[bath-tub]

Hello. I am a new beads user in one of my first couple projects. I have a large 100 bead list created with hierarchal ordering and have had the agents iterate over it until they no longer find work to do.

Before I dive into unleashing agents on the task list, how do I ensure that a feature or epic that is incorrectly implemented has traceability or ties to beads? This may be a simple / obvious answer but I am also struggling in finding docs or information about how an ideal workflow looks like.

Is there a best practice for this? Simply tell the agent X thing is not implemented correctly with direction on what it should be and to reference git commit history and beads for relevant context? And the rest is just magic?

I think many of my questions stem from reading: #976

If I don't get to it first, a guide on not FAQs or how beads works as I think I understand those bits enough would be I think quite helpful. Common areas / gotchas and quirks of using this new development flow especially for many new users who may just be dipping their toes into agent heavy workflows.

[peterkc]

I run beads across 4 projects (~1,500 issues, ~580 closed) with Claude Code. Traceability is the area I've iterated on most.

Where beads fits in the agent workflow

              Agent Session
              ============

PICK WORK     bd ready --> choose issue
                  |
LOAD CONTEXT  bd show <id>           <-- agent reads description, notes, design
                  |
IMPLEMENT     write code, run tests
                  |
              bd update <id> --append-notes="session log"
                  |
VERIFY        does the code match the intent?
                  |
              +---+---+
              |       |
             OK     WRONG ----------> CREATE BUG
              |                       bd create --type=bug
              |                       bd dep add <bug> <original>
              |                       (loops back to PICK WORK)
CLOSE         |
              v
              bd close <id> --reason="what changed + commit ref"

Traceability breaks down wherever an agent skips a step. The four common gaps:

Gap	What happens	Fix
No description at creation	Agent guesses what to build	Write requirements in --description, approach in --design
No context loading	Agent ignores prior work	AGENTS.md instructs bd show <id> before coding
No session log	Can't tell what happened last session	--append-notes after work (never --notes — that overwrites)
No close reason	Can't trace code back to bead	bd close --reason="commit ref + summary"

AGENTS.md: the lever that makes traceability work

Beads stores the data, but the agent only records what you tell it to. Without instructions, you get titles with empty descriptions — and titles aren't traceable.

Claude Code note: Claude Code reads CLAUDE.md, not AGENTS.md. Add @AGENTS.md to your CLAUDE.md to import it (docs). Other tools (Codex, Cursor, Copilot, Gemini CLI) read AGENTS.md directly.

Add this to your AGENTS.md:

## Working on Issues

When starting a bead:
1. Run `bd show <id>` first — read description, notes, and design
2. After work, log context: `bd update <id> --append-notes="what was done, what worked, what failed"`
3. Close with a reason: `bd close <id> --reason="what changed + commit ref"`

When something is implemented wrong:
1. Create a bug: `bd create --title="Fix: <what's wrong>" --type=bug --priority=1`
2. Link it: `bd dep add <bug-id> <original-id>`
3. Describe what's wrong and reference the original bead in --description

Never use `--notes` (overwrites). Always `--append-notes`.

Verifying the agent built what the bead describes

The hardest traceability gap sits between IMPLEMENT and VERIFY. The agent closes a bead and moves on. The code may not match the bead's intent.

Tests catch functional errors. For structural intent ("is the auth flow using PKCE, not implicit grant?"), semantic code search fills the gap. I use colgrep to verify implementations match the bead description:

# Bead says "implement PKCE auth flow" — verify the code matches:
colgrep "PKCE authentication flow" src/auth/

# Bead says "add retry with backoff" — verify:
colgrep "retry with exponential backoff" src/api/

Targeted grep works too, but the semantic match catches cases where the agent used different terminology than the bead. That semantic gap — between what the bead says and what the code does — is where "incorrectly implemented" hides.

Add this to your AGENTS.md to make verification a habit:

## Verify Before Closing

Before closing any bead, verify the implementation matches the description:
1. Re-read the bead: `bd show <id>` — note the key requirements
2. Semantic check: `colgrep "<key requirement from description>" <changed-directory>/`
3. Pattern check: `grep -rn "<expected identifier or pattern>" <changed-files>`
4. If either check shows a mismatch, do not close — append what's missing to `--append-notes`

Install colgrep: see official docs for macOS, Linux, and Windows options.

Corrective workflow: when a feature is wrong

Don't reopen the original bead. Create a new bug and link it:

# 1. Create bug with context
bd create --title="Fix: OAuth uses implicit grant instead of PKCE" \
  --type=bug --priority=1

# 2. Link to original feature
bd dep add <bug-id> <original-feature-id>

# 3. Describe the divergence
bd update <bug-id> --description="Login feature (<original-id>) implemented OAuth \
  incorrectly. See bd show <original-id> for requirements. Should use PKCE per spec."

# 4. When fixed, close with evidence
bd close <bug-id> --reason="Fixed in commit abc1234. Changed OAuth flow to PKCE."

bd dep add creates a bidirectional link — bd show on either bead shows the connection. The close reason ties the fix back to a specific commit.

Automating the discipline

The AGENTS.md approach works on its own, but Claude Code can also enforce traceability through rules (always-on behavioral constraints) and hooks (shell commands triggered at lifecycle events).

Session start hook (.claude/settings.json):

{
  "hooks": {
    "SessionStart": [{ "command": "bd ready 2>/dev/null || true" }]
  }
}

Traceability rule (.claude/rules/beads-traceability.md):

# Beads Traceability

- Always run `bd show <id>` before implementing any bead
- Always close beads with `--reason` including the commit ref
- Use `--append-notes` (never `--notes`) for session context
- When finding incorrect implementations, create a bug bead and link with `bd dep add`

The hook surfaces available work at session start. The rule teaches Claude the recording discipline without you having to repeat it in every conversation. Together they automate the PICK, LOAD, CLOSE, and CORRECTIVE steps from the diagram above.

What 1,500 issues taught me

• Empty descriptions are the bd dep tree mostly broken #1 traceability killer. Steve found 17.5% of beads in his own projects had empty descriptions (Anybody else having trouble getting CC to put any details into issues? #366). Explicit AGENTS.md instructions brought mine to near zero.
• Close reasons cost 2 seconds, save 20 minutes. When debugging "what changed three sessions ago," the close reason with a commit ref is the fastest path.
• Dependencies are your revision graph. Feature A spawns Bug B spawns Fix C — the bd dep add chain tells the full story with bd show on any node.
• bd show is the real session start. Good context in the bead = good agent output. Empty bead = the agent guesses.

Your 100-bead hierarchical setup already covers the planning layer. The gap you're feeling is the recording discipline at each lifecycle stage — and the AGENTS.md instructions that enforce it.