Booth DJ — Hard Constraints for Bug Handling
These are MUST/NEVER rules that bind DJ when receiving any bug-shaped input. Companion to booth-dj (which carries the protocol detail). Pairs with the rules-as-skills meta-rule installed on this machine.
Trigger
A user message that reports any of:
- A failing behavior, regression, unexpected output, or "X doesn't work"
- A previous fix being insufficient or causing a side effect
- Daemon, deck, or skill misbehaving in their session
Treat these as bug reports even when the user does not say the word "bug".
MUST
MUST capture phenomenon verbatim before forming any hypothesis. Record what the user observed, not what the user thinks happened. A user statement like "X is bypassed" is a hypothesis from the user's side, not a phenomenon — extract the underlying observation ("alert appeared but no commit landed on main") and treat the user's hypothesis as one candidate to verify, not as fact.
MUST read existing design before dispatching a fix. At minimum: find and grep the backstage design/ and progress/ trees for related topics, plus inline // BUG-XXX: comments on the relevant source. If a design doc names the load-bearing invariants of the affected module, quote them in the dispatch prompt.
MUST verify phenomenon with first-party evidence before recording. Daemon log lines, git log, peek output, and direct file reads — not user description alone. If evidence contradicts user framing, raise the contradiction openly; do not silently re-frame.
MUST identify which layer the bug lives at (symptom / mechanism / design) before choosing a fix direction. State the chosen layer in the dispatch prompt.
MUST re-validate the original concern when overriding a previous fix. If a new bug points at a previous fix's side effect, audit whether the previous fix's underlying problem still exists. Re-state that problem and explain how the new direction addresses both.
MUST include all of this in the dispatch prompt: phenomenon (verbatim), evidence (log lines / SHAs), design intent (quoted from docs), hypothesized layer, named existing fixes the deck must not break, E2E proof requirement.
NEVER
NEVER record a bug entry and dispatch a fix in the same turn. A research step is required between them. The minimum is reading design + verifying phenomenon. Fast turnaround is not a virtue here — it is the failure mode.
NEVER copy the user's hypothesis into a BUG-XXX entry as the root cause. Phenomenon goes in the bug entry. Hypothesized cause goes in a separate "investigating" line, marked as a hypothesis until evidence confirms it.
NEVER write a deck prompt of the form "remove / delete / revert X to fix Y" without quoting the design intent of X. If the deck cannot see the design intent, it will execute the literal removal — and that is the monkey-paw failure.
NEVER let three or more consecutive fixes land in the same module without pausing for a design audit. Symptom-layer patches accumulate. When the count hits three, stop and re-examine the module's state machine before adding a fourth patch.
NEVER override or revert a previous BUG-XXX fix without first asking: "is the original problem still present, or has it been moved/solved elsewhere?" Override requires explicit answer to that question.
NEVER dispatch a fix prompt that lacks an E2E proof requirement. Compilation is not E2E. "Read the code and reason" is not E2E. The deck must produce evidence the runtime path was exercised — log lines, observed state changes, before/after snapshots.
NEVER patch a layer's internals before asking whether the layer is needed at all. When the bug lives in a middleware (parsing / caching / preprocessing / format conversion), the first question is "what happens if this layer disappears?" — not "what's wrong inside this layer?". If the data source is accessible to downstream consumers without the layer, deleting the layer is almost always preferable to fixing its bug. Past failure: BUG-030 round 1 added a filter to the pre-compact predigest hook; round 2 deleted the predigest entirely. The round 1 patch was wasted because nobody asked the layer-necessity question first.
How to Apply
When the user message triggers this skill:
- Stop. Do not yet write any "BUG-XXX" entry, do not yet write any deck prompt.
- Open
booth-dj skill if not already loaded — its "Research-First Bug Protocol" Steps 1–6 are the procedure.
- Walk the steps in order. Each step has an output (recorded phenomenon, design quote, evidence excerpt, layer label, stress-test result, dispatch prompt).
- Only after Step 6 produces a fully-contextualized prompt: dispatch.
- After dispatch: log to
progress.md what was done, including the design quote and layer label so future DJ sessions can audit.
Why
Past failure (booth daemon session, 2026-05-07): user reported many small bugs over a long session. DJ recorded each bug verbatim from user words, treated each as standalone, dispatched a fix per bug. Result: 11 "fixes" merged. After audit, several reopened (BUG-024 fix had to be reverted; BUG-019 fix had a hidden gate that re-broke today; BUG-005 fix accumulated 21 stale worktrees by violating original design; BUG-022 fix added complexity but did not solve the underlying deck-protocol issue). User reaction: "你是怎么做到每次解决一个 bug 就会诞生 3 个新 bug 的". The session was net-negative — value delivered did not exceed regressions introduced.
The lesson: in a system as interconnected as Booth, where a single daemon module already carries 11+ patched concerns, you cannot fix at the symptom layer without breaking neighbors. Research-first is not optional. The cost of pausing to audit is far smaller than the cost of regressions.
1---2name: booth-dj-rules3description: Hard constraints for booth DJ when investigating bugs and dispatching fixes. MUST do design research before recording a bug or writing a fix prompt. MUST separate phenomenon from cause. NEVER dispatch a fix in the same turn the bug was reported. NEVER revert a previous fix without re-validating its original concern. NEVER let a fix prompt omit design intent. Activates when BOOTH_ROLE=dj and the user reports a bug, symptom, regression, or unexpected behavior.4---56# Booth DJ — Hard Constraints for Bug Handling78These are MUST/NEVER rules that bind DJ when receiving any bug-shaped input. Companion to `booth-dj` (which carries the protocol detail). Pairs with the `rules-as-skills` meta-rule installed on this machine.910## Trigger1112A user message that reports any of:13- A failing behavior, regression, unexpected output, or "X doesn't work"14- A previous fix being insufficient or causing a side effect15- Daemon, deck, or skill misbehaving in their session1617Treat these as bug reports even when the user does not say the word "bug".1819## MUST2021- **MUST capture phenomenon verbatim before forming any hypothesis.** Record what the user *observed*, not what the user *thinks happened*. A user statement like "X is bypassed" is a hypothesis from the user's side, not a phenomenon — extract the underlying observation ("alert appeared but no commit landed on main") and treat the user's hypothesis as one candidate to verify, not as fact.2223- **MUST read existing design before dispatching a fix.** At minimum: `find` and `grep` the backstage `design/` and `progress/` trees for related topics, plus inline `// BUG-XXX:` comments on the relevant source. If a design doc names the load-bearing invariants of the affected module, quote them in the dispatch prompt.2425- **MUST verify phenomenon with first-party evidence before recording.** Daemon log lines, git log, peek output, and direct file reads — not user description alone. If evidence contradicts user framing, raise the contradiction openly; do not silently re-frame.2627- **MUST identify which layer the bug lives at** (symptom / mechanism / design) before choosing a fix direction. State the chosen layer in the dispatch prompt.2829- **MUST re-validate the original concern when overriding a previous fix.** If a new bug points at a previous fix's side effect, audit whether the previous fix's underlying problem still exists. Re-state that problem and explain how the new direction addresses both.3031- **MUST include all of this in the dispatch prompt**: phenomenon (verbatim), evidence (log lines / SHAs), design intent (quoted from docs), hypothesized layer, named existing fixes the deck must not break, E2E proof requirement.3233## NEVER3435- **NEVER record a bug entry and dispatch a fix in the same turn.** A research step is required between them. The minimum is reading design + verifying phenomenon. Fast turnaround is not a virtue here — it is the failure mode.3637- **NEVER copy the user's hypothesis into a `BUG-XXX` entry as the root cause.** Phenomenon goes in the bug entry. Hypothesized cause goes in a separate "investigating" line, marked as a hypothesis until evidence confirms it.3839- **NEVER write a deck prompt of the form "remove / delete / revert X to fix Y" without quoting the design intent of X.** If the deck cannot see the design intent, it will execute the literal removal — and that is the monkey-paw failure.4041- **NEVER let three or more consecutive fixes land in the same module without pausing for a design audit.** Symptom-layer patches accumulate. When the count hits three, stop and re-examine the module's state machine before adding a fourth patch.4243- **NEVER override or revert a previous BUG-XXX fix without first asking: "is the original problem still present, or has it been moved/solved elsewhere?"** Override requires explicit answer to that question.4445- **NEVER dispatch a fix prompt that lacks an E2E proof requirement.** Compilation is not E2E. "Read the code and reason" is not E2E. The deck must produce evidence the runtime path was exercised — log lines, observed state changes, before/after snapshots.4647- **NEVER patch a layer's internals before asking whether the layer is needed at all.** When the bug lives in a middleware (parsing / caching / preprocessing / format conversion), the first question is "what happens if this layer disappears?" — *not* "what's wrong inside this layer?". If the data source is accessible to downstream consumers without the layer, deleting the layer is almost always preferable to fixing its bug. Past failure: BUG-030 round 1 added a filter to the pre-compact predigest hook; round 2 deleted the predigest entirely. The round 1 patch was wasted because nobody asked the layer-necessity question first.4849## How to Apply5051When the user message triggers this skill:52531. Stop. Do not yet write any "BUG-XXX" entry, do not yet write any deck prompt.542. Open `booth-dj` skill if not already loaded — its "Research-First Bug Protocol" Steps 1–6 are the procedure.553. Walk the steps in order. Each step has an output (recorded phenomenon, design quote, evidence excerpt, layer label, stress-test result, dispatch prompt).564. Only after Step 6 produces a fully-contextualized prompt: dispatch.575. After dispatch: log to `progress.md` what was done, including the design quote and layer label so future DJ sessions can audit.5859## Why6061Past failure (booth daemon session, 2026-05-07): user reported many small bugs over a long session. DJ recorded each bug verbatim from user words, treated each as standalone, dispatched a fix per bug. Result: 11 "fixes" merged. After audit, several reopened (BUG-024 fix had to be reverted; BUG-019 fix had a hidden gate that re-broke today; BUG-005 fix accumulated 21 stale worktrees by violating original design; BUG-022 fix added complexity but did not solve the underlying deck-protocol issue). User reaction: "你是怎么做到每次解决一个 bug 就会诞生 3 个新 bug 的". The session was net-negative — value delivered did not exceed regressions introduced.6263The lesson: in a system as interconnected as Booth, where a single daemon module already carries 11+ patched concerns, you cannot fix at the symptom layer without breaking neighbors. Research-first is not optional. The cost of pausing to audit is far smaller than the cost of regressions.
motiful