Use this when you've made a code change and need to update related documentation and comments to stay in sync. Works alongside any code modification — feature work, refactoring, bug fixes, API changes.
Process
Step 1: Gather inputs
Ask the user to provide:
- The code change — a diff, PR link, commit hash, or description of what changed (functions renamed, APIs modified, behavior altered, files moved)
- Codebase location — which project or repo this is in
- Known documentation — any documentation files the user already knows about (README, API docs, architecture docs, configuration guides). If unsure, say "I'll scan for them."
Step 2: Identify documentation that needs updating
Scan for references to the changed code in:
| Documentation type | Where to look | What to check |
|---|---|---|
| README files | Project root, module directories | Setup instructions, usage examples, feature descriptions |
| Inline code comments | Files adjacent to the change | Function docstrings, block comments explaining behavior, TODO comments referencing changed code |
| API documentation | Docs directory, OpenAPI specs | Endpoint descriptions, parameter names, response formats, example requests |
| Architecture docs | ADRs, design docs | System diagrams, component descriptions, data flow explanations |
| Configuration guides | Deployment docs, env examples | Environment variables, config keys, default values |
| Changelog | CHANGELOG.md, release notes | Version history entries |
For each reference found, note whether it:
- Needs updating — references changed behavior, renamed items, or modified interfaces
- Needs removing — references deleted code or removed features
- Is still accurate — no update needed
Step 3: Generate documentation updates
For each documentation target that needs updating, produce:
Documentation updates for: (brief description of the code change)
File: (path/to/doc-file)
Current text:
(exact current text that needs changing)
Proposed update:
(updated text reflecting the code change)
Reason: (what changed in the code that makes this update necessary)
(Repeat for each documentation target.)
If any documentation references concepts that were removed entirely, flag them:
Removed references:
- (file:line) — references
(deleted function/API/concept). Recommend: (remove the section / replace with new equivalent / add deprecation note).
Step 4: Review and apply
Present all proposed updates to the user:
- Are these updates accurate?
- Any documentation files I missed?
- Should any of these changes be batched into the same PR as the code change?
- Any new documentation needed that doesn't exist yet? (Note: I'll flag this but won't create new docs unless you ask.)
Apply updates only after user approval.
Related skills
/code-review— use during code review to check whether documentation was updated alongside the change
Output location
Present the proposed documentation updates as formatted text in the conversation. The user applies the changes to their codebase.
Example Output
Input
- Code change: Renamed
generate_invoice()tocreate_invoice()acrossbilling/invoices.py; also changed thedue_dateparameter from an integer (days offset) to an ISO 8601 date string (e.g."2024-03-15"); removed the deprecatedsend_invoice_email()helper which was folded intocreate_invoice(notify=True) - Codebase location:
clearpath-billing— Python monorepo, internal billing service - Known documentation:
README.mdat project root,docs/api-reference.md, I think there's a changelog but not sure where
Output (abbreviated)
Documentation updates for: generate_invoice() → create_invoice(), due_date type change, removal of send_invoice_email()
File: README.md
Current text:
## Generating invoices
Call `generate_invoice(customer_id, due_date=30)` to create a new invoice due 30 days
from today. To notify the customer by email, call `send_invoice_email(invoice_id)`
after creation.
Proposed update:
## Creating invoices
Call `create_invoice(customer_id, due_date="2024-03-15")` to create a new invoice with
a specific due date. Pass `notify=True` to send the customer a notification email at
creation time.
Reason: Function renamed; due_date now takes an ISO 8601 string instead of a day offset integer; send_invoice_email() removed and its behavior absorbed into create_invoice(notify=True).
File: docs/api-reference.md
Current text:
### POST /invoices
Internally calls `generate_invoice(customer_id, due_date)` where `due_date` is an
integer representing days until the invoice is due.
**Parameters**
| Name | Type | Description |
|-------------|---------|---------------------------------|
| customer_id | string | Unique customer identifier |
| due_date | integer | Days from today until due |
Proposed update:
### POST /invoices
Internally calls `create_invoice(customer_id, due_date, notify=False)` where
`due_date` is an ISO 8601 date string.
**Parameters**
| Name | Type | Description |
|-------------|---------|------------------------------------------|
| customer_id | string | Unique customer identifier |
| due_date | string | Due date in ISO 8601 format (YYYY-MM-DD) |
| notify | boolean | If true, sends customer email on creation |
Reason: Function signature changed; due_date type changed from integer to ISO 8601 string; new notify parameter exposed at API layer.
File: billing/invoices.py (inline docstring)
Current text:
def create_invoice(customer_id, due_date, notify=False):
"""
Generate a new invoice. Previously called generate_invoice().
due_date: integer number of days until due.
Use send_invoice_email() to notify the customer separately.
"""
Proposed update:
def create_invoice(customer_id, due_date, notify=False):
"""
Create and return a new invoice for the given customer.
Args:
customer_id (str): Unique identifier for the customer.
due_date (str): Due date in ISO 8601 format, e.g. "2024-03-15".
notify (bool): If True, sends a notification email to the customer
upon creation. Defaults to False.
"""
Reason: Docstring still referenced the old function name, old due_date type, and the removed send_invoice_email() helper.
Removed references:
README.md:14— referencessend_invoice_email(invoice_id). Recommend: remove; replacement behavior iscreate_invoice(notify=True)(already captured in proposed update above).docs/api-reference.md:88— standalone section titled "Email Notifications viasend_invoice_email()". Recommend: remove the section entirely or replace with a note that notification is handled via thenotifyparameter onPOST /invoices.
Changelog: Found CHANGELOG.md at project root. No entry exists for this change yet.
⚠️ New documentation needed — no release note documents this breaking change (due_date type change is not backward-compatible). Recommend adding an entry under the current version. I won't create it unless you ask.
Review questions for you:
- Are the proposed
due_dateexamples ("2024-03-15") consistent with how your API layer formats dates, or should I use a different sample value? - Should the
docs/api-reference.mdremoval of the email section be a deletion or a deprecation notice? - Do you want me to draft the
CHANGELOG.mdentry for this breaking change? - Should all of these updates be included in the same PR as the code change?