triage-issue

Overview of triage-issue skill

The triage-issue skill is a focused workflow for investigating a reported bug, tracing it through a codebase, finding the likely root cause, and producing a GitHub issue that includes a test-driven fix plan. It is best for developers, maintainers, and AI-assisted issue triagers who want more than a vague bug summary and need a reusable path from report to actionable engineering work.

What triage-issue is designed to do

Unlike a generic “analyze this bug” prompt, triage-issue pushes toward a specific outcome:

1. capture the problem with minimal back-and-forth,
2. explore the codebase deeply,
3. identify the smallest credible fix approach,
4. turn the investigation into a GitHub-ready issue with testing guidance.

That makes the triage-issue skill especially useful when the real bottleneck is not writing the issue text, but doing enough technical investigation that the issue is worth assigning.

Best-fit users and repositories

Use triage-issue for Issue Tracking when you already have repository access and can inspect source code, tests, and recent changes. It fits best when:

• a user reports a bug but the cause is unclear,
• you want a maintainable issue instead of a speculative ticket,
• your team values TDD or at least explicit test coverage,
• you need to reduce maintainer time spent reproducing and scoping.

It is less useful for feature requests, product ambiguity, or bugs that depend on unavailable production-only data.

What makes triage-issue different

The main differentiator is the workflow discipline:

• ask at most one initial clarifying question,
• investigate first instead of interrogating the reporter,
• look for code paths, dependencies, tests, and similar working patterns,
• prefer root cause over symptom description,
• end with a minimal fix plan, not just observations.

That is a stronger default than ordinary prompting, where agents often ask too many questions or stop at superficial guesses.

What users usually care about before install

Most readers evaluating triage-issue install want to know three things quickly:

• Will it save time versus a custom prompt?
• Does it require a large support framework?
• Will it produce an issue that engineers can actually work from?

For this skill, the answer is usually yes if your environment lets the agent read the repo and run basic code exploration. The repository is lightweight and centered around a single SKILL.md, so adoption is simple, but output quality depends heavily on the quality of the bug report and codebase access.

How to Use triage-issue skill

How to install triage-issue

A typical install command is:

npx skills add mattpocock/skills --skill triage-issue

After install, open triage-issue/SKILL.md first. This skill has a small footprint, so nearly all of the important behavior is in that file rather than spread across extra rules or helper assets.

What to read first in the repository

For a fast triage-issue guide, read in this order:

1. SKILL.md — the actual workflow and guardrails
2. the skill description/frontmatter — quick fit check

Because this skill ships as a single-document workflow, there are no supporting scripts or reference docs to decode first. That is good for fast adoption, but it also means you need to supply the missing context yourself in the prompt.

What input triage-issue needs to work well

The skill can start from a very short bug report, but results improve a lot if you provide:

• a clear symptom,
• where it happens,
• expected vs actual behavior,
• any reproduction hints,
• relevant files, components, or routes if known,
• whether you want a GitHub issue draft at the end.

Useful input example:

“Please use triage-issue on this bug: saving profile settings appears successful, but after refresh the old values return. This happens in apps/web on the account settings page. I suspect the API mutation succeeds but cached data is stale. Please investigate the root cause and draft a GitHub issue with a TDD fix plan.”

That is much better than:

“Something is broken in settings. Can you triage it?”

How triage-issue handles the first interaction

A key part of triage-issue usage is that it minimizes questioning. If the report is missing, the intended first question is essentially: “What’s the problem you’re seeing?” After that, investigation should start immediately.

This matters if your current workflow gets stuck in clarification loops. The skill is designed to trade some uncertainty for momentum.

The core investigation workflow

In practice, triage-issue works best as a four-part sequence:

1. capture the reported problem,
2. explore affected code paths and entry points,
3. inspect related tests and missing coverage,
4. produce an issue with root cause, scope, and fix plan.

During exploration, the agent should look for:

• where the bug manifests,
• what flow leads there,
• why the failure happens,
• what nearby code already solves a similar problem.

That last point is especially useful in mature repositories where a working pattern already exists elsewhere.

What triage-issue should inspect in the codebase

To get meaningful output, direct the agent toward these sources of evidence:

• source files involved in the failing path,
• dependencies imported along that path,
• existing tests around the behavior,
• adjacent modules with similar logic,
• recent file history via git log for suspicious changes,
• error handling and state transitions.

If your repo is large, narrow the search space in the prompt. Otherwise the agent may spend too much time exploring broad areas before it reaches the likely fault line.

How to turn a rough request into a strong prompt

A strong triage-issue skill prompt usually includes five pieces:

• the observed problem,
• repository or package scope,
• constraints on investigation,
• desired deliverable,
• confidence expectations.

Example:

“Use triage-issue for this regression in packages/auth only. Users can log in, but session renewal fails after 15 minutes. Please inspect the existing renewal flow, recent changes, and related tests. I want a GitHub issue draft with root cause, minimal fix approach, and tests to add. Avoid broad refactors unless clearly necessary.”

This framing helps the skill stay scoped and deliver an issue that is actually assignable.

What good output looks like

A strong output from triage-issue should contain:

• a concise problem statement,
• evidence-backed root cause,
• impacted modules or interfaces,
• minimal proposed fix,
• test cases to add or update,
• any uncertainty or assumptions.

If the result only restates the symptom without identifying code paths or test impact, the skill was not given enough context or the investigation stopped too early.

When to use triage-issue instead of a normal prompt

Choose triage-issue when you need investigation discipline more than creativity. It is better than a generic prompt when:

• the bug report is vague,
• the codebase is non-trivial,
• you want a written issue, not just a chat answer,
• you need test planning as part of triage.

Use a normal prompt when you only want quick brainstorming, user-facing messaging, or a lightweight hypothesis list.

Practical workflow tips that improve output quality

Three habits materially improve triage-issue install value after adoption:

• Name the likely area of the repo, even if uncertain.
• Ask for a GitHub issue draft explicitly.
• Tell the agent whether to prefer minimal patching or broader cleanup.

Those constraints change the shape of the investigation and usually produce a more actionable issue.

triage-issue skill FAQ

Is triage-issue good for beginners?

Yes, if the beginner can let the agent inspect a repository and verify findings. The skill gives useful structure for bug investigation, but it does not replace basic judgment. A beginner may still need help validating whether the proposed root cause is the real one.

Does triage-issue require a reproducible bug?

No, but reproducibility improves confidence. triage-issue can still work from symptoms, code reading, and recent changes, especially if the failure path is easy to trace. Without reproduction clues, the final issue should include uncertainty clearly rather than pretending certainty.

What does triage-issue produce at the end?

The intended end state is a GitHub issue draft with a root-cause-oriented explanation and a TDD-style fix plan. That is the main reason to use triage-issue for Issue Tracking rather than a generic debugging prompt.

Is triage-issue only for bugs?

Mostly yes. It is optimized for reported problems, regressions, and failures in existing behavior. It is not the best fit for feature ideation, roadmap tickets, or design discussions.

How is triage-issue different from asking an agent to “debug this”?

The difference is output discipline. A normal debug prompt may stop after offering guesses. triage-issue usage is oriented around producing a maintainable issue with investigation notes, affected code areas, and tests to add. That makes it more useful for handoff and backlog quality.

When should I not use triage-issue?

Skip it when:

• the issue is purely product or UX prioritization,
• the repository cannot be inspected,
• the problem depends entirely on missing production telemetry,
• you already know the exact fix and just need implementation.

In those cases, triage-issue may add overhead without improving decisions.

How to Improve triage-issue skill

Give triage-issue better starting evidence

The fastest way to improve triage-issue results is to provide better initial evidence, not more generic instruction. High-value inputs include:

• exact error messages,
• route names or UI locations,
• suspected package or module,
• recent PRs or commits,
• a known working version,
• screenshots or reproduction notes summarized in text.

This shortens exploration time and increases the odds of a credible root-cause analysis.

Reduce false confidence in root-cause claims

A common failure mode is overcommitting to the first plausible explanation. Ask the agent to separate:

• confirmed findings,
• strong hypotheses,
• open questions.

For example: “If root cause is uncertain, list the top two explanations and what evidence would distinguish them.” That keeps the GitHub issue honest and more useful to engineers.

Ask for test impact, not just a code fix

The skill is strongest when it produces a fix plan tied to verification. If you want better output, explicitly request:

• which existing tests should change,
• what missing test should be added,
• what behavior the new test proves.

This turns triage into implementation-ready planning instead of issue prose.

Scope the repository to avoid shallow wandering

On large monorepos, triage-issue can waste time exploring too broadly. Improve it by constraining search scope:

• specific app or package,
• likely entry point,
• suspected API or UI flow,
• relevant ownership area.

Even a rough scope like “start in apps/admin and trace the billing update flow” can materially improve depth.

Ask for the minimal fix path first

Another common failure mode is proposing an oversized refactor. If your goal is issue quality and faster shipping, prompt for the smallest root-cause fix before broader cleanup ideas.

A useful instruction is:

“Prioritize the minimal change that resolves the bug. Mention larger cleanup only if it is required for correctness.”

This keeps the triage-issue skill aligned with real triage rather than architecture critique.

Improve the final issue format for your team

If you plan to use the output directly, ask triage-issue to format the issue with fields your team already expects, such as:

• summary,
• reproduction,
• actual behavior,
• expected behavior,
• root cause,
• proposed fix,
• tests,
• risks,
• acceptance criteria.

That small customization makes adoption easier because the skill output drops into existing issue tracking workflows.

Iterate after the first pass

The first triage-issue guide output should be treated as a working draft. Good follow-up prompts are targeted, such as:

• “Tighten the root cause section with file-level evidence.”
• “List exactly which tests are missing.”
• “Rewrite the issue for a maintainer who has not seen the report.”
• “Reduce the fix scope to the minimum safe change.”

Those iterations improve trust and handoff quality far more than re-running the entire skill with the same vague input.