documentation-sync

Documentation Sync

Keep each documentation projection useful without creating a second source of component truth.

Source Direction

textual SysML/KPAR -> generated component, application, and manifest views

Hand-authored Markdown may explain rationale, tutorials, operations, evolution, or unresolved questions. It must not independently restate normative action signatures, state, dependencies, or invariants.

Workflow

1. Inventory canonical model, implementation, generated, documentation, and skill changes from version-control status and diffs. Include untracked files; an ordinary diff omits newly added documentation and can hide an incomplete sync.
2. Run just model-render for parser-backed inventories, model-derived views, conformance objectives, and manifests.
3. Review generated component pages for actions, signatures/defaults, typed failures, state access, required constraints, asserted satisfiers, native action calls, invariants, and subject-compatible verification objectives. A fresh but semantically incomplete projection fails sync.
4. When an accepted source or prior model exists, confirm the projection preserves its public meaning unless an explicit contract change was approved.
5. Before deleting predecessor documentation, classify its remaining content: contractual facts move to the model; rationale, tutorials, operations, evolution notes, and unresolved questions move to a clearly non-normative home; obsolete statements cite the current model decision that supersedes them. Confirm implementation discoveries are either modeled intentionally or recorded as realization drift.
6. When package ownership or imports change, update library/application indexes and confirm the generated dependency direction still matches the canonical model.
7. Update only hand-authored documents whose readers need new context or workflow guidance.
8. Update AGENTS when repository-wide authoring or realization rules change.
9. Update reusable skills only for generally applicable workflow improvements; keep product names, project findings, and repository-specific package maps in repository guidance.
10. Update skill UI metadata when a skill's purpose changes.
11. Confirm packaged products validate independently and downstream products consume packaged dependencies, then run just skills-check, just model-check, local-link and documentation- guidance checks when available, and the narrowest relevant repository checks.