provna

Propagate a settled decision (e.g. a pinned-technology choice) consistently across the whole docs tree — the canonical docs, the relevant ADRs, and every stale terminology reference — and verify it. USE FOR: rippling an already-made decision so the tree stays self-consistent after a tech choice, a substrate swap, or a scope refinement. DO NOT USE FOR: recording the decision in the first place (use ../write-adr/SKILL.md) or reversing one (use ../supersede-adr/SKILL.md).

Deeply review a competitor or reference (an open-source repo or a product) and write a structured, evidence-cited teardown plus a Provna-implications synthesis INTO docs/private/. USE FOR: a code-level or doc-level intelligence dossier on a rival/reference (e.g. an agent- governance toolkit, an IFC engine, a durable-execution substrate) mapped to Provna's four pillars. DO NOT USE FOR: writing public docs (use ../write-doc/SKILL.md) — teardowns are internal and public docs never reference them.

The consistency gate for the docs tree — run before finishing ANY documentation change. Fast and mostly machine: no docs/private leak, English-only public docs, relative links resolve, ASCII-safe Mermaid, single H1 / no front-matter; then a short list of judgment checks the script cannot make. USE FOR: a pass/fail self-gate after editing docs. DO NOT USE FOR: a deep adversarial review (use ../review-docs/SKILL.md or the provna-docs-reviewer agent).

The primary end-to-end flow for delivering a non-trivial Provna roadmap workstream — scope, align, inspect, plan, do the work, gate it, update the canonical docs, commit, and hand off to review. USE FOR: a Phase-0 PoC or a substantial planning/spec/deliverable from docs/roadmap/current.md (and, once the monorepo lands, a feature/fix in the data-plane or control-plane). DO NOT USE FOR: a one-line edit, recording a decision (use write-adr), a quick docs gate (use docs-check), or reviewing someone else's work (use review-docs).

Deep, multi-dimension adversarial review of a docs change or the whole tree — terminology, quantitative consistency, technical accuracy vs the pinned decisions, cross-references, scope discipline, the no-docs/private rule, honesty, and conventions — with each candidate finding verified before it is reported. USE FOR: a thorough review before a milestone or after a large change. DO NOT USE FOR: the quick pass/fail gate (use ../docs-check/SKILL.md) or writing/fixing docs (this produces findings, it does not edit).

Reverse or replace an Accepted decision by writing a NEW ADR and marking the old one Superseded — ADRs are append-only and history is never rewritten. USE FOR: changing a decision that an Accepted ADR already records (a substrate swap, a reversed scope call, a new pinned technology that displaces an old one). DO NOT USE FOR: recording a brand-new decision (use ../write-adr/SKILL.md), or merely refining wording/propagating an unchanged decision across docs (use ../apply-decision/SKILL.md).

Author a new Architecture Decision Record in docs/decisions/ using Provna's condensed-MADR form and register it in the index. USE FOR: recording a settled non-trivial architectural / product / process / tech decision, pinning a stack or seam choice, or justifying a new core dependency. DO NOT USE FOR: reversing an Accepted decision (use ../supersede-adr/SKILL.md), propagating an already-recorded decision across the tree (use ../apply-decision/SKILL.md), or writing a normal doc (use ../write-doc/SKILL.md).

Add or update a page in the docs/ tree (architecture, business, compliance, roadmap, standards, a pillar, the glossary) so it obeys Provna's conventions and the one-canonical-home rule. USE FOR: writing a new public doc, restructuring or expanding an existing one, adding a Mermaid-first architecture page. DO NOT USE FOR: recording a decision (use ../write-adr/SKILL.md), propagating a settled decision tree-wide (use ../apply-decision/SKILL.md), or writing internal competitive analysis (use ../competitive-teardown/SKILL.md, which targets docs/private/).