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(accelerator config *)
  - Bash(accelerator corpus metadata derive)
  - Bash(accelerator corpus frontmatter validate *)
---

# Research Issue

!`accelerator config context --skill research-issue --fail-safe`
!`accelerator config agents --fail-safe`

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**: !`accelerator config path research_issues --fail-safe`

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

- Review each affected file's recent history (its last ~20 revisions) using the
  session's VCS log command
- Look for recent modifications that correlate with when the issue started
- Check if any recent refactoring touched the affected code paths
- Inspect suspicious commits using the session's VCS diff command 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
  `accelerator corpus metadata derive` to obtain
  `Current Date/Time (UTC):`, `Current Revision:`, and `Repository Name:`.
- Write the RCA document to the configured research directory using this
  template:

!`accelerator config template rca --fail-safe`

  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`)

**Validate the frontmatter**: after writing, run `corpus frontmatter
validate` over the RCA document you just wrote:

```bash
accelerator corpus frontmatter validate --file <path>
```

If it exits non-zero, the RCA document violates the canonical frontmatter
standard; report the emitted violation and fix the frontmatter before
completing.

### 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 VCS 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

!`accelerator config instructions research-issue --fail-safe`