Content
85%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a tightly scoped, highly actionable contributing playbook with a clear sequenced workflow, validation gates, and a single real one-level-deep reference. Its main weakness is redundancy — the same rules (clean-upstream repro, provider/model capture, no-PR-before-approval) recur across four sections and could be consolidated.
Suggestions
Consolidate the repeated clean-upstream-reproduction and provider/model-capture rules so each appears in one canonical place (e.g. the Workflow) with the checklist and Don't Do This sections cross-referencing rather than restating them.
The 'Lesson from pi-mono issue #1899' section restates rules already encoded in Non-Negotiables and the Workflow; consider trimming it to the single forward-looking rule it ends on.
Tighten colloquial filler ('write the issue like an adult', 'shut up and go debug more') to preserve tone without the extra tokens, since the same guidance is stated more precisely elsewhere.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly high-signal procedural knowledge rather than concepts Claude already knows, but the same rules are restated across Non-Negotiables, the Workflow steps, the Pre-Submit Checklist, and Don't Do This (e.g. clean-upstream reproduction and provider/model capture appear three to four times), which is noticeable redundancy that could be tightened. | 3 / 5 |
Actionability | Provides executable commands (git worktree add, npm install, gh issue view --json, npm run check), a copy-paste issue template, a concrete evidence-pack list, and a package-triage mapping — concrete and directly actionable rather than abstract. | 5 / 5 |
Workflow Clarity | A clearly sequenced five-step workflow with explicit validation gates ('If any answer is no or not sure, keep digging locally'; 'If the bug disappears on clean origin/main, it is not yet an upstream core bug') plus a pre-submit checklist; the issue-filing task is not a destructive/batch op so the validation cap does not bind. | 5 / 5 |
Progressive Disclosure | SKILL.md is a well-sectioned overview that signals a single one-level-deep reference ('For the repo/maintainer deep dive, read: references/pi-mono-research.md'), and that referenced file exists in the bundle, keeping navigation shallow and verifiable. | 5 / 5 |
Total | 18 / 20 Passed |