Skip to content
PETROVA

shared/documentation-hierarchy

Documentation hierarchy

Section titled “Documentation hierarchy”

Every petrova-line repo organises docs/ by rank. The rank graph is a DAG declared in front-matter (MR-1); the drift-watcher subagent reads it when adjudicating ambiguity.

Ranks

Section titled “Ranks”
  • docs/north-star/ — load-bearing intent. Outranks the backlog. Cap of ≤3 docs; if a fourth lands, retire one. Every PR and planning conversation opens with: does this serve the north-star? If no, and it isn’t load-bearing infrastructure (auth, storage, deploy, schema, contract), it goes to docs/backlog/frozen/ rather than getting executed.
  • docs/decisions/ — ADR-style decision artefacts. Append-only per MR-7. Filename: YYYY-MM-DD-<slug>.md. Closed decision docs are not edited; they are superseded by a new dated doc.
  • docs/findings/ — diagnostic arcs and incidents. Filename: YYYYMMDD-HHMM-<slug>.md. Findings that warrant a verdict graduate to a decision doc; raw findings stay here.
  • docs/runbooks/ — operator procedures. How to do recurring operations safely.
  • docs/spec/ — SRS, schemas, acceptance corpus. The grounded source for every claim a CLAUDE.md or invariant makes (MR-12).
  • docs/verification/ — traceability matrix. Maps milestones to acceptance criteria to evidence.
  • docs/backlog/ — deferred work. docs/backlog/frozen/ holds items that don’t pass the north-star lens.
  • docs/roles/<role>/outputs/ — per-subagent session logs. Pointer to AGENTS.xml for the roster.

Rank front-matter

Section titled “Rank front-matter”

Every directory’s README.md (and individual docs where useful) declares:

---
rank: <ranks-this-doc-lives-at>
outranks: [<ranks-this-overrides-on-conflict>]
---

The outranks graph is validated as a DAG by the docs-invariants CI workflow. Cycles are rejected.

Anti-patterns

Section titled “Anti-patterns”
  • Subdirectories inside ranked folders. The date prefix already orders decision docs and findings. Subdirectories conflate axes.
  • Cross-rank includes. A backlog item must not be referenced as authoritative in a decision doc. The rank order is load-bearing.
  • “Documentation” without a rank. Loose .md files at repo root (other than README.md, CLAUDE.md, MILESTONES.md, AGENTS.xml, and SECURITY.md) are a smell — pick a rank.