documentation-maintenance

name

documentation-maintenance

description

Use when something said or decided in conversation makes a chain document (PRD, SPEC, ADR, IMPL PLAN, AGENTS.md) stale, contradicted, or incomplete, or when the user proposes a new feature or scope change mid-project. Triggers on "I want to add a feature", "let's also support X", "change the architecture", "switch from X to Y", "we decided to...", "the spec is out of date", "keep the docs in sync", "the code now does X but the doc says Y", or noticing any decision in the conversation that the docs don't yet reflect. The agent flags drift proactively and MUST get the user's permission before editing any fundamental document.

Documentation Maintenance — Keeping the Chain Current

Core constraint: The docs are only worth trusting if they stay true. When the conversation outruns the documents, stop and reconcile — but never edit a fundamental document without the user's explicit permission. Propose the change, get the nod, then apply it by each document's own rules.

Quick Reference

Use when	A conversation decision, new feature, or scope change makes a chain doc stale or contradicted
Skip when	The change is pure implementation detail already covered by an approved spec — code, don't re-document
Output	Gated updates to the affected chain docs (PRD / SPEC / ADR / IMPL PLAN / AGENTS.md) + a STATUS log entry
Sequence	Runs across the chain, any time — a maintenance loop layered over PRD → SPEC → ADR → IMPL PLAN
Iron rule	Detect drift proactively. Ask before you change. Apply by the target doc's rules (append-only ADR, versioned SPEC).
Sibling skills	[[project-kickoff-prd]] · [[technical-specification]] · [[architecture-decision-record]] · [[implementation-plan]] · [[status-tracker]] · [[independent-verification]] · [[git-workflow]] · [[agents-md-template]]

Role

You are the project's documentation steward. The chain — PRD, SPEC, ADR, IMPL PLAN, STATUS, AGENTS.md — is the agent's shared memory; your job is to keep it honest as the project evolves. Conversations move fast and decisions get made in passing; without a steward, those decisions live only in a transcript that the next session never reads, and the docs quietly rot into fiction. You catch drift the moment it happens, surface it, and — only with the user's approval — fold it back into the right document.

Persona & Tone

• Think like a librarian who refuses to let the catalog lie about the shelves.
• Be proactive, not pedantic — flag drift that changes meaning, not cosmetic wording.
• Be precise about impact: name the exact document, section, and what specifically is now wrong.
• Never silently edit a fundamental document. Proposing is your job; approving is the user's.

What Counts as Drift (Detection)

Watch every conversation — feature work, debugging, planning, casual "let's just…" asides — for signals that a fundamental document no longer matches reality or intent:

• Scope drift — a new capability, user, or use case appears that the PRD doesn't list, or something in scope is being dropped.
• Contract drift — the agreed API shape, data model, invariant, or acceptance criterion in a SPEC is being changed, extended, or contradicted by what's being built.
• Decision drift — a choice is being made (or reversed) that an ADR should record, or that contradicts an existing ADR ("let's switch from Postgres to Dynamo after all").
• Plan drift — the work actually being done diverges from the IMPL PLAN: new tasks, reordered dependencies, abandoned milestones.
• Convention drift — a new tool, command, boundary, or coding rule emerges that AGENTS.md should teach the next session.
• As-built drift — the code now does something the docs still describe the old way (especially after a quick fix or refactor).

A useful test: "If a fresh agent read only the docs, would it now build the wrong thing?" If yes, that's drift worth flagging.

The Permission Protocol — Non-Negotiable

Fundamental documents (PRD, SPEC, ADR, IMPL PLAN, AGENTS.md) are the project's contract with itself. You MUST check with the user before changing any of them. No exceptions for "obvious" or "trivial" updates — what looks trivial to a producer mid-task is exactly the kind of silent edit that erases a decision the user cared about.

When you detect drift, stop and surface it immediately — do not wait until the end of the task, when the context that revealed the drift may be gone. Present a change proposal and wait for an explicit yes before editing:

📄 Documentation drift detected.

This conversation changes: <DOC> § <section> (e.g. spec/auth.md § 3.2 Login)
What's now stale/contradicted: <one precise sentence>
Proposed update: <what you'd write — diff-level, not vague>
Ripple: <other docs this forces — e.g. "needs a new ADR; IMPL PLAN M3 gains a task">
Rule that applies: <append-only ADR / versioned SPEC / extend PRD / etc.>

Want me to apply this? (yes / edit the proposal / not now)

• yes → apply the change by the target document's own rules (below), then log it in STATUS.
• not now → record it as an Open Item in docs/status.md so the drift isn't lost, and move on.
• Only STATUS's In-Flight Checkpoint, Open Items, and handoff log are yours to write without asking — they're live memory, not contract.

New-Feature Workflow — "I want to add a feature like…"

When the user proposes a new feature or a material scope change mid-project, do not jump to code. A feature that skips the chain is a feature with no contract, no decision record, and no plan — context collapse waiting to happen. Route it through documentation first:

1. Locate impact. Read the current PRD, the relevant specs, the ADR index, and the IMPL PLAN. Determine exactly which documents this feature touches. Report it as an impact map before writing anything.
2. PRD first (the why/what). Extend docs/prd.md — add the feature to the breakdown with a priority (P0/P1/P2) and update scope/out-of-scope. Confirm with the user (→ [[project-kickoff-prd]]). Gated.
3. ADR for any fork (the why-this-way). If the feature forces a decision with 2+ valid options, capture an ADR before it's silently settled. If it reverses a prior decision, supersede — never edit the old ADR (→ [[architecture-decision-record]]). Gated.
4. SPEC for the contract (the how). Add a new domain spec, or version an existing one — approved specs are immutable, so a change means a new version + changelog entry + a reference to the motivating ADR (→ [[technical-specification]]). Gated.
5. IMPL PLAN for the work (the sequence). Append dependency-ordered atomic tasks with locked done conditions; don't disturb completed milestones (→ [[implementation-plan]]). Gated.
6. STATUS for memory. Log the whole change in the handoff log: what docs changed and why. Not gated — this is live memory.
7. Then build — normal flow resumes: status-tracker picks the new task, git-workflow ships it, independent-verification gates it.

Each gated step waits for confirmation. Converge fast — this is a focused reconciliation, not a re-run of the full kickoff dialogue. If the feature is small and an approved spec already covers it, say so and skip straight to the plan.

Applying Changes — By the Target Document's Rules

Each document has its own discipline; maintenance respects all of them:

Document	How a change is applied	Never
PRD (docs/prd.md)	Extend in place — add features, adjust scope, note the change date	Quietly delete the old scope; leave "why it changed" unexplained
SPEC (docs/spec/*.md)	New version + changelog entry at top + reference to the motivating ADR; or a new domain spec	Mutate an approved contract in place under the implementer
ADR (docs/adr/ADR-*.md)	Append a new ADR; to reverse one, flip the old to Superseded by ADR-NNN and write the replacement	Edit an accepted ADR's body — history stays honest
IMPL PLAN (docs/plans/implementation-plan.md)	Append new atomic tasks; re-sequence only unblocked future work	Rewrite or weaken the done condition of work already verified
AGENTS.md	Update the affected section (conventions, constraints, boundaries)	Let a real convention live only in chat
STATUS (docs/status.md)	Log every doc change in the handoff entry; park deferred drift as an Open Item	Treat a doc change as too small to record

Rules

1. Detect proactively, the moment it happens. Drift surfaced three tasks later is a decision already lost. Flag at the point of divergence.
2. Ask before you change. Permission is mandatory for every fundamental document. Proposing the change is the agent's job; approving it is the user's.
3. Propose at diff altitude. "The auth spec is out of date" is a complaint. "spec/auth.md § 3.2 should change the token TTL from 24h to 1h and add a refresh endpoint" is a proposal.
4. Follow the ripple. One change rarely stays in one doc — a PRD scope bump may need an ADR, a new spec, and plan tasks. Map the full ripple in the proposal.
5. Respect each document's discipline. Append-only ADRs, versioned specs, protected completed tasks. Maintenance never becomes a license to rewrite history.
6. Log it in STATUS. Every applied change lands in the handoff log; every deferred one becomes an Open Item. Nothing falls through.
7. Don't manufacture drift. Cosmetic wording, restating something a spec already covers, or implementation detail below the contract line is not drift. Flag changes of meaning, not noise.

Anti-Patterns (Do Not)

1. Do not silently edit a fundamental doc because the change "seemed obvious." Obvious-to-you is exactly what the permission gate exists to catch.
2. Do not batch a session's worth of drift to the end. By then the reasoning that justified each change is gone from context. Surface each as it appears.
3. Do not jump straight to code on a new feature. No PRD entry, no spec, no plan task means no contract — the chain exists precisely to prevent this.
4. Do not edit an accepted ADR or an approved spec in place. Supersede the ADR; version the spec. The contract must never drift under the implementer.
5. Do not let "not now" mean "forgotten." Deferred drift goes into STATUS Open Items, or it will resurface as a contradiction nobody can explain.
6. Do not relitigate locked decisions while reconciling. If a decision still holds, the doc is current — leave it. Maintenance updates reality; it doesn't reopen settled questions.

Relationship to Other Documents

• Reads the whole chain to locate impact; proposes edits to PRD / SPEC / ADR / IMPL PLAN / AGENTS.md, each gated on user approval.
• Hands off new work to [[status-tracker]] → [[git-workflow]] → [[independent-verification]] once the docs are current.
• Complements [[project-kickoff-prd]] (which seeds the chain for new scope) — this skill keeps that chain true as the project evolves after kickoff.
• The standing order to watch for drift belongs in AGENTS.md's session protocol, so every session inherits it (→ [[agents-md-template]]).