Files

Defame1297 4f49b2a249 refactor(bin): move non-spec root files into references/ across four skills

grill-with-docs, improve-codebase-architecture, tdd, and triage kept
non-spec markdown files at their skill root, in violation of
skill-audit's file-structure.md rule (only SKILL.md/README.md belong
at the root; everything else lives in scripts/, references/, assets/
or tests/). A root-level file is invisible to the ADR-0020
dangling-reference gate, which only resolves unqualified
`references/...` pointers.

- Moved and renamed to lowercase-kebab-case under references/:
  grill-with-docs (ADR-FORMAT.md, CONTEXT-FORMAT.md),
  improve-codebase-architecture (DEEPENING.md, INTERFACE-DESIGN.md,
  LANGUAGE.md), tdd (five files, casing was already fine), triage
  (AGENT-BRIEF.md, OUT-OF-SCOPE.md).
- Updated every in-skill link to the new references/ paths, including
  link text that still showed the old uppercase filenames.
- Fixed improve-codebase-architecture/SKILL.md's cross-skill citation
  of grill-with-docs's two files to the sanctioned possessive form
  with the references/ segment included.
- Updated all four skills' README.md file tables to match.
- Regenerated the flat content mirror via
  scripts/sync-plugin-content.sh --all.

Fixes #122.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88

2026-09-09 19:59:02 +00:00

3.0 KiB

Raw Blame History

triage

Move issues on the project issue tracker through a small state machine of triage roles.

What it does

Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one category role (bug, enhancement) and one state role (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at needs-triage; needs-info returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.

A run does one of three things depending on what the maintainer asks for:

Show what needs attention — three buckets, oldest first: unlabeled, needs-triage, and needs-info with reporter activity since the last triage notes.
Triage a specific issue — gather context (including prior triage notes, so resolved questions are not re-asked, and .out-of-scope/ records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs before any grilling, run a grill-with-docs session if the issue needs fleshing out, then apply the outcome.
Quick state override — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.

Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are not necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at.

Composition

grill-with-docs is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: diagnose names this skill as the place to send a reported bug that needs filing rather than debugging.

Usage

/triage

Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".

Files

File	Purpose
`SKILL.md`	The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session
`references/agent-brief.md`	Cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers
`references/out-of-scope.md`	Cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests

3.0 KiB Raw Blame History