| name | memory-document |
| description | Write docs like code — Minto pyramid, MECE sections, BFO ontology, Mermaid diagrams, ground truth sources. Applies to any .md file. |
| version | 2.0.0 |
How to Write a Document
Write docs like code. Fractal structure where each level is complete. No redundancy — reference, don't repeat. Every claim has a source.
graph TD
Thesis[Thesis: 1 sentence] --> Overview[Overview: 1 paragraph]
Overview --> Diagrams[Mermaid: TD + LR]
Diagrams --> Sections[MECE Sections 1.0–7.0]
Sections --> Details[¶1, ¶2, ¶3 per section]
Sources[Ground Truth] --> Sections
Sources --> Details
1.0 The Stack
Six rules. Use internal names here for clarity — don't leak them into the actual doc output.
¶1 Minto — top-down. Thesis → overview → sections → details. Reader gets the point before the evidence.
¶2 MECE — sections don't overlap, but cover everything. 3–7 top-level sections. If you can't draw a clean boundary between two sections, merge them.
¶3 BFO — separate what exists (continuants) from what happens (occurrents). TD diagrams for structure, LR diagrams for process. This isn't decoration — it forces you to find the real shape of your content.
¶4 Fractal — each subsection mirrors the whole. Own thesis sentence, own diagram if needed, own numbered paragraphs. Expand only if it earns the depth.
¶5 DRY — each fact once. Cross-reference with §X.Y, don't restate.
¶6 Ground truth — every claim traces to a source. URL, file path, query, session ID, person. No source = no claim. See §4.0.
2.0 Structure
¶1 Thesis — one sentence. Specific outcome with who/what/when. Must preview the MECE sections that follow.
¶2 Overview — one paragraph expanding the thesis. Introduces each major section like a function docstring listing its parameters.
¶3 Mermaid diagrams — go right after the overview, before §1.0. Structure (TD) before process (LR). See §3.0.
¶4 Sections — numbered 1.0, 2.0, 3.0. Subsections 1.1, 1.2. State ordering logic upfront (importance / chronology / dependency). Continuant sections get noun titles, occurrent sections get verb titles.
¶5 Paragraphs — numbered ¶1, ¶2, ¶3 within each section. Order: general → specific, or problem → solution, or setup → action → result.
¶6 Coherence — if thesis says "planning, execution, monitoring", the doc must have all three. No surprise sections, no missing ones.
¶7 Big docs — over ~10 pages, split into linked files with proper relative paths.
3.0 Mermaid Diagrams
Every doc gets at least one diagram. Complex docs need both TD and LR.
¶1 Headers required — every diagram gets a bold header before the code block. Format: **[Specific Description] ([Type] - [Direction]):**. "Skill Package Structure (Continuant - TD)" not "System Structure".
¶2 Continuant (TD/TB) — what exists. Nodes are nouns (Database, API, User). Edges are "contains", "depends on", "is part of". Use for architecture, data models, component trees.
¶3 Occurrent (LR) — what happens. Nodes are verbs or states (Extract, Validate, Deploy). Edges are temporal — "then", "triggers", "flows to". Use for pipelines, workflows, request flows.
¶4 Participation (optional) — how continuants participate in occurrents. User triggers Pipeline which updates Database. TD or LR depending on emphasis.
¶5 Sizing — 5–12 nodes per diagram. More than that, split. Short labels (1–3 words). Label edges only when the relationship isn't obvious.
¶6 Placement — primary diagrams after overview, before §1.0. Section-level diagrams inline where needed. One diagram per abstraction level — deeper sections get smaller, focused diagrams.
¶7 Structure first — when showing both, continuant (TD) before occurrent (LR).
4.0 Ground Truth
Every piece of information traces to its source. No exceptions.
Patterns
¶1 External — **Source:** [Title](URL) (accessed YYYY-MM-DD)
¶2 Code — **Source:** path/to/file.py:123-145 (function calculate_metrics)
¶3 Session — **Generated by:** Claude Code session abc123 by Name (YYYY-MM-DD)
¶4 LLM reasoning — **LLM Analysis:** Based on ¶1 + ¶3 — flag synthesis explicitly, don't present it as source data.
¶5 Query — **Query:** SELECT ... (YYYY-MM-DD) with result and date. Data changes; timestamp matters.
¶6 Human — **Expert input:** Name (Role), discussed YYYY-MM-DD
¶7 Meeting — **Source:** Gong call gong_123456 with Client (YYYY-MM-DD) with key takeaway.
Where to Put It
¶1 Doc-level — primary source right after the thesis in the overview.
¶2 Section-level — at top of section if the whole section comes from one source.
¶3 Inline — next to specific claims: "churn is 12% (Source: SELECT AVG(churn_rate)... 2025-11-10)".
¶4 Mixed — multiple sources in one paragraph, attribute each piece separately.
Rules
- Dates mandatory. Always YYYY-MM-DD.
- URLs must work. Use archive.org if original might vanish.
- Code refs need line numbers or function names, not just file paths.
- "Based on research" is not a source. Name it.
- Synthesis presented as fact is a violation. Flag LLM reasoning.
Checklist
Paste at doc end. Tick before shipping.
Structure:
Content:
Ground Truth:
