Situation: You are about to compose any markdown document — worklog, README, spec, methodology, error-pattern record, or ticket — where both human cognitive load and downstream AI token consumption matter.

Before You Start: Identify Document Type

Different document types have different readers, lifespans, and structural demands. Pick the type first; the rest of this reference applies the five compositional principles to each.

Two rules follow from the table:

1. High-volatility documents (worklog, ticket) must stay append-only; rewriting history breaks the record.
2. Permanent documents (methodology, error-pattern, spec) must be distilled; every paragraph earns its keep.

Principle 1 — Atomization × Documents: Section granularity and when to split

Core question

How much content belongs in a single file, and when do you cut?

Decision table

Split heuristics by document type

• Worklog: Stays single per version. Append chronologically. Do not split by Wave unless the file exceeds ~2000 lines (rare).
• README: Always single file per directory. Route outward via links; do not fork README for sub-topics.
• Spec: Split by use case (one UC per file). Do not bundle multiple UCs for “efficiency”.
• Methodology: One methodology per file. If a second concept appears, it is a second methodology.
• Error-pattern: One pattern per file. Multiple root causes → multiple files, cross-linked.
• Ticket: One ticket per file is the atomic contract. Splitting a ticket means creating child tickets, not subdividing the file.

Anti-patterns

Principle 2 — Indexing × Documents: MOC, directory structure, cross-document references

Core question

Given many atomic documents, how does a reader find the right one?

Three indexing mechanisms

1. Directory layout — the physical grouping implies a taxonomy. Keep depths shallow (≤ 3 levels); deeper trees hide documents.
2. MOC (Map of Content) — a landing document that lists siblings with one-line summaries. Every directory with more than 5 documents earns an MOC (README.md or index.md).
3. Inline cross-reference — when one document must point to another, use a stable relative path and describe why the reader should click, not just that they can.

Cross-reference format

A reference without intent (“see X.md”) is a broken signpost. Always say what the reader gains by clicking.

Reference anchors: semantic titles, not positional numbers

引用另一個章節 / 階段 / 條列項時、錨點用語意標題、不用位置編號（「見核心問題」、不是「見 Stage 3」；「如『底線告知協議』所述」、不是「如第 4 點」）。編號是結構排列的 derivation — 插入或搬移一個單位、後續編號全部位移、引用句字面完好、語意卻 silent 指向錯的內容（misdirected 比 broken link 難偵測：連結斷掉會報錯、編號錯位會成功解析到錯的東西）。對應要求：每個結構單位的標題要承載核心意義（「Stage 3：核心問題」、編號只是排序前綴）、引用一律取語意半邊。例外是發布方凍結的編號（RFC 段號、法條）— 那是 fact、可引用。重排結構的 commit 要全 repo 掃編號式引用。完整判準與失效案例見 reference-by-semantic-title-not-number。

標題要能當穩定錨、名稱本身得先是純 fact：集合命名（問題清單 / 階段序列 / 原則組）只承載角色與層級、把成員數量留給清單呈現 —「核心七問」加一問就在每個複製過名稱的地方失真、「核心問題」承受任意成員增減。判準與邊界（外部凍結品牌 / 概念閾值可留數字）見 name-collections-by-role-not-count。

Indexing by document type

• Worklog: The worklog itself is an index of tickets. Each ticket row points into a detail file.
• README: Is the MOC for its directory. Must list every sibling one-line.
• Spec: Indexed by use case ID. Use cases form a flat catalogue; requirements nest under them.
• Methodology: Indexed by methodologies/README.md. Methodologies do not cross-reference methodologies-of-methodologies; keep one hop deep.
• Error-pattern: Indexed by a stable ID prefix scheme (e.g. category abbreviation + running number). The ID itself is the index key.
• Ticket: Indexed by worklog + ticket track list. CLI is the primary index, not a markdown TOC.

Anti-patterns

Principle 3 — Explicit Intent & Business Logic × Documents: Inverted pyramid, spec vs process

Core question

How do you make the point land in the first paragraph — and how do you separate “what the rules are” from “how we got here”?

The inverted pyramid

Put the conclusion first. A reader who stops after the opening paragraph should still leave with the main takeaway.

Spec vs process record — a mandatory split

Rule: Never mix the two in one document. A spec paragraph written in past tense is a process note; move it to worklog. A worklog entry that begins “the system must” is a spec fragment; promote it.

Business logic, not syntax translation

Documents that touch business concepts must describe the why, not the what of the syntax.

Rule: if the sentence describes code mechanics a compiler already enforces, delete it and write the business reason instead.

Anti-patterns

Principle 4 — Searchability × Documents: Titles, frontmatter, grep-friendly structure

Core question

When a human or AI greps for a concept, does the right document surface, and does the right section surface within it?

Title conventions

Heading conventions

• Every H2 heading contains a concept keyword that a reader would actually search for (“Split heuristics”, not “More details”).
• Avoid generic headings: “Overview”, “Introduction”, “Details”, “Notes”. They produce grep hits on every document.
• Prefer question-form or imperative headings: “When to split”, “How to cite a sibling doc”.

YAML frontmatter

Frontmatter is the most grep-friendly slice of a document. Use it for:

Frontmatter must be machine-parseable. Never include narrative text in values; keep values atomic (ID strings, statuses, dates).

Grep-friendly body conventions

• Put the keyword in the same line as the assertion: “Worklog must be append-only” (not “It must be append-only” on its own line).
• When listing rules, repeat the subject: every row of a rule table should contain the rule’s noun, not rely on column headers alone.
• Use separators (→, :, |) consistently so regex-based tooling can parse structure.

Anti-patterns

Principle 5 — Field Design × Documents: Structural templates by type

Core question

What sections must a document of type X contain, and how do those sections differ in angle?

Each field in a template exists to answer a specific question. Two fields answering the same question are a bug.

Worklog template

Append-only sections: 進度追蹤, 技術筆記. Mutable: Phase tables (statuses flip).

README template

Spec template

Angles must not overlap: preconditions are entry guards, not flows; acceptance criteria are pass/fail, not behaviour descriptions.

Methodology template (from methodology-writing core)

Length discipline: keep only judgment criteria and core rules in the methodology; move operational flows, code examples, and error-handling to a SKILL. Length is whatever makes the criteria explicit and directly applicable — it is not bounded by reading time.

Error-pattern template

Each section answers a different question. Symptom is not cause; cause is not prevention.

Ticket template

Ticket fields are extensively defined elsewhere (designing-fields.md). Key angles here:

Overlap between what and why is the most common ticket bug. Keep them at different angles.

Anti-patterns

Worklog-Specific Extensions (distilled from worklog-writing methodology)

Tool compatibility

Markdown table cells in worklogs must not contain multi-byte status emoji (⏳, [SYNC], [FAIL], etc.). CLI parsers have hit Rust panics on char-boundary issues. Use plain text:

Emoji is allowed outside table cells (in prose headings).

Five events that must be logged

Worklog records decisions and milestones, not execution detail (detail lives in tickets).

Prefer bullet list over table: easier to append, diff-friendly, still readable past 20 entries.

Narrative summary as legal alternative

When a session closes many tickets in a sprint, per-ticket bullets become impractical. A narrative summary covering the ticket ID range + key outcomes is acceptable:

1### {date}: {theme} 衝刺
2- {ticket-range} 可觀測性修復：全域錯誤處理、靜默失敗路徑消除
3- {ticket-range} 審查結論全部修復：AppLogger 遷移、ErrorHandler 防護

Priority order: per-ticket bullets > narrative summary > no record. Sprint-style summary is the fallback, not the default.

Methodology-Specific Extensions (distilled from methodology-writing)

Reader is an expert

Readers already know the content; they just forgot a detail. Your job is to help them recall, not to teach.

Forbidden phrasings:

• “You should…” (condescending)
• “Remember that…” (teaching)
• “The lesson here is…” (sermonising)

Replace with description of what was done and what was observed.

Length discipline: criteria stay, flows leave

A methodology carries the framework’s judgment criteria and core rules, written explicitly enough for a reader — including an AI applying them during development — to use directly. Operational detail, not the criteria themselves, belongs in a SKILL or reference.

If rewriting an old verbose methodology, the test is:

The methodology keeps its judgment criteria explicit and applicable; the SKILL holds the full walk-through. Never compress the criteria themselves to save length.

Experience-sharing variant (six guidelines)

When the document is an experience-sharing write-up (not a methodology), six additional rules apply:

1. Share experience, do not teach. No “you should” / “remember to”.
2. State facts, do not dramatise. Avoid “totally blew up”, “I was lazy”, etc.
3. Use functional description, not function names, in prose.
4. Not every problem is your own fault — don’t self-blame for library bugs.
5. Every case needs discovery → diagnosis → fix, not just “problem was X, fixed as Y”.
6. Avoid specific product/SDK names in prose; describe the structural problem.

Self-Validation Checklist (run before committing the document)

• Document type identified, and structure matches the type’s template
• Opening paragraph states the conclusion / rule (inverted pyramid)
• Spec content contains no process narrative; process content is not dressed as spec
• No section duplicates another section’s angle (no double-answered questions)
• Cross-references state why to click, not just where to click
• No reference to a ticket ID / commit hash / worklog path inside a stable document (spec / methodology / error-pattern)
• Table cells in worklogs contain plain-text status, not emoji
• File length is either atomic (< ~500 lines) or the body holds a single concept despite length
• Headings contain searchable concept keywords (no generic “Overview” / “Details”)
• Frontmatter fields, if present, are atomic and machine-parseable

Multi-pass Re-read（refinement protocol）

The checklist above is a single-frame final sweep — not multi-pass. Multi-pass requires each round to use a different frame to catch errors at different layers (literal-interception-vs-behavioral-refinement / writing-multi-pass-review).

For documents (worklog / spec / methodology / error-pattern):

Skip rules: quick worklog notes can skip rounds 4-7’; stable specs / methodology should run all rounds twice.

Quick Routing by Scenario