| name | bug-protocol |
| description | The "loudly declare" protocol for platform, engine, or data bugs during a NexusTrade certification campaign — bugs are a first-class deliverable, not something to route around. Use whenever a NexusTrade tool errors, hangs, or returns numbers that contradict the config; whenever you're tempted to write "probably an engine quirk"; or when a discovered bug invalidates prior backtests and results must be quarantined. Includes the bug hand-off doc template (see references/BUG_TEMPLATE.md). |
| license | MIT |
| metadata | {"author":"Austin Starks","version":"1.0.0","created":"2026-07-03T00:00:00.000Z","last_reviewed":"2026-07-03T00:00:00.000Z","review_interval_days":90} |
| activation | /bug-protocol |
| provenance | {"maintainer":"Austin Starks","source":"public-portfolio-challenge episode-10 / episode-11 runbooks"} |
Bug Protocol — "Loudly Declare"
The compute + engine stack is new and moves. Every failure gets this protocol. Never paper over an
error to keep a campaign moving — a swallowed bug is worse than a blocked stage. A confabulated
mechanism (inventing why the engine did something) is the worst failure mode: the campaign's worst
moments have been confabulated reconcile events, pricing behavior, and budget behavior. Verify,
don't assert.
Precedent: a totalBudget over-deployment bug (a book with a 40% budget deployed ~96% of NAV at cold
start) was caught exactly this way and invalidated weeks of results. See
episode-11/attempt2/TOTALBUDGET_BUG.md for the canonical worked example.
The five steps (apply on every failure)
- Stop and characterize — is it config (my fault), data (source-side), or engine (NexusTrade)?
Reproduce minimally — the smallest job/backtest that still shows it.
- Log it immediately in the run's
CAMPAIGN_LOG.md under a ⚠️ BUG/ISSUE heading: symptom,
repro IDs, expected-vs-observed, current hypothesis (labeled hypothesis), what it blocks.
- If it's a real engine/data bug, write a hand-off doc
<NAME>_BUG.md in the run directory,
modeled on the template in references/BUG_TEMPLATE.md (one-line summary, expected vs observed,
reproduction with IDs, leading hypothesis, alternatives to rule out, where to look, impact on
results).
- Quarantine affected results — mark every backtest/study that ran before the fix as
suspect/invalid. Re-run after the fix. If the bug inflated leverage, both returns AND drawdowns are
inflated and any sweep gene it touched may be non-differentiating — re-validate all of it.
- Tell the human, prominently, in the chat. Bugs are a co-equal deliverable of the episode with
the trading result — not an embarrassment to route around.
What is NOT a bug (honest-signal failures — don't file these)
- A fold returning
NoEligibleCandidate = an honest signal, not a bug. Widen validation; don't drop
the certification floors.
- A dead / not-yet-listed name (e.g. SNDK in 2022) being absent or in a reject list with no
fabricated values = correct behavior. The engine fabricating a price/indicator value for a name
that didn't trade IS a bug (see engine-sanity).
- A single-tick reconcile target = the live strategy accretes the rest over daily rebalances — say so,
don't re-diagnose it as a bug (see deploy-gate).
Verify-don't-assert checklist
Before writing any claim about engine behavior into a deliverable, back it with one of:
query_backtest_events / query_portfolio_events, a conditionFieldAudit, or a minimal
reproduction. "The engine probably…" is not evidence.
