drill

/drill (bro)

All mechanics live in the bro CLI over bd. This skill is policy only. A drill frame is a bead labeled drill; nesting uses bd's native --parent hierarchy. There is no .drills/ directory tree and no claim.json — beads IS the memory system.

Prereq: bro on PATH or npx -y @broject/bro@0, bd init done.

Commands

Command	What it does
bro work drill down <title> [--under ID] [--ephemeral]	New child frame under the current leaf (or a root). --ephemeral = wisp, no audit trail
bro work drill up --result T [--prevent T]… [--evidence R]… [--report]	Close the current frame. --result is mandatory (CLI-enforced). --prevent is policy-mandatory when the drill found an error, gap, or reusable lesson — each item spawns a prevention-labeled task linked discovered-from the frame. --evidence records a provenance ref (sha/PR). --report also writes <drill.report.dir>/<id>.md (drills/ by default) — the durable md artifact (frontmatter + result/prevention/trail) for drills done on purpose
bro unwind …	Alias for drill up — collapse a solved frame into its parent
bro work drill current	The active leaf frame (deepest open path)
bro work drill tree	All drill hierarchies (● open / ○ closed)
bro work drill list	Open frames
bro work drill report	Published reports under drill.report.dir (drills/)
bro work drill distill ID	bd mol distill — turn a successful drill tree into a reusable proto/formula

Policy

• Narrow → investigate → ascend → prevent. Descend only into a strictly narrower problem. A frame that returns nothing teaches nothing — the CLI refuses drill up without --result.
• Found a root cause or a reusable lesson? --prevent is the policy, not a suggestion. The CLI can't judge whether a lesson exists — that call is yours; when it does, each item becomes follow-up work in beads, not a footnote.
• Isolation. A child frame gets only task-relevant context; the curated memo lands as a bd note on the closed child (prevention items become beads linked discovered-from it) — never the raw transcript.
• Can't ascend past open children — bd blocks the close; ascend bottom-up.
• Drill → distill → formula is the learning loop: a drill tree that solved a problem well can be distilled into a proto and re-poured next time (bd mol pour/bd mol wisp).
• Reports are intentional. Beads stay the coordination substrate; a committed <id>.md under drill.report.dir (drills/ by default) is the durable output for postmortems and audits. --report forces it; drill.report.mode always covers persistent frames only, prompt asks on a TTY (off non-interactively). When publishing is enabled, drill up writes the file but never commits — it rides the branch.
• Lifecycle is auditable for persistent frames: claim on down, handoff on up, evidence refs as provenance events (bd provenance log <id>). --ephemeral wisps skip all provenance — by design they leave no audit trail.