# Understand Issue

Investigate a GitHub issue or reported bug the way a seasoned maintainer would, form...

- Repository: https://github.com/mastra-ai/mastra (29259 stars)
- Category: Git and review
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mastra-ai/mastra --skill understand-issue -g -a claude-code -y`
Codex: `npx skills add mastra-ai/mastra --skill understand-issue -g -a codex -y`
Cursor: `npx skills add mastra-ai/mastra --skill understand-issue -g -a cursor -y`
Gemini CLI: `npx skills add mastra-ai/mastra --skill understand-issue -g -a gemini-cli -y`

## Description

Investigate a GitHub issue or reported bug the way a seasoned maintainer would, form an independent model before reading the thread's theories, trace the mechanism and history, verify the diagnosis, and return a concise briefing with a verdict and fix direction. Use for triage, root-cause analysis, or re-investigation.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Understand Issue

Investigate the issue as a maintainer deciding what is actually wrong and what should happen next. Help the human understand it without turning the investigation into a walkthrough. Run uninterrupted to a concise front page, then stay available inside the goal until the human says the investigation is finished.

The issue follows `ARGUMENTS:` at the end of the objective. If absent, infer it from the conversation or the checked-out branch name (`fix/1234`, `issue-567`, `gh-890`). If no issue can be resolved and no bug is described, ask once.

## What matters

1. **Independent model before the thread's theories.** Understand the symptom and form your own hypothesis from the code before reading commenters' diagnoses, workarounds, or linked fix attempts. The gap between your model and theirs exposes anchoring in both directions.
2. **Depth proportional to stakes.** Data loss, security, silent misbehavior, wide blast radius, and uncertainty determine how hard to look, not a fixed checklist.
3. **Verify the diagnosis.** Read code deeply and run the smallest useful probe. A diagnosis needs real evidence and pointers; a plausible story is not evidence.
4. **A verdict, not a survey.** Say what the issue is and what causes it. Do not present a menu of candidates when the evidence supports one.
5. **Complete, not padded.** Everything you established or still suspect is in the briefing; length follows from findings, never the other way around. Lead with what matters most and cut narration, not conclusions. Preserve supporting detail in one record file for follow-up questions.

## Investigation record

Use one ignored file: `.mastracode/scratch/issues/<owner>-<repo>-<n>.md`. Never stage or commit it.

Start the record with a short **Own model**:

- the symptom as reported, in your words;
- how the relevant code currently works;
- your hypothesis for the cause;
- what evidence would confirm or kill it.

The rest: https://github.com/mastra-ai/mastra/blob/HEAD/.mastracode/skills/understand-issue/SKILL.md