wtf

/wtf (bro)

All mechanics live in the bro CLI over bd. This skill is policy only. A wtf bead is the trigger artifact; a retro bead is the analysis record; prevention beads carry the follow-up work.

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

Commands

Command	What it does
bro wtf <complaint> / bro self retrospect capture <complaint>	Open a wtf bead — the user's complaint verbatim + a git/cwd snapshot
bro self retrospect schema	Print the commented plan template — the schema lives in the CLI, not here
bro self retrospect record <plan.toml>	Validate the plan → close a retro bead with the analysis memo → each [[actions]] item becomes an open prevention bead labeled sink:<sink> → the wtf is closed (retro.wtf, --wtf, or the only open one — auto-linked)
bro self retrospect status	Exit gate — exit 1 while any wtf stays unanswered
bro self retrospect list	Retro beads + open wtf beads

Policy

• Capture before apologizing. The first move is bro wtf '<the user's words, verbatim>' — never a paraphrase, never a softened version. The quote is evidence; every arg is captured literally, ---leading text included (only a leading -h/--help prints usage). Invoke it as a single argv value, single-quoted — escape an embedded ' as '\''. Never double quotes: $() and backticks still expand inside them, and never a compound shell command where metacharacters could execute.
• Analyze your own actions, not the user. The wtf is a defect in the agent's process. Review your recent turns in context: what you were asked, what you assumed, what you skipped. Post-compaction and unsure? Say so — a fabricated confession is worse than none. For real root-causing, bro work drill down first; the drill's memo feeds the plan.
• The plan is the deliverable. bro self retrospect schema → write the file → bro self retrospect record. what/why are mandatory; every [[actions]] item needs a sink — the resource the fix lands in. record auto-answers the only open wtf; with several open, set retro.wtf or pass --wtf to pick.
• The gate decides, not you. Resume normal work only when bro self retrospect status exits 0.
• Route by sink. sink:backlog stays queued; sink:memory → persist to user or project memory (scope decides); sink:agentic-documents → update AGENTS.md/rules/skill files directly; sink:upstream-issue → file it; sink:workaround → implement the fix now.
• Recurrence escalates scope. bro self retrospect list before writing, then bd show <id> on each listed retro to read its why memo — a repeat root cause moves the fix one scope wider along session → agent → user → project → universal.
• Recurrence also escalates the sink. A root cause that already has a prose rule (memory, AGENTS.md, skill text) and still recurred will not be fixed by wider prose — route at least one action to sink:workaround or sink:backlog as a mechanical guardrail (CLI validation, a hook, a schema check). Prose reached the agent and didn't bind; the mechanism must.