| name | revise-best-practice-skill |
| description | Use when an existing SKILL.md has review-best-practice-skill findings to address, a citation has become inaccurate, steps reference an outdated tool, or scope needs adjusting — splitting a skill that covers two concepts, or expanding one that is too shallow. |
| source | IETF RFC errata process (BCP 9), MDN Web Docs contribution guidelines, Wikipedia article improvement process |
| tags | ["skill-revision","quality-debt","targeted-fix","contributor","maintainer","review-pass"] |
Revise Skill
Update an existing grimoire SKILL.md to resolve specific findings without touching validated content.
Why This Is Best Practice
Adopted by: Targeted revision of specific findings is the standard maintenance model across all long-lived technical documentation systems — IETF errata correct specific claims in RFCs without replacing the full document, MDN Web Docs uses targeted pull requests per section rather than full-article rewrites, and Wikipedia's peer review process improves articles through iterative section-level fixes rather than wholesale replacement.
Impact: Targeted revision preserves validated content while addressing gaps — wholesale rewrite discards working sections and resets review history unnecessarily. Aghajani et al. (2019, MSR) found that the vast majority of documentation fixes in OSS projects are targeted single-section changes; wholesale rewrites are rare and reserved for fundamental practice changes. The IETF errata model demonstrates that long-lived technical documents can remain accurate for decades through targeted correction while full replacements introduce regression risk across all sections.
Why best: Fixing only flagged findings — vs. refactoring the whole file "while you're there" — prevents introducing new issues in sections that were already PASS. A full rewrite is the alternative; it costs more, discards verified content, and risks new failures in sections that passed.
Sources: IETF RFC errata process (BCP 9), MDN Web Docs contribution guidelines, Wikipedia article improvement process, Aghajani et al. 2019 (MSR documentation debt)
Steps
1. Load findings
Get the finding set:
- review-best-practice-skill already run → use its structured output directly
- No findings yet → run
review-best-practice-skill on the file first; use its output
- Findings from user report (not review-best-practice-skill format) → map each to a review-best-practice-skill criterion name before proceeding
2. Classify each finding by type
| Finding type | Scope of fix |
|---|
| Frontmatter field (name, description, source, tags) | Frontmatter only — don't touch body |
| "Adopted by" inaccurate or vague | ## Why This Is Best Practice only |
| "Impact" citation weak or fabricated | ## Why This Is Best Practice only |
| Steps reference outdated tool or API | Affected step(s) only |
| Steps not actionable or too abstract | Affected step(s) only |
| Scope too broad (two separable concepts) | Split — see step 4 |
| Scope too shallow (<50 lines) | Expand Steps with concrete examples |
| Domain safety footer missing | Add footer only |
3. Order revisions: structural before content
Structural before content: Always apply structural revisions before content revisions.
- First: fix step ordering, add/remove steps, fix routing logic, add missing required fields
- Then: improve wording, strengthen examples, tighten descriptions
Structural changes invalidate content — if you improve wording in a step that will be removed, the content work is wasted. Structure is the skeleton; content is the flesh.
4. Fix each finding in isolation
Fix the flagged item. Don't touch adjacent text that wasn't flagged.
❌ Citation wrong → rewrite entire Why section
✅ Citation wrong → replace the one sentence containing the citation
❌ One step vague → rewrite all steps for consistency
✅ One step vague → rewrite that step only
If fixing a citation requires changing the surrounding sentence for grammatical coherence, that is acceptable. Touching unrelated paragraphs is not.
5. Scope fix: splitting
If the finding is "skill covers two separable concepts":
- Identify concept A (primary — stays in this file) and concept B (extract)
- Remove concept B content from the current skill
- Create a new directory for concept B's skill
- Run
write-best-practice-skill to author the extracted skill from scratch — do not copy the removed content verbatim; the extracted skill needs its own Why section, sources, and steps
- Run
review-best-practice-skill on both resulting skills
This is a scope reduction, not a deprecation. Do not add a deprecation notice to the concept A skill.
6. Verify: re-run review-best-practice-skill
After all fixes are applied, run review-best-practice-skill on the updated file:
- All previously flagged criteria now ✅ → proceed to PR
- New ❌ introduced by the fix → resolve before opening PR
- Previously PASS criteria now ❌ → the fix caused a regression; revert that change
7. Open a PR
PR title: fix(<domain>/<skill-name>): <one-line description of what changed>
PR description: one line per finding, stating what it was and how it was resolved.
PR template: When submitting a skill revision as a PR, title format: fix(skills): [what was fixed] in [skill-name]. Body must include:
- What finding triggered this revision (quote the NEEDS-REVISION finding)
- What was changed (structural or content)
- Any STANDARD.md criteria newly passing after the revision
Rules
- Never fix what wasn't flagged — scope creep in revision introduces regressions
- One PR per skill — if multiple skills need revision, open separate PRs
- Always re-run
review-best-practice-skill after revision — don't assume the fix resolved the finding
- Splitting is a revision, not a deprecation — do not mark the original skill as deprecated
- If a finding cannot be resolved without invalidating the skill's core claim, use
deprecate-best-practice-skill instead
Common Mistakes
Rewriting the whole skill for one citation: fix the citation sentence; leave everything else.
"Improving" unflagged sections: if review-best-practice-skill didn't flag it, don't touch it — even if you'd write it differently.
Skipping re-verification: a fix can introduce a new failure. Always re-run review-best-practice-skill after editing.
Treating scope reduction as deprecation: splitting a skill that was too broad is a fix. Both resulting skills live on — neither is retired.
