# Bug Root Cause Analyst Runbook

## Project Context To Prepare
- Project goal
- Current repository or workflow context
- Bug symptoms
- Steps to reproduce
- Logs
- Recent changes

## Input Template
Project:

Goal:

Current context:

Constraints:

Available files, notes, or data:

Expected output:
- Evidence
- Ranked hypotheses
- Fix direction
- Missing evidence

## Starter Inputs
### First useful run
Use this when you know the goal but still need a structured first draft.

Analyze why bookmarks disappear after refresh using browser logs and the storage helper.

Context:
- Current state:
- Constraints:
- Audience:
- Success criteria:

### Project handoff run
Use this when the output will be pasted into a ticket, PR, document, or project brief.

Goal: produce Hypotheses for a real project.
Source material:
- 
Constraints:
- 
Review needs:
- Go deep on the risks and constraints listed above.
- Mark assumptions.
- Flag missing context.

### Boundary check
Use this when the request may be under-specified and you want the agent to narrow it safely.

Explain a production outage from a screenshot of an error toast only.

Before producing the final answer, identify missing required context and propose a stronger prompt if needed.

## Setup Context Notes
- Collect symptoms, logs, reproduction steps, recent changes, and affected environment details.
- Include the target audience, output destination, and any examples of acceptable or unacceptable work.
- Name what should remain out of scope so the agent does not broaden the task.

## Good Input Example
Users cannot bookmark after refreshing; localStorage key exists.

Goal: produce Hypotheses for a real project.
Constraints: keep the result specific, structured, and ready for handoff.

## Weak Input Example
Help me with Bug Root Cause Analyst.

## Weak Input Diagnostics
### Help me with Bug Root Cause Analyst.
- Why it fails: It does not name the project, source material, constraints, audience, or success criteria.
- Stronger input: Analyze why bookmarks disappear after refresh using browser logs and the storage helper. Include current context, constraints, expected output, and review criteria.

### Make this better.
- Why it fails: The agent cannot tell whether better means clearer, safer, faster, more complete, or easier to hand off.
- Stronger input: Improve the output for Bug triage. Optimize for Hypotheses, keep assumptions explicit, and list the changes made.

## Expected Output Shape
- Evidence: the facts given and what each rules in or out
- Hypotheses ranked by likelihood, each with the command or experiment that confirms or kills it
- Fix for the leading hypothesis, with verification and prevention
- Missing evidence to collect if nothing is confirmed
- Other ideas kept to one line each under "Also worth checking"

## Output Checklist
- Every log line, error, environment difference, and recent change the user gave is interpreted
- Each hypothesis has a concrete check with the expected result for each outcome
- No cause is called confirmed before a check confirms it
- Assumptions are marked [ASSUMPTION] and nothing is invented
- Production fixes and data changes are left to a human, with a rollback

## Failure Modes
- The input lacks the project context the agent needs
- A risk or constraint the user named gets a generic line instead of a concrete failure mode and check
- Unrequested extras crowd out depth on what the user asked for
- The agent invents facts, numbers, or approvals that were not provided

## Handoff Tips
- Paste relevant project files, notes, or constraints before asking for the final output.
- Ask for a first draft, then request a stricter revision using the checklist.
- Keep the generated output with the project ticket, PR, proposal, or team document.