docs: trim skill READMEs and ADR/changelog narration
Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
@@ -1,35 +0,0 @@
|
||||
# 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
|
||||
|
||||
```text
|
||||
/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 |
|
||||
Reference in New Issue
Block a user