How the Triage-Issue Skill Investigates and Documents Bugs: A Complete Guide

The triage-issue skill is a declarative Markdown-based checklist that transforms vague GitHub issues into actionable bug reports by systematically collecting context, reproducing failures, capturing diagnostics, and standardizing documentation.

The triage-issue skill in the mattpocock/skills repository provides a systematic framework for investigating and documenting bugs. This reusable guide helps maintainers convert chaotic issue reports into structured, reproducible bug tickets that accelerate resolution times and reduce back-and-forth clarification.

How the Triage-Issue Skill Works

The skill operates through five distinct phases defined in triage-issue/SKILL.md. Unlike automated bots, this skill is declarative—it presents a transparent checklist that humans follow rather than executing code directly, which prevents accidental secret leaks while maintaining process consistency.

1. Collect Context

The investigation begins by gathering the "who, where, and what" of the bug report:

• Reads the issue title and description
• Pulls attached screenshots, logs, or stack traces
• Checks environment tags (OS, browser, version, etc.)

This phase reduces the time spent requesting basic information from reporters by capturing everything upfront.

2. Reproduce the Bug

Before any code changes occur, the skill mandates that bugs must be observable:

• Attempts to run reported steps in a local environment
• Prompts the reporter for clarification if steps are ambiguous
• Records exact commands or UI actions that trigger the failure

Guaranteeing reproducibility is a prerequisite for any fix, preventing developers from chasing phantom bugs or environment-specific quirks.

3. Capture Diagnostics

Concrete debugging artifacts are collected to accelerate resolution:

• Collects error logs, console output, and exception traces
• Generates minimal reproducible examples when possible
• Tags appropriate test suite failures for CI tracking

These diagnostics provide developers with specific entry points for debugging and help automated systems detect future regressions.

4. Update the Issue

Raw issues are transformed into standardized documentation:

• Adds a "Reproduction Steps" section with a numbered list
• Inserts a "Diagnostic Info" block containing logs or screenshots
• Applies standardized labels such as bug, needs-triage, and high-priority
• Links related issues or pull requests for traceability

This structured format turns vague reports into high-quality tickets that can be prioritized and assigned immediately without additional triage overhead.

5. Hand-off to Developers

The final phase ensures seamless transition to fix implementation:

• Notifies team channels (e.g., Slack, Discord) with investigation summaries
• Optionally creates draft pull requests linked to the issue
• Assigns the issue to appropriate maintainers based on component labels

This notification step ensures the right stakeholders are aware and can begin work without delay.

Practical Implementation Example

Below is the exact markdown structure the triage-issue skill prescribes, demonstrating how a developer would document a crash report:

## 🔍 Triage (triage-issue skill)

### 1️⃣ Collect Context

- **Reporter:** @alice  
- **Environment:** macOS 13.2, Electron 22.0.0  
- **Attachments:** `crash-log.txt`, screenshot of error dialog

### 2️⃣ Reproduce the Bug

1. Clone the repo and checkout `main`.
2. Run `npm ci && npm start`.
3. Click *Settings* in the top-right menu.
4. Observe the crash after ~2 seconds.

*Result:* Application terminates with `SIGABRT`.

### 3️⃣ Capture Diagnostics

[2024-10-12 14:32:07] *** Assertion failed: ... Stack trace: at SettingsPage.render (src/ui/settings.tsx:45) …

### 4️⃣ Update the Issue

- **Added Sections:**  
  - **Steps to Reproduce** (numbered list)  
  - **Diagnostic Info** (code block with log)  
- **Labels:** `bug`, `macos`, `high-priority`  
- **Linked PR:** (none yet)  

### 5️⃣ Hand-off

- Posted summary to `#bug-triage` Slack channel.  
- Assigned to @bob for investigation.

Teams can copy this template directly into issue comments or edit the original issue body to reflect the structured format, creating a single source of truth for the bug investigation.

Key Source Files and References

Understanding the triage-issue skill requires referencing specific files in the mattpocock/skills repository:

• triage-issue/SKILL.md — Contains the full declarative checklist and explanatory notes for each investigation phase.

• github-triage/SKILL.md — Provides higher-level guidance on automating GitHub triage workflows, including how to use bots to apply the triage-issue skill at scale.

• README.md — Documents the general conventions used across all skills in the repository, including markdown formatting standards and secret-leak prevention rules.

These files together define the process automation hooks and repository conventions that make the triage-issue skill effective for open-source maintenance.

Summary

• The triage-issue skill transforms chaotic bug reports into actionable tickets through a five-phase declarative process defined in triage-issue/SKILL.md.
• Reproducibility is mandatory—the skill requires local verification before any code changes are attempted.
• Standardized formatting includes specific sections for reproduction steps and diagnostic info, plus consistent labeling with tags like bug and high-priority.
• Declarative design keeps the process transparent and safe from automated secret leaks while remaining compatible with bot automation via github-triage/SKILL.md.
• Structured hand-offs ensure developers receive complete context through team notifications and linked artifacts, eliminating triage bottlenecks.

Frequently Asked Questions

What is the triage-issue skill?

The triage-issue skill is a reusable Markdown-based guide stored in triage-issue/SKILL.md that provides a systematic checklist for investigating GitHub issues. It is designed to be read and executed by humans or automation tools to standardize how bugs are documented across a project.

How does the triage-issue skill ensure reproducibility?

The skill mandates that investigators must attempt to reproduce the bug locally using the reported steps before documenting it. If steps are ambiguous, the investigator must request clarification from the reporter. This ensures that every documented bug has confirmed, observable behavior rather than unverified claims.

Can the triage-issue skill be automated?

While the skill itself is declarative and human-readable, it can be integrated with automation workflows. The github-triage/SKILL.md file describes how bots can apply the triage-issue skill template to incoming issues. However, the core skill remains non-executable by design to prevent accidental execution of malicious code or secret leakage.

Where is the triage-issue skill defined?

The complete skill definition lives in the mattpocock/skills repository at the path triage-issue/SKILL.md. This file contains the full checklist, formatting templates, and explanatory notes that guide developers through the bug investigation process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}