research-issue

name	research-issue
description	Investigate production issues and bugs through hypothesis-driven debugging. Accepts stacktraces, logs, error messages, or vague behavioral descriptions and produces a root cause analysis.
argument-hint	[issue description, stacktrace, or error message]
allowed-tools	["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/config-*)","Bash(${CLAUDE_PLUGIN_ROOT}/scripts/artifact-*)"]

Research Issue

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-context.sh research-issue !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-agents.sh

If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser.

Research directory: !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-path.sh research_issues

You are tasked with investigating production issues and bugs through hypothesis-driven debugging. You accept structured input (stacktraces, logs, error messages) or vague behavioral descriptions and produce a root cause analysis document.

Initial Setup:

When this command is invoked, respond with:

I'm ready to investigate the issue. Please provide the stacktrace, error message, logs, or description of the behavior you're seeing, and I'll conduct a hypothesis-driven root cause analysis.

Then wait for the user's issue description.

Steps to follow after receiving the issue description:

Step 1: Extract and classify input

• Determine input type: Structured (stacktrace/logs), Vague (behavioral description), or Mixed
• For structured input: extract error messages, file paths, line numbers, timestamps, request IDs, affected services
• For vague input: identify keywords, affected features, conditions under which the issue occurs, frequency patterns
• For intermittent/vague issues: specifically look for race conditions, state variance, non-deterministic code paths

Step 2: Map to code

• For structured input: resolve stacktrace frames to actual source files, check if referenced lines still match (code may have changed since the error)
• For vague input: identify code paths for the affected functionality
• Read the relevant source files FULLY (no limit/offset) to understand context
• Note any error handling, state management, or concurrency patterns

Step 3: Check recent changes

• Run git log --oneline -20 -- <affected-files> on each affected file
• Look for recent modifications that correlate with when the issue started
• Check if any recent refactoring touched the affected code paths
• Use git diff on suspicious commits if needed

Step 4: Form hypotheses (2-3 theories)

• Based on the evidence gathered, formulate 2-3 plausible root causes
• Each hypothesis should be testable through code inspection
• Rank hypotheses by likelihood based on available evidence
• For vague/intermittent issues: always consider timing, ordering, and state as hypothesis categories

Step 5: Investigate in parallel

• Spawn sub-agent tasks to investigate each hypothesis concurrently
• Use the {codebase analyser agent} to trace specific code paths
• Use the {codebase pattern finder agent} to find similar patterns that might reveal the issue
• Use the {codebase locator agent} to find related components
• Each agent should look for evidence FOR and AGAINST its assigned hypothesis
• Collect specific file paths and line numbers as evidence

Step 6: Synthesise into RCA document and populate frontmatter

• Wait for ALL sub-agents to complete
• Evaluate each hypothesis: Confirmed, Eliminated, or Inconclusive
• Identify the root cause with specific code references
• Construct the causal chain from trigger to failure
• Propose fix options with risk/effort assessment
• Gather metadata using ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-derive-metadata.sh to obtain Current Date/Time (UTC):, Current Revision:, and Repository Name:. Run the bare path directly as an executable; never prefix it with bash/sh/env (a wrapper prefix escapes the skill's allowed-tools permission and forces an unnecessary prompt).
• Write the RCA document to the configured research directory using this template:

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-template.sh rca

Before writing the artifact file, substitute every field below with the indicated value:

• type: ← issue-research
• id: ← the filename stem, always quoted as a YAML string
• title: ← Investigation: {Brief Issue Description}
• date: ← the Current Date/Time (UTC): value
• author: ← the author resolved per the standard chain (config → VCS user → prompt)
• producer: ← research-issue
• status: ← complete
• revision: ← the Current Revision: value
• repository: ← the Repository Name: value
• last_updated: ← the same Current Date/Time (UTC): value
• last_updated_by: ← the same value resolved for author
• schema_version: ← 1 (bare integer)

Optional linkage/foreign-ref keys are omit-by-default: the template shows each as ""/[], but write a key into the artifact only when it has a value, and omit it entirely otherwise (do not carry the empty placeholder through).

• parent: ← the work item this investigation supports, as a typed-linkage ref ("work-item:NNNN"). Fill when the RCA has an owning work item; otherwise omit the key.

• relates_to: ← list of typed-linkage refs to related research (["issue-research:NNNN", ...]). Fill when related artifacts are explicit; otherwise omit the key.

• work_item_id: ← the linked work item's full ID (quoted). Fill when the RCA is linked to a work item; otherwise omit the key.

• Filename format: YYYY-MM-DD-description.md where description is a brief kebab-case summary of the issue (e.g., 2025-01-08-auth-timeout-on-refresh.md)

Step 7: Present findings (ONLY after the file has been written)

• Confirm the file path where the RCA document was saved
• Summarise the root cause concisely
• Highlight the recommended fix with rationale
• Include key file references for easy navigation
• Ask if they want deeper investigation on any aspect

Important notes:

• MANDATORY FILE OUTPUT: You MUST write the RCA document to a file in the configured research directory. NEVER present findings only as conversation output. The file write in step 6 is NOT optional — it is the primary deliverable of this skill. If you reach step 7 without having written a file, STOP and go back to step 6.
• Always use parallel Task agents to maximise efficiency
• Hypothesis-driven: generate theories THEN test them — don't just explore breadth-first
• For vague/intermittent issues: look for race conditions, state variance, non-deterministic paths, timing dependencies
• Evidence-based: every conclusion must reference specific code
• The RCA document should be self-contained and actionable
• Include the causal chain — not just "what" but "why" and "how"
• File reading: Always read affected files FULLY (no limit/offset)
• Critical ordering: Follow the numbered steps exactly
  • ALWAYS classify input before investigating (step 1)
  • ALWAYS check git history on affected files (step 3)
  • ALWAYS form hypotheses before spawning agents (step 4)
  • ALWAYS wait for all sub-agents before synthesising (step 6)
  • ALWAYS write the RCA document to a file before presenting findings (step 6 before step 7)
  • NEVER write the RCA document with placeholder values
  • NEVER skip the file write — the document IS the output of this skill

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-instructions.sh research-issue