Writing Documents — Situational Reference

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

The line counts in this table decide sections versus files within one concept only. Whether to split at all is decided by responsibility: a 600-line parameter reference can be one responsibility, an 80-line README can hold four. Count responsibilities from history — git log --follow --no-merges --format='%h %s' -- <file-path>, group the commit subjects by topic, the number of groups is the number of responsibilities. See change-history-counts-a-documents-responsibilities.

Before adding a section to an existing document

A document gains a second responsibility in the edit that adds a section, and each such edit looks reasonable on its own. Before adding, ask: is this section’s reason to change one of the reasons this file already has — read the existing reasons from its history, not from its title. If not, find the file that owns that reason; only if none exists open a new file and leave a one-line link here. Also ask whether the section would sit better under another category of the same collection: a document’s scope is the intersection of its title and its category, and titles often omit what the category already constrains (see section-scope-is-bounded-by-the-category-too). Rule documents that accumulate (project conventions, agent instructions, skill files) need this check most.

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.

Supplementary notes live next to their parent command

操作型文件裡的先備知識（為什麼這個參數值得用）與環境陷阱（某個平台上同一條指令會靜默失敗）跟在它們所屬的指令旁邊——表格的用途欄、或緊跟指令的那一段。判斷問句是「讀者在讀到哪個位置時會需要這段資訊」，答案指向的位置就是它該放的地方。遊離的形態是參數的理由獨立成段（讀者掃表格時跳過它）、環境陷阱跟在無關的段落後面；成因是寫的時候想到什麼補什麼，而文件的讀者掃描式閱讀、不照順序讀每一段。見 supplementary-knowledge-follows-its-parent-concept。

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

文件被別人照著執行時另有一條：rule-must-point-at-something-openable——那裡給「照這一條工作，第一個動作是打開什麼」這個判斷標準，與三種失效形態各自的修法。

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.

Operation sentences: fill four slots before writing the sentence

文件裡描述操作的每一句由四個槽位組成——動作者（人、腳本、工具、系統元件）、動詞、受詞（動詞在這個領域裡能作用的對象）、結果——外加量詞範圍一格，每格填的都是這個領域裡實際存在的東西。三條判定：動作者格填了指令片段（「-G 16M 放大緩衝區」）→ 換成人或系統元件；受詞格的名詞在領域外（「執行」的受詞填「字」）→ 換成領域內的名詞；量詞（完全、任何、所有）的範圍沒在句內具名 → 補範圍。判定者不代填槽位——單位要寫在句子裡，從上下文推得出來不算。worklog 與操作指引是這一類句子密度最高的文件；寫的跟審的是同一個模型時審查端對它偵測率是零，所以規格放在寫的當下。判斷標準與 before/after 見 command-fragment-as-subject-hides-the-actor 與 spoken-emphasis-is-silent-in-text；教學定位的文件另查開場與教室互動語句（teaching-is-not-lecturing）。

Command operands: the values the reader must change

上一節的判定單位是句子，所以它走到程式碼區塊就停下來——指令沒有主詞也沒有謂語。示範指令另有一條檢查，而規範與操作指引的指令密度最高，所以這一條在這裡比在文章裡更常觸發。

四個位置（工具 / 子命令 / 選項 / 引數）裡引數最需要寫：工具與子命令的名字讀者查得到，選項多半有 --help，而引數的語意常常只有這份文件講得出來（路徑為什麼選在這裡、兩個引數哪個是來源、給不給這個引數會讓指令做不同的事），而且它是讀者唯一要動手改的位置。判斷標準：讀者把這條指令用在自己的環境上要改哪幾個位置，每個位置文件有沒有說過它填什麼。 掃描入口是區塊裡的字面值而不是佔位符——佔位符自帶「這裡要換」的訊號，字面值長得像一個完整可用的答案，稿件上因此看不出缺口。引數的有無改變行為時，兩種形態要並列在同一個程式碼區塊裡、各帶一行註解，文字說明是補充而不是替代。五種形態與修法見 literal-operand-hides-the-change-point。 區塊的排法、註解的分工與參數表的判斷標準在 demonstrating-commands。

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