Two-phase workflow to keep project documentation synchronized with code changes
Analyzes git diffs to identify documentation gaps after code changes, then updates all project docs (README, CLAUDE.md, examples) to stay synchronized. Use before merging or marking features complete to prevent documentation drift.
/plugin marketplace add cipherstash/cipherpowers/plugin install cipherpowers@cipherpowersThis skill inherits all available tools. When active, it can use any tool Claude has access to.
test-scenarios.mdDocumentation drift is inevitable without systematic maintenance. Code evolves rapidly while documentation becomes stale. This skill provides a two-phase workflow to keep project docs synchronized with code: analyze recent changes, then update and restructure documentation accordingly.
Use this skill when:
When NOT to use:
Maintaining existing documentation after code changes is NOT "proactively creating docs" - it's keeping current docs accurate.
CLAUDE.md instructions about "don't proactively create documentation" apply to NEW documentation files for undocumented features. They do NOT apply to maintaining existing documentation after you change the code it documents.
If you changed the code, you must update the corresponding documentation. No exceptions.
| Rationalization | Reality |
|---|---|
| "I'll update docs in a follow-up PR" | Later rarely happens. Context is freshest now. Capture it. |
| "Commit messages are documentation enough" | Commit messages explain code changes, not user workflows. Both are needed. |
| "Code is self-documenting if well-written" | Code shows HOW. Docs explain WHY and usage patterns. Different purposes. |
| "Time pressure means ship now, document later" | Shipping undocumented changes creates support burden > time saved. |
| "Don't know if user wants docs updated" | If code changed, docs MUST update. Not optional. Ask about scope, not whether. |
| "Documentation is maintenance overhead" | Outdated docs are overhead. Current docs save time for everyone. |
| "Minimal accurate > comprehensive outdated" | False choice. This skill gives you accurate AND complete in 15-30 min. |
| "Different teams handle docs differently" | This skill IS the standard for this project. Follow it. |
| "Risk of making commit scope too large" | Documentation changes belong with code changes. Same PR = atomic change. |
| "Best practices docs only change for patterns" | If you discovered lessons during implementation, they belong in CLAUDE.md. |
None of these are valid reasons to skip documentation maintenance.
| Phase | Focus | Key Activities |
|---|---|---|
| Analyze | What changed? | git diff → review docs → identify gaps |
| Update | Sync docs | Update content → restructure → summarize changes |
Goal: Understand what changed and what documentation needs updating
Review recent changes:
git diff [base-branch]...HEAD
Examine the full diff to understand scope of changes
Check existing documentation:
Identify documentation gaps:
Output of analysis phase: List of specific documentation updates needed
Goal: Bring documentation into sync with current code
Update content to reflect changes:
Restructure for clarity:
Document updates: Provide summary of changes:
Follow project documentation standards defined in:
Key standards to verify:
| Mistake | Fix |
|---|---|
| Updating only README, missing other docs | Check CLAUDE.md, README_*.md, docs/ systematically |
| Not reviewing git diff | Always start with full diff to understand scope |
| Describing "what" without "why" | Explain rationale, not just functionality |
| Forgetting to update examples | Changed APIs must update all examples |
| Batch updating at project end | Update at natural checkpoints (feature complete, before merge) |
| Restructuring separately from updates | Restructure while updating to prevent redundant passes |
| Missing troubleshooting updates | Document edge cases and solutions discovered during work |
These are consistently skipped under pressure. Check explicitly:
✅ MUST check every time:
Common blind spots:
Situations:
Rationalizations (means you're about to skip docs):
All of these mean: Stop and run this workflow before proceeding.
Without systematic maintenance:
With this workflow:
This skill can be invoked by:
Commands should provide context about documentation practices and reference this skill for methodology.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.