revise-best-practice-skill
Revise Best Practice 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)