# Investigate Issues

> Investigates identified issues in a LearningAgent session by reading the transcript, determining root causes, and updating issue files with investigation reports.

- Skill: `majiayu000/investigate-issues` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/investigate-issues`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/investigate-issues/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/investigate-issues

---


# Investigate Issues

Research identified issues from a LearningAgent session to determine their root causes.

## Arguments

`$ARGUMENTS` is the path to the session log folder (e.g., `.deepwork/tmp/agent_sessions/<session_id>/<agent_id>/`).

## Context

**Session log folder structure**:
!`cat learning_agents/doc/learning_log_folder_structure.md 2>/dev/null`

**Agent used**: !`cat $ARGUMENTS/agent_used 2>/dev/null || echo "unknown"`

**Identified issues to investigate**:
!`grep -l 'status: identified' $ARGUMENTS/*.issue.yml 2>/dev/null || echo "(none)"`

**Additional investigation guidelines**:
!`learning_agents/scripts/cat_agent_guideline.sh $ARGUMENTS issue_investigation`

## Current Agent State
-------- CURRENT KNOWLEDGE OF AGENT --------
!`learning_agents/scripts/generate_agent_instructions_for_session.sh $ARGUMENTS`
------ END CURRENT KNOWLEDGE OF AGENT-------

## Procedure

If no identified issues are listed above, report that and stop.

Refer back to the `conversation_transcript.jsonl` file as needed in this process.

### Step 1: Investigate Each Issue

For each issue file with status `identified`:

1. **Read the issue file** to understand what went wrong
2. **Search the transcript** for relevant sections — grep for keywords from `issue_description` or locate lines near `seen_at_timestamps`
3. **Determine root cause** using this taxonomy:
   - **Knowledge gap**: Missing or incomplete content in `core-knowledge.md`
   - **Missing documentation**: A topic file does not exist or lacks needed detail
   - **Incorrect instruction**: An existing instruction leads the agent to wrong behavior
   - **Missing runtime context**: Information that should have been injected at runtime was absent

### Step 2: Update Issue Files

For each investigated issue, use Edit to update the issue file:

1. Change `status: identified` to `status: investigated`
2. Add the `investigation_report` field:

```yaml
status: investigated
investigation_report: |
  <Root cause analysis with specific transcript line numbers as evidence.
  Explain what knowledge gap or instruction deficiency caused the issue.>
```

### Step 3: Summary

Simply say "Session log folder <session log folder> done."

## Guardrails

- Do NOT modify the agent's knowledge base — that is the incorporate step's job
- Do NOT change the `issue_description` — only add the `investigation_report`
- Do NOT skip issues — investigate every `identified` issue
- Be specific about evidence — reference transcript line numbers