Engineering Docs

Engineering docs

Treat docs as durable, audited deliverables. Cite decisions, archive retired docs, use Australian English and load engineering-writing for substantial prose.

Default homes

Resolve project instructions and existing canonical owners first. The table is a fallback only when project-write authority includes documentation setup. In advisory mode, propose paths without creating them.

| Type | Home | Convention | |---|---|---| | Stories / specs | docs/stories/ or docs/specs/ | NN-slug.md, indexed | | Architecture map | docs/ARCHITECTURE.md | current state; links to ADRs | | Diagrams | owning document or docs/diagrams/ | colocate by default; separate when independently owned, reused or generated | | Runbooks | docs/runbooks/ | numbered steps and verification | | Open-decision register | docs/OPEN_DECISIONS.md | one row per user/owner gate; never auto-answered | | Threat models | docs/threat-models/ | STRIDE/LINDDUN structure | | Rolling state | docs/STATE.md | rules embedded in the file (session skill) | | Archive | docs/archive/ | indexed by its README |

Binding rules

1. Verify a decision ID against its log before citing it.
2. Regenerate generated files; never hand-edit them.
3. Keep numbered directories contiguous and update their index in the same

change.

1. Quote and link frozen legal, compliance or gate wording; do not paraphrase.
2. Anti-bloat: an agent-facing doc past ~15 KB is a split/merge review

signal, not an automatic split. Split when owners, audiences, lifecycles or change rates differ; merge duplicate truths or tiny files always changed together. Keep one canonical owner and make current claim → owner → evidence reachable in at most three hops. Session residue never accumulates in live dirs; use session's context-hygiene pass.

Diagrams

Default to Mermaid in markdown for GitHub and operational docs. Use flowchart for routing, sequenceDiagram for calls, stateDiagram-v2 for lifecycles, erDiagram for schemas and a C4-style flowchart for context.

Place a load-bearing diagram in the document whose explanation it supports when both have the same audience, owner and lifecycle. Use a separate diagram file when it is reused, generated, or maintained as an independent artifact.

Render and visually inspect before commit. Parser success proves syntax, not layout quality:

src="$(pwd)/path/to/owning-document.md"
out="$(mktemp -d)"
(cd "$out" && mmdc -i "$src" -o check.md)

Keep one conceptual level per diagram. Split overview from detail when return edges distort the main path. Check normal and narrow widths for overlap, clipping, crossings, blank space and unreadable scaling. Apply [diagram-quality.md](references/diagram-quality.md). Use d2-diagrams only when fixed layout or publication quality justifies a rendered asset.

Retirement and archiving

Preserve durable records in the archive and update its index. After an authorised move, repair inbound links and remove a pointer-only file when repository history and the relevant index preserve provenance. Keep a tombstone only while a stable external link or unsupported consumer still requires one. Deleting a substantive record still requires owner authority.

Red flags

• Unverified decision citation.
• Hand-edited generated output.
• Deleted history or an unindexed new document.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mblauberg
• Source: mblauberg/provenant
• License: MIT

Install and usage instructions live in the source repository linked above.