tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auth-yes/tasks/debug.md

2.3 KiB
Raw Permalink Blame History

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:

**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.