code-investigate

Root Cause Investigator

This command invokes the bug-investigator sub-agent for systematic issue analysis of the provided problem statement.

Before invoking the sub-agent or registering artifacts, derive EFFECTIVE_ISSUE_ID:

• If ISSUE_ID is non-empty, use it unchanged.
• Otherwise derive a deterministic lowercase kebab-case slug from PROBLEM_STATEMENT.
• Collapse repeated separators, trim leading/trailing -, and if the slug would be empty use investigation.

Use EFFECTIVE_ISSUE_ID consistently for workspace paths, report paths, and agent inputs.

First emit: Generate RUN_ID as a UUID. Derive RUN_NAME from the problem statement: a brief summary (max 60 chars) prefixed with "Investigate: ".

On session start, emit the status change:

rp1 agent-tools emit \
  --workflow code-investigate \
  --type status_change \
  --run-id {RUN_ID} \
  --name "Investigate: {brief summary}" \
  --step investigating \
  --data '{"status": "running"}'

STATE-MACHINE

stateDiagram-v2
    [*] --> investigating
    investigating --> [*] : done

Invoke the bug-investigator agent with the freeform problem statement and derived issue id:

{% dispatch_agent "rp1-dev:bug-investigator" %} PROBLEM_STATEMENT={PROBLEM_STATEMENT}, ISSUE_ID={EFFECTIVE_ISSUE_ID}, KB_ROOT={kbRoot}, WORK_ROOT={workRoot} {% enddispatch_agent %}

The agent will:

• Analyze problem statement and gather context
• Form and test hypotheses systematically
• Add temporary debugging (tracked and reverted)
• Trace code execution paths
• Identify root cause with evidence
• Generate comprehensive investigation report
• Propose solutions with effort estimates
• Report back with findings

Emit btw_update events for key findings during the investigation:

rp1 agent-tools emit \
  --workflow code-investigate \
  --type btw_update \
  --run-id {RUN_ID} \
  --data '{"message": "{finding summary}"}'

After the agent writes the investigation report, register it as an artifact:

rp1 agent-tools emit \
  --workflow code-investigate \
  --type artifact_registered \
  --run-id {RUN_ID} \
  --step investigating \
  --data '{"path": "issues/{EFFECTIVE_ISSUE_ID}/investigation_report.md", "storageRoot": "work_dir", "format": "markdown"}'