jamie-bitflight/evidence-first-debugging

Evidence-First Debugging

Primary responsibilities: observation recording, evidence IDs, causality validation, verification gates.

Shared References

Load these references before producing any investigation output. A references index is available for a quick map of all shared files.

• Unified Investigation Template — the 15-section output structure (sections 0–14)
• Evidence Rules — evidence ID format, truncation disclosure, forbidden phrases
• Causality Gate — classification rules for action-result links

Domain Extensions

Load the applicable extension when the investigation type matches. Insert the extension's sections immediately after section 2 (OBSERVATIONS).

flowchart TD
    Start([Identify investigation type]) --> Q1{Software bug or crash?}
    Q1 -->|Yes| Dbg["Load [Debugging Extensions](../../shared/extensions/debugging-extensions.md)<br>Adds: CALL STACK, RECENT CODE CHANGES, DEPENDENCY GRAPH after section 2"]
    Q1 -->|No| Q2{Latency, throughput, or memory regression?}
    Q2 -->|Yes| Perf["Load [Performance Extensions](../../shared/extensions/performance-extensions.md)<br>Adds: BASELINE METRICS, REGRESSION WINDOW, HOT PATH ANALYSIS, RESOURCE UTILIZATION after section 2"]
    Q2 -->|No| Neither[Proceed with base template only]

Non-Negotiable Rules

Enforce these for every investigation output, without exception.

Rule 1 — Facts only in FACTS / OBSERVATIONS / RESULTS

Write only directly observed signals. Causal language is permitted only when the Causality Gate classification is causal-supported. No guesses, no interpretation, no speculation.

Rule 2 — Label every hypothesis explicitly

Every hypothesis must state what it predicts and include a falsifiable test. Use the form:

H1: [specific causal mechanism]
  Prediction: If H1 is true, we would observe [specific outcome]
  Falsification test: [what would disprove H1]

Rule 3 — Reserve resolved-verified for verified outcomes

Output status: resolved-verified only when section 13 (Verification) contains a passing verification command with an evidence ID. If section 13 is absent or empty, the status must be mitigated, unresolved, or unknown.

Rule 4 — Cite evidence IDs on every claim

Every statement in FACTS or RESULTS must end with an evidence ID in brackets — e.g., [E3]. Statements without a citable evidence ID must be labeled UNKNOWN.

Rule 5 — Disclose all truncated output

When any output is abbreviated, include a truncation disclosure block immediately after the snippet:

TRUNCATED
total lines: <N>
shown: <M>
method: head | tail | grep
fingerprint: <sha256 or key tokens>
command: <exact command used>

Silent abbreviation is prohibited.

Status Options

Choose exactly one per investigation output. Include it in section 14 of the investigation template.

flowchart TD
    Start([Choose investigation status]) --> Q1{Is the issue resolved?}
    Q1 -->|No — still occurring| Unresolved[status: unresolved]
    Q1 -->|Partially — symptoms reduced but root cause unknown| Mitigated[status: mitigated]
    Q1 -->|Yes — fix applied| Q2{Does section 13 contain a passing verification command with evidence?}
    Q2 -->|Yes| Verified[status: resolved-verified]
    Q2 -->|No — verification missing or inconclusive| Unknown[status: unknown]

Output Checklist

Before emitting any investigation output, verify all items.

• [ ] Shared references loaded (investigation template, evidence rules, causality gate)
• [ ] Domain extension loaded if applicable (debugging or performance)
• [ ] All FACTS and RESULTS cite evidence IDs in brackets
• [ ] All hypotheses are labeled explicitly and include falsification tests
• [ ] All truncated output includes a TRUNCATION disclosure block
• [ ] Causality Gate classification present for every action-result link in section 10
• [ ] Status is exactly one of the four valid options
• [ ] resolved-verified is used only when section 13 contains passing verification evidence