review-best-practice-skill

Review Skill

Evaluate a proposed SKILL.md against grimoire standards and produce a structured PASS / NEEDS-REVISION / REJECT verdict with specific findings per criterion.

Why This Is Best Practice

Adopted by: Deterministic review checklists are standard in high-quality OSS projects — Linux kernel patch review, CPython PEPs, React RFC process, and most projects with a quality bar use structured, criteria-based review over subjective human judgement. Impact: Structured checklist-based review (Fagan Inspection method, IBM 1976) achieves 60–90% defect detection — highest of any quality technique per Capers Jones (Software Quality Engineering, 2011). Consistent criteria reduce reviewer disagreement from 40–60% (ad-hoc review) to <10% (checklist-based) per Bacchelli & Bird, ICSE 2013. Agent execution reduces review turnaround from days to seconds. Why best: A checklist applied by humans drifts over time and varies by reviewer. A skill applied by an AI agent produces identical criteria evaluation every time, making the standard self-enforcing rather than aspirational.

Sources: Linux kernel patch review process, CPython PEP review guidelines, Bacchelli & Bird (ICSE 2013), Capers Jones (Software Quality Engineering, 2011)

Steps

1. Read the proposed skill

Read the SKILL.md at the path provided (or inferred from context). Extract: full frontmatter, all ## section headers, full body content.

2. Check frontmatter — FAIL any missing field → REJECT

Field	Check
name	Passes naming standard: verb-first, specific subject, 2–4 words, no rejected verbs, abbreviation policy applied
description	Starts with "Use when", describes triggering conditions NOT content, ≤500 chars
source	Present and names specific institution, standard body, or top-tier companies
tags	3–8 tags covering all 4 axes: problem keyword, tool/method, role/context, outcome

3. Check required sections — missing either → REJECT

• ## Why This Is Best Practice exists
• ## Steps or ## Core Pattern exists

4. Grill "Why This Is Best Practice" — each sub-field

Adopted by — ask these challenge questions:

• Does it name specific companies or institutions? ("many companies" = FAIL)
• Does it claim majority top-tier adoption, not just notable examples?
• Would a domain expert agree this is the majority position?

Impact — ask these challenge questions:

• Is the outcome measurable? (%, time saved, defect reduction, risk reduction)
• Is specific evidence cited? (study, company data, systematic review)
• Is "significantly better" or similar vague language present? (FAIL if no number)

Why best — ask these challenge questions:

• Is at least one alternative mentioned and explicitly compared?
• Is the argument "this wins because X" rather than just "this is good"?

Sources — ask these challenge questions:

• Is the source verifiable? (not just "industry standard" — name the standard)
• Is the source credible? (institution, peer-reviewed research, major engineering blog)

5. Check quality criteria

• Actionable: steps are concrete, commandable, immediately executable — not theory
• Scoped: one concept only — ask "could this cleanly be two skills?"
• Industry-proven: cross-check "Adopted by" claim against criterion 3 bar (majority, not minority)
• Specific: names tools, cites numbers, shows commands — no abstract rules without examples
• Complete: covers failure modes, edge cases, "if X fails do Y" — not just happy path

6. Check domain safety (where applicable)

Domain	Required
health / medicine	Evidence tier tags [RCT]/[SR]/[Consensus]/[Practical] present; healthcare provider footer
law	Jurisdiction stated; "not legal advice" disclaimer footer
finance / investing	Risk disclosure where relevant; "not financial advice" footer
psychology / mental health	No diagnosis/prescription; mental health professional footer

7. Check size

• Under 50 lines: too shallow — flag for expansion
• Over 300 lines: likely two skills — flag for splitting

8. Staleness check

• Does the content reference tools, APIs, or practices that are outdated or superseded?
• Does the "Adopted by" claim reflect current (not historical) practice?

9. Output structured verdict

## Skill Review: <skill-name>

### Overall Verdict: PASS | NEEDS-REVISION | REJECT

### Findings

| Criterion | Result | Finding |
|-----------|--------|---------|
| name | ✅ / ❌ / ⚠️ | — or specific issue |
| description | ✅ / ❌ / ⚠️ | — or specific issue |
| source | ✅ / ❌ / ⚠️ | — or specific issue |
| tags | ✅ / ❌ / ⚠️ | — or specific issue |
| Why Best Practice — present | ✅ / ❌ | — |
| Why Best Practice — Adopted by | ✅ / ❌ / ⚠️ | — or specific issue |
| Why Best Practice — Impact | ✅ / ❌ / ⚠️ | — or specific issue |
| Why Best Practice — Why best | ✅ / ❌ / ⚠️ | — or specific issue |
| Why Best Practice — Sources | ✅ / ❌ / ⚠️ | — or specific issue |
| Actionable | ✅ / ❌ / ⚠️ | — or specific issue |
| Scoped | ✅ / ❌ / ⚠️ | — or specific issue |
| Industry-proven | ✅ / ❌ / ⚠️ | — or specific issue |
| Specific | ✅ / ❌ / ⚠️ | — or specific issue |
| Complete | ✅ / ❌ / ⚠️ | — or specific issue |
| Domain safety | ✅ / ❌ / N/A | — or specific issue |
| Size | ✅ / ⚠️ | <N> lines |
| Staleness | ✅ / ⚠️ | — or specific issue |

### Required fixes before merge (REJECT / NEEDS-REVISION only)
1. <specific fix with example>
2. <specific fix with example>

Rules

• REJECT if any frontmatter field is missing or empty
• REJECT if ## Why This Is Best Practice section is absent
• REJECT if "Adopted by" names no specific companies or institutions
• REJECT if "Impact" has no quantified outcome
• NEEDS-REVISION for vague claims that can be strengthened with specifics
• PASS only when all criteria are ✅ — no unchecked items
• When flagging a FAIL or REVISION, always state exactly what fix is needed