/wbDebug — Exhaustive Simulation ()
/wbDebug is the diagnostician. Its job is root-cause analysis, not patch attempts. It reads a stack trace, a failing test, or a description of unwanted behavior, and produces a theory of what's broken and why — citing evidence at every step. It does not fix. It hands the diagnosis to /wbWork (or to the user) with enough context that the fix can be made deliberately.
Read this if you want to know why /wbDebug has no flags, what counts as a usable diagnosis, and where the boundary sits between "diagnose" and "fix."
1. Role & target
| Aspect | Behavior |
|---|---|
| Role | The Diagnostician — root cause + evidence chain. |
| Target | A failing test name, a stack trace, an error message, a user-described symptom, or a file the user suspects. |
| Cell scope | None. Output is a diagnosis report, not a plan mutation. |
| Side effects allowed | Reading code, reading test output, reading logs, running read-only diagnostic commands (grep, file inspection). |
| Side effects forbidden | Editing source code, applying fixes, mutating plan cells, running anything that changes state. |
The "no patch attempts" rule is the design center. A diagnostic that says "I think it's broken here, and I fixed it" loses both the theory (because the user can't follow the reasoning) and the fix (because the fix is now bundled with potentially-wrong reasoning). /wbDebug separates the two: a diagnosis you can read and verify, then /wbWork --id="<row>" to actually fix it.
2. Argument resolution matrix
/wbDebug is intentionally forgiving on input format because real debug starts from messy evidence. It accepts whatever the user has.
| Form | Example | What /wbDebug does |
|---|---|---|
| Stack trace (multi-line) | Pasted JS/Python/Vue trace in argument | Parses frames, identifies the deepest user-code frame, follows from there. |
| Error message string | Command: /wbDebug "Cannot read property 'map' of undefined" | Searches workspace for code paths that could produce this error; ranks by likelihood. |
| Failing test name | Command: /wbDebug "WBCodeSlot.spec.js > renders empty slot" | Reads the test, reads the code under test, walks the assertion that fails. |
| Symptom description | Command: /wbDebug "WBDataViewer apiResponse_ stale on route change" | Maps symptom to candidate code areas using both source and memory. |
| Suspect file | Command: /wbDebug core2/packages/wb-core/src/WBC.js | Treats the file as the locus; looks for issues consistent with the user's framing. |
| Bug report URL | (e.g., a GitHub issue number) | Refuses if the URL isn't local. /wbDebug does not fetch external resources. |
The forgiving input is paired with a strict output contract: every diagnosis names a specific file/line/symbol, a specific cause, and an evidence chain. Vague inputs are fine; vague outputs are not.
3. Flag matrix
/wbDebug has no flags (per the canonical the agent flag map). This is deliberate. Debugging that needs flags to refine its output usually wants /wbAudit --profile="<x>" instead — a flag-driven adversarial scan, not a diagnostic. /wbDebug's output shape is fixed: theory + evidence + recommended next step.
| What you might want | What to use instead |
|---|---|
| "Just fix it for me" | /wbDebug to diagnose, then /wbWork --id="<row>" to fix. |
| "Scan many files for similar issues" | /wbAudit --profile="correctness". |
| "Diagnose and add a row to the plan" | /wbDebug (read the diagnosis), then /wbPlan --task="bugfix" "<diagnosis summary>". |
| "Find all failing tests" | /wbTest --profile="all". /wbDebug is for one failure at a time. |
The single-failure-at-a-time rule is the second design center. Debugging a batch of failures together produces shallower diagnoses than debugging them individually — the agent's attention dilutes. The convention is: run /wbTest to enumerate failures, then /wbDebug per failure.
4. Pipelines (the agent-native scenarios)
/wbDebug "WBDataViewer apiResponse_ stale on route change"> /wbDebug "WBDataViewer apiResponse_ stale on route change"💠 Pipeline The WBDataViewer apiResponse_ stale-cache symptom
A real symptom that surfaces in this workspace: the project changes via the route, but the data viewer keeps showing the previous project's response. The memory note project_wbdataviewer_apiResponse.md describes the cache pattern but doesn't say what's wrong. The user runs /wbDebug to find out:
💠 Pipeline Stack trace from a failing build
A vite build fails with an obscure trace. The user pastes it:
💠 Pipeline A test failure with no obvious cause
A unit test fails intermittently. The user pastes the test name:
5. Edge cases & refusals
| Trigger | What /wbDebug does |
|---|---|
| No symptom/target provided | Halt. ❌ Provide a stack trace, error message, test name, or symptom description. |
User asks /wbDebug to fix the bug | Refuse politely. /wbDebug produces diagnoses; fixes are /wbWork's job. |
| Symptom matches no code or test in the workspace | Honest "could not localize." Suggests checking dependencies or build artifacts. |
| Multiple plausible causes | Rank by evidence strength; present the top theory plus 1-2 alternatives. |
| Memory contradicts the user's framing (e.g., "X is broken" but memory says "X was deliberately removed") | Surface the contradiction. Ask whether the user wants to revive X or accept that it's gone. |
| External URL given | Refuse. /wbDebug does not fetch. Paste the relevant content into the argument. |
| Stack trace from a dependency (no user code in the trace) | Diagnose the call site in user code, not the dependency. Note that the upstream may be broken but is out of scope. |
The unifying rule: /wbDebug produces theories, not patches. Every diagnosis is a hypothesis the user can verify against the cited evidence. When the agent is uncertain, it says so; when memory contradicts the framing, it surfaces that contradiction. The diagnosis is a handoff document, not a finished work item.