Documentation maintenance

中文 · Terms used

Keep NMG documentation useful as an interface between users, Agents, design, and implementation. Use the documentation index to resolve ownership when it is unclear; read its CI contract when changing checks and its bilingual policy when changing paired content.

Before drafting, reorganizing, condensing or publishing reader-facing text, apply the reader-oriented writing and review standard. It owns reader-task structure, controlled-language-inspired expression and semantic acceptance. Structural checks do not replace that review.

Content that can be read locally

Use the writing standard's local-reading criteria for section boundaries, required versus background links, source references and inventory duplication. Its review procedure checks incoming references and the meaning of their targets after a move.

The root bootstrap owns the stable discovery protocol. Changing commands and setup belong at their operational owner; the documentation index resolves which surface owns a fact. This Skill routes that work rather than maintaining another copy of the writing criteria.

Meta-rule: NMG's own rules are governed

Rules and decisions about NMG are themselves NMG artifacts and follow the same discipline as the code they govern. This is the rule that makes every other rule change deliberate rather than silent.

• A rule change is a non-trivial change. Adding, weakening, or moving a standing rule, Skill convention, or decision convention is itself a decision: state what changed, what it replaces or beats (alternatives), and why, in the owning record, in the same change. Never change a rule silently inside a code edit, a commit body, or a prose aside.
• One home per rule. State each rule once at its owner — an AGENTS.md standing order, the owning Skill, or a decision record — and link elsewhere by relative Markdown path. If the same rule appears twice, delete the copy and link the owner.
• Prefer a gate to a reminder. When a rule must be followed in many places or protected against drift, turn it into one mechanical check at its owner rather than restating it. A rule restated everywhere is a rule enforced nowhere.
• Keep a new rule reversible and grounded. Prefer a documented convention over entrenched machinery. A rule that needs new space, or replaces an existing rule, records what it costs and what it beat.
• Most docs need no approval. Approval attaches to normative content that no check can decide, not to the docs/** prefix. The test is if this file were wrong, what would fail? — a check means the check approves, nothing means the edit is free. Where a doc has a checkable property and no check yet, write the check instead of asking. See the approval tiers; a record whose substance the user already agreed goes straight into implemented/ with **Approved:** explicit, and is never parked in proposed/.

One home per fact and the slop checklist

Durable prose follows one home per fact: state each fact once in the surface that owns it (Workflow step 3 lists them) and link elsewhere; if a fact appears twice, delete the copy and link the owner. Keep docs and rules lean because generative Agents read them every session.

Hunt these in any doc you write or touch; a rule restated in two homes, or a fact narrated as history, is drift waiting to happen:

• The same rule or fact in more than one home. Keep one; link the rest.
• Change-history narration in durable prose: "previously / now / no longer / renamed / was moved", or PR/commit positions. State the current fact; put the change story in the commit, decision, or experiment, not in design prose.
• Implementation-status annotations ("implemented! / future: …"). The code and package manifests carry status; it rots in prose.
• Hand-restated catalogs, JSDoc, or inventories of tests/packages when source or a generator is authoritative.
• Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, or rejected local alternatives restated as prose. Keep the resulting contract or rationale; drop the path used to derive it.
• Spec-speak in an implemented decision or note: "should / Proposal / Plan / Acceptance criteria". An implemented record states what is, in the present tense.
• Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve it for the clause that changes behavior.

Headers are a closed vocabulary. A record's header block — the lines before its first ## — carries only the fields its surface documents, and docs:check rejects anything else. A decision's set is in decisions/README.md. A design carries **Status:** draft | current | superseded (absent means current) plus at most Created, Updated, Authority, Related, Supersedes, Superseded by; a superseded design lives in docs/design/archived/ and names its successor. Free-form status sentences are what this replaced.

Workflow

1. Classify the change before writing. Decide whether it changes normative behavior, records rationale, reports evidence, changes completion status, adds unresolved work, or changes user instructions.
2. Find the existing owner. Search titles and relevant terms. When a name could be an alias or have several meanings, use the existing terminology lookup in the relevant scope, then widen a miss rather than declaring absence. Update the owning document instead of creating another summary. Git preserves editing history. If a detail remains only in Git and would be expensive to rediscover, leave a commit or decision link in the relevant audit or decision document.
3. Update the right surface.
   • Behavior and architecture: docs/design/design.md and, when useful, one owning topic design.
   • Rationale and alternatives: a record under docs/decisions/.
   • Measured results: docs/experiments/; never promote a result into a design claim without an explicit decision.
   • Failure narrative: a numbered record under docs/postmortem/ when its triage rule fires, with its index row; when a class is promotable, its consumption rules decide which owner the rule lands in.
   • Current implementation evidence: docs/design/completion-audit.md.
   • Unresolved action only: docs/design/temporary-todo.md; remove it when done.
   • User or Agent operation: README, Skill, or operating guide that owns it.
4. Handle supersession explicitly. Refine an existing owner when possible. Cross-link old and new decisions; archive a fully superseded decision, or state the remaining scope when supersession is partial.
5. Maintain the complete document group. Apply the documentation index's bilingual scope and three-artifact contract. Review the English text, Chinese text and shared terminology together; neither a language variant nor its term-use file is a separate specification.
6. Keep status honest. Separate implemented, validated, enabled, default, deferred, and out-of-scope states. A passing controlled test is not natural product evidence; an experiment result is not a default-policy decision.
7. Verify. Apply the CI contract, then run npm run docs:check and the code or evaluation checks needed by the underlying change. Review warnings rather than hiding them. If automation policy must change, update the contract first and the verifier second.

Commit lineage

Git remains the exhaustive changelog. Add commit information to an existing owner only when it helps a later Agent rediscover an architectural origin, understand a hardening fix, locate validation evidence, or avoid retrying a superseded design.

• Put a compact Implementation lineage section in the owning topic document.
• Group related commits; do not narrate every intermediate patch.
• Mark entries as Introduced, Hardened, Validated, or Superseded.
• A validation commit proves only what its evidence measured; it does not imply default activation.
• For supersession, name both the old and replacement commit or decision.
• Leave formatting, generated artifacts, dependency refreshes, ordinary tests, merges, and easy-to-rediscover implementation details in Git.
• Use the curated lineage index to find owners; do not turn it into a duplicate commit database.

Boundaries

• Do not copy project facts into this Skill. Link their canonical owner.
• Do not use temporary-todo.md as a changelog or completed-work archive.
• Do not make every ordinary code change a decision record. Create one when the rationale, alternatives, compatibility, or consequences will matter later.
• Do not make every fixed bug a post-mortem. The tier's triage rule decides which failures earn a record.
• Report missing document-group members as unfinished work under the owning bilingual policy; a green structural check does not settle that work.
• Do not rewrite unrelated experiment reports while reorganizing documentation.