mirror of
https://github.com/mattpocock/skills.git
synced 2026-04-30 14:03:53 +07:00
Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Matt Pocock
|
b7bf8cc3c1 | ||
|
Matt Pocock
|
d0592f4cfb |
@@ -2,9 +2,10 @@
|
||||
"name": "mattpocock-skills",
|
||||
"skills": [
|
||||
"./skills/engineering/diagnose",
|
||||
"./skills/engineering/github",
|
||||
"./skills/engineering/grill-with-docs",
|
||||
"./skills/engineering/github-triage",
|
||||
"./skills/engineering/improve-codebase-architecture",
|
||||
"./skills/engineering/triage",
|
||||
"./skills/engineering/tdd",
|
||||
"./skills/engineering/to-issues",
|
||||
"./skills/engineering/to-prd",
|
||||
|
||||
@@ -130,12 +130,13 @@ Software engineering fundamentals matter more than ever. These skills are my bes
|
||||
Skills I use daily for code work.
|
||||
|
||||
- **[diagnose](./skills/engineering/diagnose/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
|
||||
- **[github](./skills/engineering/github/SKILL.md)** — GitHub backend for the engineering skills. Publishes PRDs and issues, applies triage outcomes via `gh`.
|
||||
- **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline.
|
||||
- **[github-triage](./skills/engineering/github-triage/SKILL.md)** — Triage GitHub issues through a label-based state machine.
|
||||
- **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`.
|
||||
- **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
|
||||
- **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable GitHub issues using vertical slices.
|
||||
- **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation context into a PRD and submit it as a GitHub issue. No interview — just synthesizes what you've already discussed.
|
||||
- **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. Hands off to a backend skill (`/github`) to publish.
|
||||
- **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation context into a PRD. Hands off to a backend skill (`/github`) to publish. No interview — just synthesizes what you've already discussed.
|
||||
- **[triage](./skills/engineering/triage/SKILL.md)** — Triage issues through a label-based state machine. Backend-agnostic — pairs with `/github` to apply outcomes.
|
||||
- **[zoom-out](./skills/engineering/zoom-out/SKILL.md)** — Tell the agent to zoom out and give broader context or a higher-level perspective on an unfamiliar section of code.
|
||||
|
||||
### Productivity
|
||||
|
||||
@@ -6,6 +6,21 @@ set -euo pipefail
|
||||
|
||||
REPO="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
DEST="$HOME/.claude/skills"
|
||||
|
||||
# If ~/.claude/skills is a symlink that resolves into this repo, we'd end up
|
||||
# writing the per-skill symlinks back into the repo's own skills/ tree. Detect
|
||||
# and bail out instead of polluting the working copy.
|
||||
if [ -L "$DEST" ]; then
|
||||
resolved="$(readlink -f "$DEST")"
|
||||
case "$resolved" in
|
||||
"$REPO"|"$REPO"/*)
|
||||
echo "error: $DEST is a symlink into this repo ($resolved)." >&2
|
||||
echo "Remove it (rm \"$DEST\") and re-run; the script will recreate it as a real dir." >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
mkdir -p "$DEST"
|
||||
|
||||
find "$REPO/skills" -name SKILL.md -not -path '*/node_modules/*' -print0 |
|
||||
|
||||
@@ -5,5 +5,4 @@ Skills I no longer use.
|
||||
- **[design-an-interface](./design-an-interface/SKILL.md)** — Generate multiple radically different interface designs for a module using parallel sub-agents.
|
||||
- **[qa](./qa/SKILL.md)** — Interactive QA session where user reports bugs conversationally and the agent files GitHub issues.
|
||||
- **[request-refactor-plan](./request-refactor-plan/SKILL.md)** — Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue.
|
||||
- **[triage-issue](./triage-issue/SKILL.md)** — Investigate a bug by exploring the codebase, identify the root cause, and file a GitHub issue with a TDD-based fix plan.
|
||||
- **[ubiquitous-language](./ubiquitous-language/SKILL.md)** — Extract a DDD-style ubiquitous language glossary from the current conversation.
|
||||
|
||||
@@ -1,102 +0,0 @@
|
||||
---
|
||||
name: triage-issue
|
||||
description: Triage a bug or issue by exploring the codebase to find root cause, then create a GitHub issue with a TDD-based fix plan. Use when user reports a bug, wants to file an issue, mentions "triage", or wants to investigate and plan a fix for a problem.
|
||||
---
|
||||
|
||||
# Triage Issue
|
||||
|
||||
Investigate a reported problem, find its root cause, and create a GitHub issue with a TDD fix plan. This is a mostly hands-off workflow - minimize questions to the user.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Capture the problem
|
||||
|
||||
Get a brief description of the issue from the user. If they haven't provided one, ask ONE question: "What's the problem you're seeing?"
|
||||
|
||||
Do NOT ask follow-up questions yet. Start investigating immediately.
|
||||
|
||||
### 2. Explore and diagnose
|
||||
|
||||
Use the Agent tool with subagent_type=Explore to deeply investigate the codebase. Your goal is to find:
|
||||
|
||||
- **Where** the bug manifests (entry points, UI, API responses)
|
||||
- **What** code path is involved (trace the flow)
|
||||
- **Why** it fails (the root cause, not just the symptom)
|
||||
- **What** related code exists (similar patterns, tests, adjacent modules)
|
||||
|
||||
Look at:
|
||||
- Related source files and their dependencies
|
||||
- Existing tests (what's tested, what's missing)
|
||||
- Recent changes to affected files (`git log` on relevant files)
|
||||
- Error handling in the code path
|
||||
- Similar patterns elsewhere in the codebase that work correctly
|
||||
|
||||
### 3. Identify the fix approach
|
||||
|
||||
Based on your investigation, determine:
|
||||
|
||||
- The minimal change needed to fix the root cause
|
||||
- Which modules/interfaces are affected
|
||||
- What behaviors need to be verified via tests
|
||||
- Whether this is a regression, missing feature, or design flaw
|
||||
|
||||
### 4. Design TDD fix plan
|
||||
|
||||
Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:
|
||||
|
||||
- **RED**: Describe a specific test that captures the broken/missing behavior
|
||||
- **GREEN**: Describe the minimal code change to make that test pass
|
||||
|
||||
Rules:
|
||||
- Tests verify behavior through public interfaces, not implementation details
|
||||
- One test at a time, vertical slices (NOT all tests first, then all code)
|
||||
- Each test should survive internal refactors
|
||||
- Include a final refactor step if needed
|
||||
- **Durability**: Only suggest fixes that would survive radical codebase changes. Describe behaviors and contracts, not internal structure. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state. A good suggestion reads like a spec; a bad one reads like a diff.
|
||||
|
||||
### 5. Create the GitHub issue
|
||||
|
||||
Create a GitHub issue using `gh issue create` with the template below. Do NOT ask the user to review before creating - just create it and share the URL.
|
||||
|
||||
<issue-template>
|
||||
|
||||
## Problem
|
||||
|
||||
A clear description of the bug or issue, including:
|
||||
- What happens (actual behavior)
|
||||
- What should happen (expected behavior)
|
||||
- How to reproduce (if applicable)
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
Describe what you found during investigation:
|
||||
- The code path involved
|
||||
- Why the current code fails
|
||||
- Any contributing factors
|
||||
|
||||
Do NOT include specific file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts instead. The issue should remain useful even after major refactors.
|
||||
|
||||
## TDD Fix Plan
|
||||
|
||||
A numbered list of RED-GREEN cycles:
|
||||
|
||||
1. **RED**: Write a test that [describes expected behavior]
|
||||
**GREEN**: [Minimal change to make it pass]
|
||||
|
||||
2. **RED**: Write a test that [describes next behavior]
|
||||
**GREEN**: [Minimal change to make it pass]
|
||||
|
||||
...
|
||||
|
||||
**REFACTOR**: [Any cleanup needed after all tests pass]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
- [ ] All new tests pass
|
||||
- [ ] Existing tests still pass
|
||||
|
||||
</issue-template>
|
||||
|
||||
After creating the issue, print the issue URL and a one-line summary of the root cause.
|
||||
@@ -3,10 +3,11 @@
|
||||
Skills I use daily for code work.
|
||||
|
||||
- **[diagnose](./diagnose/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
|
||||
- **[github](./github/SKILL.md)** — GitHub backend for the engineering skills. Publishes PRDs and issues, applies triage outcomes via `gh`.
|
||||
- **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline.
|
||||
- **[github-triage](./github-triage/SKILL.md)** — Triage GitHub issues through a label-based state machine.
|
||||
- **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`.
|
||||
- **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time.
|
||||
- **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable GitHub issues using vertical slices.
|
||||
- **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation context into a PRD and submit it as a GitHub issue.
|
||||
- **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. Hands off to a backend skill (`/github`) to publish.
|
||||
- **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation context into a PRD. Hands off to a backend skill (`/github`) to publish.
|
||||
- **[triage](./triage/SKILL.md)** — Triage issues through a label-based state machine. Backend-agnostic — pairs with `/github` to apply outcomes.
|
||||
- **[zoom-out](./zoom-out/SKILL.md)** — Tell the agent to zoom out and give broader context or a higher-level perspective on an unfamiliar section of code.
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
name: github
|
||||
description: GitHub backend for the engineering skills. Publishes PRDs and issues, applies triage outcomes via gh. Use when a content skill (`/to-prd`, `/to-issues`, `/triage`) has produced an artifact and the user wants to push it to GitHub.
|
||||
---
|
||||
|
||||
# GitHub Backend
|
||||
|
||||
The GitHub backend for content skills in the engineering bucket. Reads an artifact + state from conversation context and translates it into `gh` calls.
|
||||
|
||||
This skill does **not** explore the codebase, generate templates, or own state vocabulary. Those concerns live in the content skills (`/to-prd`, `/to-issues`, `/triage`). This skill is pure integration — swap it for `/linear`, `/beads`, etc. by implementing the same three operations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `gh` is authenticated and the working directory is a git repo with a GitHub remote
|
||||
- The repo has labels matching the state vocabulary defined in `/triage` (`bug`, `enhancement`, `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). If any are missing, create them with `gh label create` before publishing.
|
||||
|
||||
## State → label mapping
|
||||
|
||||
The state vocabulary maps 1:1 to GitHub labels of the same name. Every issue gets exactly one category label (`bug` or `enhancement`) and one state label.
|
||||
|
||||
## AI Disclaimer
|
||||
|
||||
Every comment or issue body posted by this skill **must** start with:
|
||||
|
||||
```
|
||||
> *This was generated by AI during triage.*
|
||||
```
|
||||
|
||||
Prepend it to the body before calling `gh`.
|
||||
|
||||
## Operations
|
||||
|
||||
### `publishPRD(artifact)`
|
||||
|
||||
Input: a PRD body produced by `/to-prd` (already in the desired template) and a state (defaults to `ready-for-agent`).
|
||||
|
||||
Steps:
|
||||
|
||||
1. Verify the `enhancement` and state labels exist in the repo; create any missing ones with `gh label create`.
|
||||
2. Prepend the AI disclaimer to the body.
|
||||
3. Run `gh issue create --title "<derived from PRD>" --body "<body>" --label enhancement --label <state>`.
|
||||
4. Report the new issue URL to the user.
|
||||
|
||||
### `publishIssues(artifacts[])`
|
||||
|
||||
Input: an ordered list of vertical-slice artifacts produced by `/to-issues`. Each artifact has:
|
||||
|
||||
- title
|
||||
- body (already formatted — agent brief for AFK slices, summary for HITL)
|
||||
- type (`AFK` or `HITL`) → state mapping: AFK → `ready-for-agent`, HITL → `ready-for-human`
|
||||
- category (defaults to `enhancement` unless the parent issue was a bug)
|
||||
- blocked-by — references to other artifacts in this batch by their position
|
||||
|
||||
Steps:
|
||||
|
||||
1. Verify required labels exist; create any missing ones.
|
||||
2. Create issues in dependency order (blockers first) so each issue's "Blocked by" section can reference real numbers.
|
||||
3. For each artifact, after creation, substitute placeholder references in dependent artifacts with the real issue number.
|
||||
4. Prepend the AI disclaimer to each body before posting.
|
||||
5. Apply category + state labels to each.
|
||||
6. Report the list of created issue URLs.
|
||||
|
||||
Do **not** close or modify any parent issue.
|
||||
|
||||
### `applyTriageOutcome(issueId, outcome)`
|
||||
|
||||
Input: an issue identifier and a triage outcome from `/triage`. The outcome has:
|
||||
|
||||
- target state (one of the states above)
|
||||
- category (`bug` or `enhancement`)
|
||||
- comment body (may be empty for `needs-triage` with no progress to capture)
|
||||
- close (boolean — true for `wontfix`)
|
||||
|
||||
Steps:
|
||||
|
||||
1. Verify the target state and category labels exist; create missing ones.
|
||||
2. Read the issue's current labels. Remove any existing state label that conflicts with the target state. Remove existing category label if it differs from the target.
|
||||
3. Apply the new state and category labels: `gh issue edit <id> --add-label <state> --add-label <category> --remove-label <old-state>`.
|
||||
4. If a comment body is provided, prepend the AI disclaimer and post it: `gh issue comment <id> --body "<body>"`.
|
||||
5. If `close` is true: `gh issue close <id>`.
|
||||
6. For `wontfix` on an enhancement, ensure the corresponding `.out-of-scope/<concept>.md` file exists in the working directory before closing (the `/triage` skill is responsible for writing it; this skill just verifies the file is present and surfaces a warning if missing).
|
||||
7. Report the actions taken.
|
||||
|
||||
## Inferring the operation
|
||||
|
||||
When invoked, infer which operation to run from the most recent artifact in conversation context:
|
||||
|
||||
- A PRD artifact (from `/to-prd`) → `publishPRD`
|
||||
- A list of vertical-slice artifacts (from `/to-issues`) → `publishIssues`
|
||||
- A triage outcome with a target state (from `/triage`) → `applyTriageOutcome`
|
||||
|
||||
If multiple are present or the situation is ambiguous, ask the user which to run.
|
||||
@@ -1,27 +1,27 @@
|
||||
---
|
||||
name: to-issues
|
||||
description: Break a plan, spec, or PRD into independently-grabbable GitHub issues using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
|
||||
description: Break a plan, spec, or PRD into independently-grabbable issues using tracer-bullet vertical slices. Backend-agnostic — pairs with `/github` (or another backlog skill) to publish. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues.
|
||||
---
|
||||
|
||||
# To Issues
|
||||
|
||||
Break a plan into independently-grabbable GitHub issues using vertical slices (tracer bullets).
|
||||
Break a plan into independently-grabbable issues using vertical slices (tracer bullets). Produce canonical artifacts; hand off to a backend skill (`/github` by default) to publish.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Gather context
|
||||
|
||||
Work from whatever is already in the conversation context. If the user passes a GitHub issue number or URL as an argument, fetch it with `gh issue view <number>` (with comments).
|
||||
Work from whatever is already in the conversation context. If the user passes an issue identifier as an argument and a backend is reachable, ask the backend skill to fetch the parent issue (with comments).
|
||||
|
||||
### 2. Explore the codebase (optional)
|
||||
|
||||
If you have not already explored the codebase, do so to understand the current state of the code. Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md). Issue titles and descriptions should use the project's `CONTEXT.md` vocabulary.
|
||||
If you have not already explored the codebase, do so to understand the current state of the code. Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md). Issue titles and bodies should use the project's `CONTEXT.md` vocabulary.
|
||||
|
||||
### 3. Draft vertical slices
|
||||
|
||||
Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
|
||||
Break the plan into **tracer bullet** slices. Each is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
|
||||
|
||||
Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
|
||||
Slices may be **HITL** or **AFK**. HITL slices require human interaction (an architectural decision, a design review). AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
|
||||
|
||||
<vertical-slice-rules>
|
||||
- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
|
||||
@@ -47,21 +47,33 @@ Ask the user:
|
||||
|
||||
Iterate until the user approves the breakdown.
|
||||
|
||||
### 5. Create the GitHub issues
|
||||
### 5. Produce artifacts
|
||||
|
||||
For each approved slice, create a GitHub issue using `gh issue create`. Use the issue body template below.
|
||||
For each approved slice, produce an artifact with:
|
||||
|
||||
Create issues in dependency order (blockers first) so you can reference real issue numbers in the "Blocked by" field.
|
||||
- **title** — short descriptive name
|
||||
- **type** — `AFK` or `HITL`. Maps to state: AFK → `ready-for-agent`, HITL → `ready-for-human` (the state vocabulary lives in `/triage`)
|
||||
- **category** — `enhancement` by default, or `bug` if the parent was a bug
|
||||
- **blocked-by** — references to other slices in this batch (by their position in the list)
|
||||
- **body** — formatted per the templates below
|
||||
|
||||
<issue-template>
|
||||
**AFK slices** use the AGENT-BRIEF format from [../triage/AGENT-BRIEF.md](../triage/AGENT-BRIEF.md). The agent brief is the contract the AFK agent will work from.
|
||||
|
||||
**HITL slices** use the simpler template below — they require human judgment, so a procedural acceptance list is enough.
|
||||
|
||||
<hitl-template>
|
||||
## Parent
|
||||
|
||||
#<parent-issue-number> (if the source was a GitHub issue, otherwise omit this section)
|
||||
#<parent-issue-id> (if the source was an existing issue, otherwise omit)
|
||||
|
||||
## What to build
|
||||
|
||||
A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
|
||||
|
||||
## Why this needs a human
|
||||
|
||||
Brief reason this can't be delegated to an AFK agent (e.g. requires architectural decision, design review, judgment call).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Criterion 1
|
||||
@@ -70,10 +82,17 @@ A concise description of this vertical slice. Describe the end-to-end behavior,
|
||||
|
||||
## Blocked by
|
||||
|
||||
- Blocked by #<issue-number> (if any)
|
||||
- Blocked by <slice-ref> (if any)
|
||||
|
||||
Or "None - can start immediately" if no blockers.
|
||||
</hitl-template>
|
||||
|
||||
</issue-template>
|
||||
### 6. Hand off
|
||||
|
||||
Present the artifact list to the user and end with a handoff hint:
|
||||
|
||||
> Artifacts ready. Invoke `/github` (or your configured backend equivalent) to publish — it will create issues in dependency order, apply state and category labels, and substitute real identifiers into the "Blocked by" references.
|
||||
|
||||
Do not call `gh` directly. The backend skill owns publishing.
|
||||
|
||||
Do NOT close or modify any parent issue.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: to-prd
|
||||
description: Turn the current conversation context into a PRD and submit it as a GitHub issue. Use when user wants to create a PRD from the current context.
|
||||
description: Turn the current conversation context into a PRD. Backend-agnostic — pairs with `/github` (or another backlog skill) to publish. Use when user wants to create a PRD from the current context.
|
||||
---
|
||||
|
||||
This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
|
||||
This skill takes the current conversation context and codebase understanding and produces a PRD artifact. Do NOT interview the user — just synthesize what you already know. Hand off to a backend skill (`/github` by default) to publish.
|
||||
|
||||
## Process
|
||||
|
||||
@@ -15,7 +15,11 @@ A deep module (as opposed to a shallow module) is one which encapsulates a lot o
|
||||
|
||||
Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
|
||||
|
||||
3. Write the PRD using the template below and submit it as a GitHub issue.
|
||||
3. Write the PRD artifact using the template below. Default state is `ready-for-agent` (state vocabulary lives in `/triage`); category is `enhancement`. Present the artifact to the user, then end with a handoff hint:
|
||||
|
||||
> PRD ready. Invoke `/github` (or your configured backend equivalent) to publish — it will create the issue with category `enhancement` and state `ready-for-agent`.
|
||||
|
||||
Do not call `gh` directly. The backend skill owns publishing.
|
||||
|
||||
<prd-template>
|
||||
|
||||
|
||||
@@ -1,28 +1,32 @@
|
||||
---
|
||||
name: github-triage
|
||||
description: Triage GitHub issues through a label-based state machine. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
|
||||
name: triage
|
||||
description: Triage issues through a label-based state machine. Backend-agnostic — pairs with `/github` (or another backlog skill) to apply outcomes. Use when user wants to triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
|
||||
---
|
||||
|
||||
# GitHub Issue Triage
|
||||
# Triage
|
||||
|
||||
Triage issues in the current repo using a label-based state machine. Infer the repo from `git remote`. Use `gh` for all GitHub operations.
|
||||
Triage issues using a label-based state machine. This skill owns the *conceptual* state vocabulary, the AGENT-BRIEF format, and the workflows. It does **not** know how to talk to any specific backlog system — handoff to a backend skill (e.g. `/github`) when an outcome needs to be applied.
|
||||
|
||||
## AI Disclaimer
|
||||
|
||||
Every comment or issue posted to GitHub during triage **must** include the following disclaimer at the top of the comment body, before any other content:
|
||||
Every comment posted to a backlog system during triage **must** include the following disclaimer at the top, before any other content:
|
||||
|
||||
```
|
||||
> *This was generated by AI during triage.*
|
||||
```
|
||||
|
||||
The backend skill is responsible for prepending it.
|
||||
|
||||
## Reference docs
|
||||
|
||||
- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
|
||||
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
|
||||
|
||||
## Labels
|
||||
## States
|
||||
|
||||
| Label | Type | Description |
|
||||
The conceptual state vocabulary. The backend skill maps these to its platform's primitives (e.g. `/github` maps each to a GitHub label of the same name).
|
||||
|
||||
| State | Type | Description |
|
||||
| ----------------- | -------- | ---------------------------------------- |
|
||||
| `bug` | Category | Something is broken |
|
||||
| `enhancement` | Category | New feature or improvement |
|
||||
@@ -32,27 +36,27 @@ Every comment or issue posted to GitHub during triage **must** include the follo
|
||||
| `ready-for-human` | State | Requires human implementation |
|
||||
| `wontfix` | State | Will not be actioned |
|
||||
|
||||
Every issue should have exactly **one** state label and **one** category label. If an issue has conflicting state labels (e.g. both `needs-triage` and `ready-for-agent`), flag the conflict and ask the maintainer which state is correct before doing anything else. Provide a recommendation.
|
||||
Every issue should have exactly **one** state and **one** category. If an issue has conflicting states (e.g. both `needs-triage` and `ready-for-agent`), flag the conflict and ask the maintainer which is correct before doing anything else. Provide a recommendation.
|
||||
|
||||
## State Machine
|
||||
|
||||
| Current State | Can transition to | Who triggers it | What happens |
|
||||
| -------------- | ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| `unlabeled` | `needs-triage` | Skill (on first look) | Issue needs maintainer evaluation. Skill applies label after presenting recommendation. |
|
||||
| `unlabeled` | `ready-for-agent` | Maintainer (via skill) | Issue is already well-specified and agent-suitable. Skill writes agent brief comment, applies label. |
|
||||
| `unlabeled` | `ready-for-human` | Maintainer (via skill) | Issue requires human implementation. Skill writes a brief comment summarizing the task, applies label. |
|
||||
| `unlabeled` | `wontfix` | Maintainer (via skill) | Issue is spam, duplicate, or out of scope. Skill closes with comment (and writes `.out-of-scope/` for enhancements). |
|
||||
| `needs-triage` | `needs-info` | Maintainer (via skill) | Issue is underspecified. Skill posts triage notes capturing progress so far + questions for reporter. |
|
||||
| `needs-triage` | `ready-for-agent` | Maintainer (via skill) | Grilling session complete, agent-suitable. Skill writes agent brief comment, applies label. |
|
||||
| `needs-triage` | `ready-for-human` | Maintainer (via skill) | Grilling session complete, needs human. Skill writes a brief comment summarizing the task, applies label. |
|
||||
| `needs-triage` | `wontfix` | Maintainer (via skill) | Maintainer decides not to action. Skill closes with comment (and writes `.out-of-scope/` for enhancements). |
|
||||
| `needs-info` | `needs-triage` | Skill (detects reply) | Reporter has replied. Skill surfaces to maintainer for re-evaluation. |
|
||||
| Current State | Can transition to | Who triggers it | What happens |
|
||||
| -------------- | ----------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `unlabeled` | `needs-triage` | Skill (on first look) | Issue needs maintainer evaluation. Apply state after presenting recommendation. |
|
||||
| `unlabeled` | `ready-for-agent` | Maintainer (via skill) | Issue is already well-specified and agent-suitable. Write agent brief, apply state. |
|
||||
| `unlabeled` | `ready-for-human` | Maintainer (via skill) | Issue requires human implementation. Write a brief comment summarizing the task, apply state. |
|
||||
| `unlabeled` | `wontfix` | Maintainer (via skill) | Issue is spam, duplicate, or out of scope. Close with comment (and write `.out-of-scope/` for enhancements). |
|
||||
| `needs-triage` | `needs-info` | Maintainer (via skill) | Issue is underspecified. Post triage notes capturing progress so far + questions for reporter. |
|
||||
| `needs-triage` | `ready-for-agent` | Maintainer (via skill) | Grilling session complete, agent-suitable. Write agent brief, apply state. |
|
||||
| `needs-triage` | `ready-for-human` | Maintainer (via skill) | Grilling session complete, needs human. Write a brief comment summarizing the task, apply state. |
|
||||
| `needs-triage` | `wontfix` | Maintainer (via skill) | Maintainer decides not to action. Close with comment (and write `.out-of-scope/` for enhancements). |
|
||||
| `needs-info` | `needs-triage` | Skill (detects reply) | Reporter has replied. Surface to maintainer for re-evaluation. |
|
||||
|
||||
An issue can only move along these transitions. The maintainer can override any state directly (see Quick State Override below), but the skill should flag if the transition is unusual.
|
||||
The maintainer can override any state directly (see Quick State Override below), but the skill should flag if the transition is unusual.
|
||||
|
||||
## Invocation
|
||||
|
||||
The maintainer invokes `/github-triage` then describes what they want in natural language. The skill interprets the request and takes the appropriate action.
|
||||
The maintainer invokes `/triage` and describes what they want in natural language. The skill interprets the request, decides the outcome, then hands off to the configured backend skill (`/github` by default) to apply it.
|
||||
|
||||
Example requests:
|
||||
|
||||
@@ -64,13 +68,13 @@ Example requests:
|
||||
|
||||
## Workflow: Show What Needs Attention
|
||||
|
||||
When the maintainer asks for an overview, query GitHub and present a summary grouped into three buckets:
|
||||
When the maintainer asks for an overview, ask the backend skill to fetch issues grouped into three buckets:
|
||||
|
||||
1. **Unlabeled issues** — new, no labels at all. These have never been triaged.
|
||||
1. **Unlabeled issues** — new, no state at all. These have never been triaged.
|
||||
2. **`needs-triage` issues** — maintainer needs to evaluate or continue evaluating.
|
||||
3. **`needs-info` issues with new activity** — the reporter has commented since the last triage notes comment. Check comment timestamps to determine this.
|
||||
3. **`needs-info` issues with new activity** — the reporter has commented since the last triage notes comment.
|
||||
|
||||
Display counts per group. Within each group, show issues oldest first (longest-waiting gets attention first). For each issue, show: number, title, age, and a one-line summary of the issue body.
|
||||
Display counts per group. Within each group, show issues oldest first (longest-waiting gets attention first). For each issue, show: identifier, title, age, and a one-line summary of the issue body.
|
||||
|
||||
Let the maintainer pick which issue to dive into.
|
||||
|
||||
@@ -80,8 +84,8 @@ Let the maintainer pick which issue to dive into.
|
||||
|
||||
Before presenting anything to the maintainer:
|
||||
|
||||
- Read the full issue: body, all comments, all labels, who reported it, when
|
||||
- If there are prior triage notes comments (from previous sessions), parse them to understand what has already been established
|
||||
- Read the full issue: body, all comments, all states, who reported it, when (ask the backend skill to fetch it)
|
||||
- If there are prior triage notes from previous sessions, parse them to understand what has already been established
|
||||
- Explore the codebase to build context — understand the domain, relevant interfaces, and existing behavior related to the issue. Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md).
|
||||
- Read `.out-of-scope/*.md` files and check if this issue matches or is similar to a previously rejected concept
|
||||
|
||||
@@ -96,19 +100,19 @@ Tell the maintainer:
|
||||
|
||||
Then wait for the maintainer's direction. They may:
|
||||
|
||||
- Agree and ask you to apply labels → do it
|
||||
- Agree and ask you to apply the outcome → hand off to the backend skill
|
||||
- Want to flesh it out → start a /grill-with-docs session
|
||||
- Override with a different state → apply their choice
|
||||
- Want to discuss → have a conversation
|
||||
|
||||
### Step 3: Bug reproduction (bugs only)
|
||||
|
||||
If the issue is categorized as a bug, attempt to reproduce it before starting a /grill-with-docs session. This will vary by codebase, but do your best:
|
||||
If the issue is categorized as a bug, attempt to reproduce it before starting a /grill-with-docs session.
|
||||
|
||||
- Read the reporter's reproduction steps (if provided)
|
||||
- Explore the codebase to understand the relevant code paths
|
||||
- Try to reproduce the bug: run tests, execute commands, or trace the logic to confirm the reported behavior
|
||||
- If reproduction succeeds, report what you found to the maintainer — include the specific behavior you observed and where in the code it originates
|
||||
- If reproduction succeeds, report what you found — include the specific behavior you observed and where in the code it originates
|
||||
- If reproduction fails, report that too — the bug may be environment-specific, already fixed, or the report may be inaccurate
|
||||
- If the report lacks enough detail to attempt reproduction, note that — this is a strong signal the issue should move to `needs-info`
|
||||
|
||||
@@ -120,26 +124,35 @@ If the issue needs to be fleshed out before it's ready for an agent, interview t
|
||||
|
||||
### Step 5: Apply the outcome
|
||||
|
||||
Depending on the outcome:
|
||||
Determine the outcome, then hand off to the configured backend skill to apply it. The triage outcome consists of:
|
||||
|
||||
- **ready-for-agent** — post an agent brief comment (see [AGENT-BRIEF.md](AGENT-BRIEF.md))
|
||||
- **ready-for-human** — post a comment summarizing the task, what was established during triage, and why it needs human implementation. Use the same structure as an agent brief but note the reason it can't be delegated to an agent (e.g. requires judgment calls, external system access, design decisions, or manual testing).
|
||||
- **needs-info** — post triage notes with progress so far and questions for the reporter (see Needs Info Output below)
|
||||
- **wontfix (bug)** — post a polite comment explaining why, then close the issue
|
||||
- **wontfix (enhancement)** — write to `.out-of-scope/`, post a comment linking to it, then close the issue (see [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md))
|
||||
- **needs-triage** — apply the label. Optionally leave a comment if there's partial progress to capture.
|
||||
- **Target state** (one of the states above)
|
||||
- **Category** (bug or enhancement)
|
||||
- **Comment body** to post — varies by outcome:
|
||||
- **ready-for-agent** — an agent brief (see [AGENT-BRIEF.md](AGENT-BRIEF.md))
|
||||
- **ready-for-human** — a comment summarizing the task, what was established during triage, and why it needs human implementation. Same structure as an agent brief but note the reason it can't be delegated (e.g. requires judgment calls, external system access, design decisions, or manual testing).
|
||||
- **needs-info** — triage notes (see Needs Info Output below)
|
||||
- **wontfix (bug)** — a polite comment explaining why; the backend will close the issue
|
||||
- **wontfix (enhancement)** — write to `.out-of-scope/` (see [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)), then a comment linking to it; the backend will close the issue
|
||||
- **needs-triage** — optional comment if there's partial progress to capture
|
||||
|
||||
End with a handoff hint:
|
||||
|
||||
> Outcome ready. Invoke `/github` (or your configured backend equivalent) to apply state `<state>` to issue `<id>` with the comment above.
|
||||
|
||||
The backend skill maps the state name to its platform primitive, posts the comment, and closes the issue if `wontfix`.
|
||||
|
||||
## Workflow: Quick State Override
|
||||
|
||||
When the maintainer explicitly tells you to move an issue to a specific state (e.g. "move #42 to ready-for-agent"), trust their judgment and apply the label directly.
|
||||
When the maintainer explicitly tells you to move an issue to a specific state (e.g. "move #42 to ready-for-agent"), trust their judgment.
|
||||
|
||||
Still show a confirmation of what you're about to do: which labels will be added/removed, and whether you'll post a comment or close the issue. But skip the /grill-with-docs session entirely.
|
||||
Show a confirmation of what you're about to do: target state, category, whether a comment will be posted, whether the issue will be closed. Then hand off to the backend skill. Skip the /grill-with-docs session entirely.
|
||||
|
||||
If moving to `ready-for-agent` without a /grill-with-docs session, ask the maintainer if they want to write a brief agent brief comment or skip it.
|
||||
|
||||
## Needs Info Output
|
||||
|
||||
When moving an issue to `needs-info`, post a comment that captures the interview progress and tells the reporter what's needed:
|
||||
When moving an issue to `needs-info`, the comment body should be:
|
||||
|
||||
```markdown
|
||||
## Triage Notes
|
||||
Reference in New Issue
Block a user