atomic-bead-filing

name	atomic-bead-filing
description	Use when noticing something off (code smell, design smell, workaround) while working and want to capture it without losing flow - grounds observation in codebase and files a proper bead that future agents can execute

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):

Flag	When to use
--type task	Default. Use bug if actively broken, feature for new capability
--priority	P0 critical (security/data loss), P1 high (bugs/blockers), P2 medium, P3 low (polish), P4 backlog - default to your judgment based on impact
--labels human-needed	Multiple valid approaches exist (see below)
--deps discovered-from:<id>	Main agent was working on a specific bead
--acceptance	Fill if obvious - what would "done" look like?
--design	Fill if obvious - brief notes on approach/constraints

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*"