53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
# Root-Cause & System Investigation Protocol (`tasks/debug.md`)
|
|
|
|
This protocol defines the standard for deeply investigating bugs, race
|
|
conditions, edge cases, or performance anomalies across local and production
|
|
environments without touching production code.
|
|
|
|
---
|
|
|
|
## 1. Direct Execution Protocol (When You Are Investigating a Bug)
|
|
|
|
When commanded to **"tasks/debug `[SYMPTOMS / ERROR]`"**:
|
|
|
|
1. **Strict Read-Only Production Rule:** Experiment, research, and report ONLY.
|
|
Never modify production source files during an investigation.
|
|
2. **Hermetic Reproduction in `scratch/`:**
|
|
- Create minimal, standalone reproduction scripts or test harnesses in
|
|
`scratch/`.
|
|
- Trace data flows across network ingress, caching tiers (Valkey), database
|
|
(Postgres), and client runtimes.
|
|
3. **Formulate & Test Falsifiable Hypotheses:** Document what was tested, what
|
|
was disproven, and what was definitively verified.
|
|
4. **Deliverable Report:** Output a structured report in
|
|
`scratch/INVESTIGATIVE_REPORT.md` detailing:
|
|
- Verified Root Cause
|
|
- Discarded Hypotheses & Evidence
|
|
- Ranked Architectural Remediation Options (with trade-offs)
|
|
|
|
---
|
|
|
|
## 2. Dispatch Template (When Preparing a Debug Prompt for Jules or External Agents)
|
|
|
|
When commanded to **"tasks/debug a prompt for Jules on `[BUG / ISSUE]`"**, fill
|
|
in and provide the following block:
|
|
|
|
```text
|
|
**Role:** Act as a Principal Systems & Security Investigator.
|
|
|
|
**The Scope:** [Describe anomaly, bug symptoms, error logs, and affected components.]
|
|
|
|
**Directives:**
|
|
- **STRICT CONSTRAINT:** Experiment, research, and report ONLY. Do not modify existing production code or create PRs with production changes.
|
|
- Place all reproduction test scripts and experiments in `scratch/` or hermetic test harnesses.
|
|
|
|
**Your Task:**
|
|
1. Formulate clear, falsifiable hypotheses based on observed logs and symptoms.
|
|
2. Design and execute minimal reproduction scripts or benchmarks in `scratch/` to test each hypothesis in isolation.
|
|
3. Trace data flows through database, caching layers, ingress proxies, and client runtime engines.
|
|
4. Document the definitive root cause and rank potential architectural solutions from most reliable to least, with explicit rationale and trade-offs.
|
|
|
|
**Deliverable:**
|
|
Author an investigative report in `scratch/INVESTIGATIVE_REPORT.md` detailing verified findings, discarded hypotheses, and ranked solutions.
|
|
```
|