# Drill

> Use when the user invokes /drill or /unwind, or when a task needs scoped descent — narrower investigation frames with mandatory result+prevention memos. Thin wrapper over the bro CLI: drill frames are beads; bd owns storage, `bro work drill` owns the invariants. Requires `bro` (npx -y @broject/bro@0) and bd.

- Skill: `theplenkov/drill-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/drill-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/drill-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/drill-2

---


# /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                                                                                                                                                                                                                                                                                                                                                                                          |
| `bro plan run drill.toml`                                                | Materialize a declared descent tree (`[[steps]]` under a root `title`) as frames — authoring schema `schemas/plans/drill.schema.json`; `bro plan describe drill` prints it (the example as a TOML template)                                                                                                                                                                                                                                                            |

## 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.

