Add syncing-documentation skill #333
Conversation
Teaches agents to proactively keep documentation synchronized with
code changes. Uses subagent investigation to gather context before
updating docs.
- Resists time pressure ("quick", "nothing fancy")
- Push back on authority pressure ("I'll handle docs")
- Continues work after refactoring exhaustion
- Provides clear workflow with investigation subagent dispatch
- Tested via RED-GREEN-REFACTOR TDD cycle
Addresses common rationalizations:
- "Code is self-documenting"
- "User said skip docs"
- "I'll do it later"
- "Too tired after refactor"
- "JSDoc is enough"
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughA new documentation file is added to establish formal guidelines and workflow for syncing documentation updates with code changes. The document outlines when to trigger updates, a standardized pattern for documentation process steps, reference matrices for change types, implementation procedures, common pitfalls, and key principles ensuring documentation evolves in concert with code modifications. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@skills/syncing-documentation/SKILL.md`:
- Line 53: The fenced code blocks in SKILL.md are missing language identifiers
which trips markdownlint and reduces readability; update each triple-backtick
fence used for plain text or prompts (the blocks containing the numbered
checklist, the Subagent prompt, and the "MEANINGFUL CODE CHANGE..." warning) to
include a language token such as text (i.e., change ``` to ```text) so
markdownlint recognizes them—ensure all occurrences referenced in the review
(the code block around the checklist, the Subagent prompt block, and the final
warning block) are updated consistently.
- Line 143: The three short sentences "No exceptions. No rationalizations. No
\"later.\"" read repetitive; change one sentence to vary its opening—e.g., keep
"No exceptions." but reword the second or third to start differently (for
example, "Avoid rationalizations." or "Don't postpone it.") so the line in
SKILL.md that currently reads "No exceptions. No rationalizations. No
\"later.\"" becomes stylistically varied while preserving the original meaning.
|
|
||
| ### After (With Discipline) | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Specify language for fenced code blocks.
Markdownlint flags these fences as missing language identifiers, which can break linting and reduce readability.
🛠️ Suggested fix
-```
+```text
1. Code change completed
2. Dispatch subagent to investigate: "What documentation exists for this module? What changed? What docs need updating?"
3. Review findings and identify affected .md files
4. Update documentation with current state
5. Work now complete
-```
+```
-```
+```text
Subagent prompt: "Investigate the documentation for [module/feature].
Find all relevant .md files. Identify what documentation exists,
what changed in the code, and what specifically needs updating.
Return: file paths and specific sections needing updates."
-```
+```
-```
+```text
MEANINGFUL CODE CHANGE WITHOUT DOC UPDATE = INCOMPLETE WORK
-```
+```Also applies to: 82-82, 139-139
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@skills/syncing-documentation/SKILL.md` at line 53, The fenced code blocks in
SKILL.md are missing language identifiers which trips markdownlint and reduces
readability; update each triple-backtick fence used for plain text or prompts
(the blocks containing the numbered checklist, the Subagent prompt, and the
"MEANINGFUL CODE CHANGE..." warning) to include a language token such as text
(i.e., change ``` to ```text) so markdownlint recognizes them—ensure all
occurrences referenced in the review (the code block around the checklist, the
Subagent prompt block, and the final warning block) are updated consistently.
| MEANINGFUL CODE CHANGE WITHOUT DOC UPDATE = INCOMPLETE WORK | ||
| ``` | ||
|
|
||
| No exceptions. No rationalizations. No "later." |
There was a problem hiding this comment.
Vary sentence openings for polish.
Three successive sentences start with “No …” which reads repetitive. Consider rephrasing one of them.
🧰 Tools
🪛 LanguageTool
[style] ~143-~143: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...`` No exceptions. No rationalizations. No "later." **Violating the letter of thi...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
In `@skills/syncing-documentation/SKILL.md` at line 143, The three short sentences
"No exceptions. No rationalizations. No \"later.\"" read repetitive; change one
sentence to vary its opening—e.g., keep "No exceptions." but reword the second
or third to start differently (for example, "Avoid rationalizations." or "Don't
postpone it.") so the line in SKILL.md that currently reads "No exceptions. No
rationalizations. No \"later.\"" becomes stylistically varied while preserving
the original meaning.
1 participant
Summary
Adds a new discipline skill that teaches agents to proactively keep documentation synchronized with code changes.
What it does
Testing
The skill was developed following the TDD approach for documentation:
RED: Ran baseline scenarios without the skill, documented exact rationalizations agents use:
GREEN: Wrote skill addressing those specific violations
REFACTOR: Re-ran scenarios WITH skill - all agents now comply
Test Results
Why this skill matters
Documentation drift is a chronic problem in codebases. Even well-intentioned developers skip docs under time pressure, after exhausting refactors, or when explicitly told "don't worry about it." This skill treats documentation sync as a discipline—not optional overhead, but part of completing the work.
Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.