skills.rest
mastra-ai
mastra-aiOFFICIAL
Explore all skills by this author →
Website𝕏@mastraGitHub

understand-issue

Investigate GitHub issues by tracing code history and architecture to diagnose root causes.

27.6k|2.7k|Updated Aug 6, 2024
Search Tags:#issue triage#code investigation#gh CLI#Debugging#Root Cause Analysis#gitHub#git blame
One-click install
npx skills add https://github.com/mastra-ai/mastra --skill understand-issue
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: understand-issue
Source: https://github.com/mastra-ai/mastra/tree/main/.mastracode/skills/understand-issue
Command: npx skills add https://github.com/mastra-ai/mastra --skill understand-issue

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debugging a reported GitHub issue often means guessing at causes without understanding the code's history or architecture. This Skill guides a structured, collaborative investigation that traces git history, maps contributing code areas, and validates a diagnosis with the user before writing anything up.

Core Features & Use Cases

  • Issue Triage and Context Gathering: Pulls issue metadata, comments, and author history via the GitHub CLI, and searches for related issues, PRs, and potential regressions.
  • History-Aware Code Tracing: Uses git log, git blame, and linked PRs to explain why each contributing code area exists, how it fits architecturally, and how areas interact.
  • Collaborative Diagnosis: Presents evidence-backed hypotheses with lettered options, distinguishes genuine bugs from config errors, docs gaps, and XY problems, and writes a structured UNDERSTANDING.md report with an optional GitHub comment.
  • Use Case: A maintainer receives a vague bug report about workflow suspension. Run this Skill to trace the relevant storage and workflow code, discover a recent commit changed a shared config assumption, confirm the root cause with the reporter, and post a concise analysis comment to the issue.

Quick Start

Ask the agent to investigate GitHub issue number 1234 and diagnose its root cause using the understand-issue workflow.

Frequently Asked Questions about understand-issue

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I investigate a GitHub issue before attempting a fix?▼

Start by pulling the issue metadata and comments with gh issue view, then search for related issues and PRs. Trace the implicated code with git log and git blame to understand why it exists before forming a diagnosis.

How to find the root cause of a bug using git history?▼

Use git log on the relevant files to see recent changes, git blame on specific lines to find who changed them and why, and read linked PRs for original motivation. Regressions often come from commits that broke assumptions in shared code.

Can this Skill post comments to GitHub issues?▼

Yes, but only with explicit user approval. It drafts a concise root-cause analysis comment, presents it for review, then posts via gh issue comment, with a REST API fallback if rate limits are low.

What if the reported issue is not actually a bug?▼

The diagnosis phase explicitly evaluates whether the issue is an XY problem, configuration error, documentation gap, or intended behavior. It states that assessment with evidence before proposing any code change.

Why does gh output break jq when investigating issues?▼

The gh CLI emits ANSI color codes that corrupt jq parsing. Use gh's built-in --jq flag for filtering, or prefix commands with NO_COLOR=1 to disable color output.

Related Skills

Explore More Software Engineering Skills→
pcortespcortes

bug-researcher

Reproduce bugs and collect stack traces, logs, and affected files.

Community
Advanced
allexcdallexcd

autonomous-bug-fixing

Diagnose, reproduce, and fix code defects from bug reports or error logs.

Community
Advanced
Euraika-LabsEuraika-Labs
14

regression-suite

Map test coverage to GDD critical paths and audit regression tests for bug fixes.

Official
Advanced
CaptainPhantasyCaptainPhantasy

debug-breakpoint-inject

Inject log-based breakpoints to trace runtime variables during execution.

Community
Advanced