review-best-practice-skill

name	review-best-practice-skill
description	Use when evaluating whether a SKILL.md meets STANDARD.md criteria — for PR review of official grimoire-core contributions, self-review before submitting, auditing existing skills, or reviewing skills in a user package that has voluntarily adopted the standard.
source	Linux kernel patch review process, CPython PEP review guidelines, Apache Software Foundation governance
tags	["skill-review","quality-gate","checklist","reviewer","maintainer","defect-prevention","consistency"]

Review Best Practice 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

Package scope. This review applies the full STANDARD.md checklist, which is required for the official grimoire-core package. For skills in a user package, this review is optional — use it only if the package has chosen to follow STANDARD.md.

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

Domain safety list: Valid domains are defined in CLAUDE.md's domain table. If the skill's domain field does not match one of the listed domains, flag it: 'Unknown domain: [domain]. Valid domains: engineering, business, science, health, writing, design, marketing, finance, law, film, music, art, sports, psychology, language, education, cooking, travel, home, parenting, automotive, pets, fashion, environment, photography, productivity, meta.'

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?
• Search the internet to verify — don't rely on training-data recall alone, since it may predate recent changes. Confirm whether the cited institution/source still holds this position and whether the referenced tool/API is still current before flagging or clearing this criterion. If no internet-access tool is available in this environment, say so explicitly and proceed on best available knowledge — flag the claim as unverified rather than silently skipping the check or asserting it was confirmed. After searching, state what was found (or that nothing conclusive turned up) before proceeding — don't just announce the check and discard the result.

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

REJECT vs NEEDS-REVISION criteria:

• REJECT — use when: the skill's core premise is wrong (bad source, disproven claim), the skill is a duplicate of an existing skill, or the skill violates STANDARD.md in a way that requires a complete rewrite (not iteration)
• NEEDS-REVISION — use when: the skill's premise is sound but execution has fixable issues (missing fields, weak examples, unclear steps, threshold not defined)
• PASS — use when: all STANDARD.md criteria are met or only trivial formatting issues remain

Do not REJECT a skill that merely needs improvement — that wastes the author's work. REJECT is for fundamental problems.