memory-document

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:

• Thesis: one sentence previewing all sections
• Overview: one paragraph introducing each section
• Mermaid: at least one; complex docs get TD + LR
• MECE: 3–7 sections, no overlap, full coverage
• Ordering stated: ¶1 of each section explains sequence logic
• Paragraph numbering: ¶1, ¶2, ¶3 throughout
• Coherence: thesis matches actual sections

Content:

• DRY: each fact once, §X.Y cross-references elsewhere
• Dense: no filler words, but enough to execute
• Labels: noun titles for continuants, verb titles for occurrents

Ground Truth:

• Primary source in overview
• Section sources attributed
• Inline sources on specific claims
• LLM reasoning flagged
• Code refs have line numbers
• All dates present
• URLs tested