humansys/raise/rai-bugfix-analyse

Bugfix Analyse

Purpose

Determine the root cause of the bug and decide a fix approach. Select the analysis method based on what information is available — not on an arbitrary complexity tier.

Mastery Levels (ShuHaRi)

• Shu: Follow the selected method strictly, document every hypothesis
• Ha: Combine methods when signals overlap
• Ri: Domain-specific RCA methods (fault trees, SBFL)

Context

When to use: After /rai-bugfix-triage has classified the bug in 4 dimensions.

When to skip: XS bugs where cause is self-evident — but still write analysis.md documenting the obvious cause.

Inputs: Bug ID, work/bugs/{issue_key}/scope.md with TRIAGE block.

Expected state: On bug branch. Scope with triage exists. Bug reproduces.

Steps

Step 1: Select Method Based on Available Signals

Read the scope artifact and determine which signals you have:

Choose the method that matches your signals. If uncertain, default to hypothesis-driven — it's the most general and what LLMs do naturally.

Step 2: Analyse

Execute the selected method:

Stack trace analysis: Follow the error from the surface (exception/log) back through the call chain to the originating defect. Document the path.

git bisect: git bisect start, git bisect bad HEAD, git bisect good {known-good-commit}. Test at each step until the introducing commit is found.

5 Whys: Trace one factual causal chain — ask "Why?" up to five times, each answer evidenced by code. Stop at the actionable root cause.

Hypothesis-driven: List 2-5 hypotheses for the root cause. For each one, define a test (grep, read code, run command), execute it, and record the result:

Narrow to one confirmed root cause. If two remain, escalate to human at GATE 2.

Rule for all methods: "Human error" is never a root cause — ask why the error was possible.

<verification> Root cause stated with evidence. Fix approach decided — not implemented yet. </verification>

<if-blocked> Root cause unclear after analysis → document top 2 hypotheses, escalate to human at GATE 2. </if-blocked>

Step 3: Write Analysis Artifact

Publish work/bugs/{issue_key}/analysis.md via CLI with: method used, root cause, evidence, and fix approach:

Use raise_docs_write MCP tool with doc_type="bugfix-analysis", title="{issue_key}: analysis", content="## Method: {method used}\n\n### Root Cause\n{root cause}\n\n### Evidence\n{evidence supporting root cause}\n\n### Fix Approach\n{one line}", output_path="work/bugs/{issue_key}/analysis.md", cwd="{project_or_worktree_path}". If MCP tools are not available, fall back to:

rai docs write bugfix-analysis \
  --title "{issue_key}: analysis" \
  --stdin \
  --output-path work/bugs/{issue_key}/analysis.md << 'EOF'
## Method: {method used}
 
### Root Cause
{root cause}
 
### Evidence
{evidence supporting root cause}
 
### Fix Approach
{one line}
EOF

git add work/bugs/{issue_key}/analysis.md
git commit -m "bug({issue_key}): analyse — root cause identified
 
Method: {method used}
Root cause: {one line}
Fix approach: {one line}
 
Co-Authored-By: Rai <rai@humansys.ai>"

<verification> Analysis artifact committed with method, root cause, and fix approach. </verification>

Output

STOP HERE. Return your summary to the orchestrator. Do NOT invoke any further skill.

Quality Checklist

• [ ] Method selected based on available signals (not arbitrary tier)
• [ ] Root cause confirmed with evidence (not guessed)
• [ ] Fix approach decided but not implemented
• [ ] Analysis artifact committed
• [ ] "Human error" never accepted as root cause
• [ ] NEVER fix before analysing — symptoms recur without root cause

References

• Previous: /rai-bugfix-triage
• Next: /rai-bugfix-plan