documentation-guidelines

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: documentation-guidelines
description: Create, reorganize, audit, clean up, or update proportionate documentation for monorepos and single-project repositories. Use for documentation architecture, source-of-truth ownership, minimal routing indexes, module or feature docs, API contracts, workflows, runbooks, optional roadmaps and delivery records, documentation-churn reduction, and removing obsolete plans, notes, archives, or stale references that pollute agent context.
---

# Documentation Guidelines

## Goal

Keep documentation discoverable, owned, and proportionate. Update a document
only when the durable source of truth it owns materially changes. Git, pull
requests, tests, and CI already own task-level history and evidence.

Repository instructions override this skill when they are newer or more
specific.

Run this skill in the main conversation. Do not spawn subagents or delegated
workers unless the user is told that delegation can increase usage and
explicitly approves the proposed count and scope. Ask again before expanding
an approved scope.

Read `references/documentation-guidelines.md` when creating a documentation
architecture, using templates, or performing a broad reorganization.

## Documentation Impact Gate

Decide whether docs need to change before editing them.

| Change | Default documentation action |
| :--- | :--- |
| Internal refactor, test-only change, typo, formatting, dependency refresh with no workflow change | No docs update |
| Bug fix that restores already-documented behavior | No docs update |
| Material user-visible behavior or module workflow change | Update one canonical owner doc |
| Public API, schema, event, permission, validation, or cross-repo contract change | Update the contract owner and any affected relationship-map entry; update a consumer doc only for consumer-specific behavior |
| Setup, command, environment, migration, seed, deployment, recovery, or operational change | Update the owning runbook/reference |
| Stable cross-project convention or architecture decision | Update the owning guide or ADR |
| Active planned scope, decision, status, or next slice changes | Update the active task or issue; update a durable roadmap only when the repository intentionally uses one |
| Add, rename, move, archive, or remove a repo/module/feature | Update its one canonical registry and affected router links |
| Significant release, migration, production change, cross-app feature, or explicit handoff | Add a delivery record only if the repository uses them |
| Obsolete plan, handoff note, delivery transcript, redirect, or archive | Move any still-valid fact to its owner, remove stale references, then delete the obsolete file when Git history is sufficient |

Do not create a docs edit merely to prove that docs were reviewed. When no
durable source of truth changed, report that no documentation update was
needed.

## Reading Rule

Use the smallest default context path: repository instructions, one current
progress hub when present, and one owner document. Open a router only when the
owner is unclear. Open maps, ADRs, references, runbooks, delivery records, and
roadmaps only when the task specifically requires their contracts.

Before editing, moving, merging, or deleting documentation:

1. Read every target file completely.
2. Read the nearest routing index needed to identify the owner.
3. Read the canonical owner doc and relationships that can materially affect
   the task.
4. Read consumer docs only when their local behavior may change.
5. If two docs appear duplicated, read both and identify the owner before
   consolidating them.
6. Do not recursively follow every link or require every root, repo, module,
   and feature index for a small,
   already-routed task.
7. Do not infer business rules from filenames, folder names, translated labels,
   or stale summaries.
8. If routing remains ambiguous after reading the available indexes, ask one
   targeted question before editing instead of gue