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

> Learn how the triage-issue skill systematically investigates and documents bugs. Transform vague GitHub issues into actionable reports with this complete guide.

- Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills)
- Tags: how-to-guide
- Published: 2026-04-04

---

**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`](https://github.com/mattpocock/skills/blob/main/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:

```markdown

## 🔍 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`](https://github.com/mattpocock/skills/blob/main/triage-issue/SKILL.md)** — Contains the full declarative checklist and explanatory notes for each investigation phase.

- **[`github-triage/SKILL.md`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/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`](https://github.com/mattpocock/skills/blob/main/triage-issue/SKILL.md). This file contains the full checklist, formatting templates, and explanatory notes that guide developers through the bug investigation process.