documenting-changes
/documenting-changes
Use when implementation of a feature, fix, or refactor is finished, before claiming work complete or starting merge/PR — any change that may affect docs/, README, CHANGELOG, or inline docstrings/JSDoc
- Author
- cloudfieldcz ↗
- Repository
- cf-powers ↗
- Licence
- MIT
- Last repository change
- 15.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when implementation of a feature, fix, or refactor is finished, before claiming work complete or starting merge/PR — any change that may affect docs/, README, CHANGELOG, or inline docstrings/JSDoc
Original author description
Use when implementation of a feature, fix, or refactor is finished, before claiming work complete or starting merge/PR — any change that may affect docs/, README, CHANGELOG, or inline docstrings/JSDoc
How it works
- Overview
- When to Use
- The Process
- Quick Reference
- Common Mistakes
- Red Flags
- Integration
SKILL.md preview
--- name: documenting-changes description: Use when implementation of a feature, fix, or refactor is finished, before claiming work complete or starting merge/PR — any change that may affect docs/, README, CHANGELOG, or inline docstrings/JSDoc --- # Documenting Changes ## Overview Code without matching documentation rots into "what does this do?" within weeks. Catch drift the moment implementation finishes, while the change is still in your head. **Core principle:** When code changes, the docs that describe it must change too — or you must say why not. **Documentation is part of the authorized change.** Perform required updates without a separate permission stop. Keep explicit user deferrals or exclusions visible; do not silently mark missing documentation as complete. **Announce at start:** "I'm using the documenting-changes skill to keep docs in sync." ## When to Use **Always run before:** - Claiming a feature/fix is "done" - Step 1.5 of `finishing-a-development-branch` - Creating a PR for a feature, refactor, or bugfix **Skip only when:** - Pure cosmetic changes (formatting, whitespace, comment typos) - The user has explicitly said "no docs needed for this" ## The Process ### Step 1: Inventory the Change ```bash git diff <base>...HEAD --stat git diff <base>...HEAD -- '*.md' # committed documentation git diff --stat # unstaged changes git diff --cached --stat # staged changes git ls-files --others --exclude-standard # untracked files ``` Read the relevant staged/unstaged diffs and untracked files, not only their names. Use the task's actual delivery scope. Preserve unrelated user changes; do not attribute them to this task or stage them as part of documentation updates. Answer: - **Public surface changed?** — API, CLI flags, config keys, env vars, schemas, slash commands, hooks, plugin manifest - **Workflow/behavior changed?** — install steps, defaults, error messages, ordering - **New things appeared?** — new feature, module, command, skill, script ### Step 2: Map Each Change to Doc Locations For each change identified, walk **all five layers**: | Layer | What to check | |-------|---------------| | `docs/` | Architecture, guides, references, ADRs, plans | | `README.md` | Overview, install, quick-start, feature list (root + subdirectory READMEs) | | `CHANGELOG.md` / release notes | Entry under current/next version | | Inline (JSDoc, TSDoc, docstrings, Go doc comments) | Signatures, parameter docs, examples at definition sites | | Plugin/skill metadata | `.claude-plugin/*`, `skills/*/SKILL.md` description fields, version fields | ### Step 3: Decide per Change Technical layers (`docs/` architecture, ADRs, references, and inline docs) follow [Technical English](../using-superpowers/references/technical-english.md). README, user guides and user-facing CHANGELOG entries keep their own voice. Prefer the existing source of truth in `docs/`. If the repository uses another documentation system, follow that convention. Create a new document only when no existing guide fits, and link it from the relevant index or README. A changelog entry or final chat reply does not replace a required persistent guide. Each change resolves to exactly one of: 1. **UPDATE** — touches user-visible surface or modifies existing documented behavior → write the update 2. **CREATE** — entirely new feature with no existing doc home → create new file (and link from index/README) 3. **SKIP** — internal-only change → must give a one-line justification naming the specific module and confirming no public surface changed "Internal" alone is not a justification. "Refactored cache eviction in `src/internal/cache.ts`; no exported API, config, or behavior changed" is. ### Step 4: Apply and Report ``` Documentation review for this work: UPDATED: - docs/architecture.md — describe new event flow - README.md — add "MyFeature" to feature list - CHANGELOG.md — entry for v1.6.0 CREATED: - docs/guides/myfeature.md — usage guide for new MyFeature INLINE: - src/api/handler.ts — JSDoc on handleRequest() reflects new param SKIPPED (internal-only): - src/internal/cache.ts refactor — no public surface or behavior change Validation: [commands/results, or a named documentation gap] ``` Apply UPDATE and CREATE decisions within the authorized scope before reporting. Verify affected examples and links, plus the relevant repository checks. Ask only when a material documentation/product decision is unresolved or work would exceed existing authorization. - **Explicit user deferral** → record the gap locally or in the handoff. Creating an external issue still requires authorization. Do not claim the docs are complete. - **SKIP** → retain the specific reason; confirm existing docs remain accurate. - **Blocked update** → name the missing document or information and report that part as incomplete. A summary in chat is not a substitute. ## Quick Reference | Change type | Likely doc actions | |-------------|-------------------| | New public API/CLI flag | UPDATE README + CHANGELOG + inline docstring; consider docs/ guide | | New feature (user-facing) | CREATE docs/guides/<name>.md + UPDATE README feature list + CHANGELOG | | Behavior change of existing feature | UPDATE relevant docs/ page + CHANGELOG; check README quick-start | | Renamed/removed export | UPDATE inline docs at new site + CHANGELOG (breaking?) + grep `docs/` for old name | | Bugfix (no behavior change beyond fix) | CHANGELOG entry; SKIP rest with justification | | Internal refactor | SKIP all with one-line justification per affected module | | New skill / plugin command | CREATE SKILL.md or command doc + UPDATE plugin manifest + CHANGELOG | ## Common Mistakes **Skipping inline docs** - **Problem:** Function signature changed but docstring still describes old params - **Fix:** `grep` for the symbol you changed and check the doc comment at its definition **"I'll update docs in a follow-up PR"** - **Problem:** Follow-up PRs for docs rarely happen; drift compounds - **Fix:** Update in same change. If truly impossible, file an issue with a deadline before merging. **Updating only `docs/`** - **Problem:** `README.md` and inline docs still show old usage; users hit them first - **Fix:** Walk all five layers every time, even if most resolve to SKIP **Vague justification for skip** - **Problem:** "internal change" is a label, not a reason - **Fix:** Name the file/module and the surface that did NOT change **New feature with no doc home** - **Problem:** Adding a feature but updating only CHANGELOG — no place a user can learn how to use it - **Fix:** CREATE a `docs/guides/<name>.md` and link from README, even if short ## Red Flags - About to claim "done" without having looked at `docs/` - Edited a function but didn't open its docstring - Added a new feature with no entry in README or `docs/` - "The code is self-documenting" (often true at unit level, almost never true for user-facing features or workflows) - Skipping with no justification, or justification that just repeats "internal" ## Integration **Called by:** - `finishing-a-development-branch` (Step 1.5) — between test verification and presenting merge/PR options - `verification-before-completion` — completion claims include "docs reviewed" **Independent invocation:** Any time after a non-trivial change, even mid-work, to keep drift from accumulating.
Versions
The database has no other skills named documenting-changes.
Database snapshot: 13.11.2026 · package version 33e0a2f5b84f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100documenting
Writes or updates project documentation (README, docs/, docstrings, decision log). Use when behaviour, setup, or architecture changes, or when asked to document something. - 100post-impl-docs
Update repository documentation after code implementation. Maintains README, CHANGELOG, docs/ folder, and inline docstrings based on changes made. Triggered by lane-executor after task completion. - 100documentation
Generate docstrings, JSDoc, API docs, and README updates that reflect current code. Use when: docs, docstring, JSDoc, README, API docs, document this, add documentation. - 100docs-writer
Write and update developer documentation (READMEs, docstrings and code comments, ADRs, CHANGELOG entries in Keep a Changelog format, and API usage docs) based on the actual code, with commands and examples that run. Use when the user asks to document a project, module, function… - 100api-docs-generator
Generates API documentation from code including OpenAPI specs, JSDoc, and Python docstrings. Use when documenting APIs, REST endpoints, or library functions. - 100documentation-generation
Generates project documentation including READMEs, docstrings (JSDoc, JavaDoc, Python docstrings), OpenAPI prose, and CI/CD doc pipelines. Use when asked to generate docs, write docstrings, automate documentation, or create README files.