Skip to content
Skills Library
Programming · Review & audit

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

Repository
cf-powers ↗
Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. When to Use
  3. The Process
  4. Quick Reference
  5. Common Mistakes
  6. Red Flags
  7. Integration
Original SKILL.md headings · 160 lines, 1,075 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.