Atomic Bead Filing

Overview

File beads that future agents can execute with zero shared context. You receive an observation, ground it in the codebase, and create a bead that stands alone.

When to Use

• Main agent noticed something off while working
• Need to capture it without derailing current task
• Want a proper bead, not a vague note

Core Principle

A bead is good if a stranger-agent can execute it knowing ONLY:

1. The bead's description
2. The codebase (via search/read)

They should NOT need: conversation history, the observer's context, or clarification.

Workflow

1. Receive observation from main agent (you have conversation context)
2. Explore codebase to ground it - find specific files, line numbers, patterns
3. Ask questions via AskUserQuestion if genuinely unclear
4. Determine actionability:
   • Clear path → actionable bead
   • Multiple valid approaches → add human-needed label, describe options
5. File bead with bd create
6. Sync with bd sync (just git commit isn't enough - beads live on beads-sync branch)
7. Return bead ID + full bead details so main agent sees what was filed

Bead Structure

Title: Concise, grounded summary (not vague)

• Bad: "Fix type issues"
• Good: "RuleViolation missing priority field - Rust hardcodes HIGH"

Description: The concrete issue

## What's Wrong
[Specific problem - what IS off, grounded in files]

## Where
[Exact file paths, line numbers]

## Why It Matters
[What could go wrong, why this is tech debt]

## Files to Study
- path/to/file.rs (the problematic code)
- path/to/related.py (the other side of the mismatch)

Fields to set (run bd create --help to see all available):

Fold context into description footer:

---
*Discovered while: [what triggered this observation]*

human-needed Label

Use when there are forks requiring human decision:

• Multiple valid architectural approaches
• Trade-offs that depend on priorities you don't know
• Breaking changes vs. compatibility concerns

When using human-needed, add to description:

## Decision Needed
[Specific question]

## Options
1. **Option A**: [approach] - [pros/cons]
2. **Option B**: [approach] - [pros/cons]

What NOT to Do

• Don't file vague beads ("look into this")
• Don't propose fixes unless obvious (focus on WHAT is off)
• Don't skip grounding (always find specific files)
• Don't ask unnecessary questions (use conversation context + codebase)

Example

Input from main agent: "The severity is hardcoded in transform.rs. Noticed while adding analyzer endpoint."

Your process:

1. Search for severity in transform.rs
2. Find line 250: parse_severity("HIGH")
3. Trace back - where should severity come from?
4. Find RuleViolation struct doesn't have severity field
5. Find Python RuleViolationDto DOES have priority field
6. Ground the full issue

Output bead:

bd create "RuleViolation drops priority - Rust hardcodes HIGH severity" \
  --type task \
  --priority 1 \
  --acceptance "Rust RuleViolation receives and uses Python's computed priority" \
  --description "## What's Wrong
Rust transform hardcodes severity to HIGH, ignoring Python's computed priority.

Line 250 in transform.rs:
\`\`\`rust
let priority = parse_severity(\"HIGH\").unwrap_or(RuleSeverity::Medium);
\`\`\`

## Where
- oxide/server/src/eval/transform.rs:250 (hardcoded value)
- oxide/server/src/eval_client.rs:165-173 (RuleViolation missing priority field)
- src/app/features/evaluation/contracts/rules_contracts.py:62-75 (RuleViolationDto HAS priority)

## Why It Matters
Python evaluator computes actual priority per-violation, but Rust discards it. All violations appear HIGH priority regardless of actual severity. Silent data loss.

## Files to Study
- oxide/server/src/eval/transform.rs (the transform)
- oxide/server/src/eval_client.rs (HTTP receive types)
- src/app/features/evaluation/contracts/rules_contracts.py (Python source types)

---
*Discovered while: adding analyzer endpoint*"