Skip to content

Documentation Lifecycle Convention

When to use: Introducing or retrofitting a clear docs structure in repositories where agent-generated markdown can blur what is provisional versus current truth.

Instructions

Goal

Separate stable documentation from interim planning and delivery notes so humans and agents can quickly determine:

  1. whether a document is current truth or temporary
  2. where implementation and docs must stay in sync
  3. whether a doc has been recently reconciled

Repository layout baseline

Use this baseline under docs/:

docs/
  core/
    architecture/
    operations/
    kb/
  planning/
  wip/
  archive/

Rules:

  • docs/core/ is grounded truth: stable architecture, operations, standards, and other docs that describe the repository as it actually is now.
  • docs/core/kb/ is durable knowledge content, not a temporary wiki scratchpad.
  • docs/planning/ is future-state intent (proposals before implementation).
  • docs/wip/ is current execution material (in-flight implementation notes).
  • docs/archive/ is historical context for completed, superseded, or abandoned material.

Promotion flow:

  1. planning -> wip when implementation starts.
  2. wip -> core when the outcome is implemented and verified as current truth.
  3. planning or wip -> archive if superseded or abandoned.

Document metadata header

Add YAML frontmatter to docs that describe implementation behaviour:

---
doc_classification: core
status: current
last_reviewed: 2026-05-28
owned_by: platform-team
code_paths:
  - src/sync/heartbeat.ts
  - src/sync/scheduler.ts
related_docs:
  - docs/core/architecture/communication-flows.md
---

Field conventions

The two lifecycle fields describe different axes and are intentionally kept separate:

  • doc_classification: where the doc lives — its tier. One of core, planning, wip, archive. This mirrors the folder the file sits in.
  • status: the doc's actual condition — one of current, proposed, superseded, abandoned. This is its truth-state, independent of location.

The two are correlated but not identical, which is the point: when they disagree that is a signal, not an error. A file with doc_classification: core but status: superseded is current-tier content that has gone stale and needs re-filing. archive also splits into superseded vs abandoned, which doc_classification alone cannot express.

Remaining fields:

  • last_reviewed: ISO date (YYYY-MM-DD) updated when doc content is checked against implementation reality. Bump it for content reconciliation, not for metadata-only churn (moves, frontmatter edits, typo fixes).
  • owned_by: team or role responsible for doc accuracy.
  • code_paths: repo-relative implementation files or folders described by this document.
  • related_docs: repo-relative links to associated docs.

doc_classification should normally match where the file lives. If a file moves lifecycle stage, update both the path and the frontmatter (and reconcile status).

Code-to-doc linkage contract

For source files implementing documented behaviour, add a top-of-file @docs: block (or equivalent docstring) with repo-relative doc paths. Use the docs-implementation-tagging skill format for the block style.

Minimum contract:

  • durable behaviour docs include code_paths
  • implementation files with external behaviour claims include @docs:
  • paths in code_paths, related_docs, and @docs: all resolve

Review and completion checks

At end of any change that affects behaviour:

  1. verify code still matches linked docs
  2. update docs and bump last_reviewed where needed
  3. verify each changed doc is in the correct lifecycle folder:
  4. planning for proposals
  5. wip for in-flight implementation
  6. core for current truth
  7. archive for historical state
  8. verify moved/renamed doc paths are updated in:
  9. other docs (related_docs)
  10. source @docs: entries
  11. repository indexes or contributor docs

Retrofit rollout for existing repositories

  1. Create docs/core/, docs/core/kb/, docs/planning/, docs/wip/, docs/archive/.
  2. Classify and move existing docs by lifecycle state.
  3. Add metadata headers to high-signal docs first (architecture, API, runbooks, operations).
  4. Add @docs: tags to implementation files those docs describe.
  5. Add checks for link validity and metadata path correctness.
  6. Add a short policy section in AGENTS.md or contributor docs so review expectations are explicit.

CI and pre-commit automation options

Use complementary checks:

  • lychee (or similar) for markdown link validity (internal and external).
  • remark-lint + remark-validate-links for markdown and link hygiene.
  • a custom metadata check script that verifies:
  • doc_classification aligns with folder path
  • status is one of the allowed values
  • each code_paths entry exists
  • each related_docs entry exists
  • each @docs: file reference exists

gray-matter is useful inside that custom script to parse and validate frontmatter reliably; it does not replace link checking.

Start CI in warning mode if legacy debt is high, then move to blocking mode once the baseline is clean.

References

Troubleshooting

Symptom Likely cause Fix
Team cannot tell if a doc is final Lifecycle folders and frontmatter are inconsistent Move the doc to the correct folder and align doc_classification/status
Completed work still appears in active docs wip docs were not promoted or archived Promote stable outcomes into core; move obsolete notes to archive
Code changes land without doc updates code_paths and @docs: contract not checked in review Add PR checklist and automate path checks
Links break after file moves Path updates were partial Run link/path checks and update related_docs, @docs:, and indexes together