kotonoha 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nahisaho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# kotonoha
+
+kotonoha provides `tech-writer`, a GitHub Copilot CLI skill that helps
+structure and polish technical documents. It covers README, design
+docs/ADRs, API reference, PR descriptions/commit messages/issue reports,
+release notes, user manuals/how-to guides, code comments, and Qiita/Zenn
+articles, structured so readers never get lost.
+
+## What tech-writer solves
+
+Technical documents tend to have two separate problems: "is the prose
+natural" and "does the structure have the right amount of information".
+`tech-writer` specializes in the latter, leaving the former (sentence-level
+naturalness, removing "AI smell") to a prose-polishing skill such as
+[natural-japanese](https://github.com/coji/natural-japanese). With both
+installed, lock down the structure with `tech-writer` first, then polish
+Japanese prose with natural-japanese.
+
+## What it does
+
+- Create/review README, design docs/ADRs, API reference, PR
+  descriptions/commit messages/issue reports, release notes, user manuals,
+  code comments, and Qiita/Zenn articles
+- Doctype-specific structure and checklists to guide writing
+- `scripts/lint.py` for mechanical structural checks (heading-level skips,
+  code blocks missing a language tag, leftover placeholders, suspicious
+  links, etc.); pass `--atomic` for commit messages, PR descriptions, issue
+  reports, code comments, and single release-notes entries
+- Markdown as the default format for every doctype, except a commit
+  message body (plain text by convention) and code comments/docstrings
+  (the target programming language's own syntax)
+- Japanese as the primary target language, with English document support
+
+## Setup
+
+### Prerequisites
+
+- GitHub Copilot CLI installed
+- Python 3.9+ if you want to run the lint script (standard library only,
+  no extra install needed)
+
+### Install
+
+Inside this repository, the skill is already placed at
+`.github/skills/tech-writer`, so no extra setup is needed to use it with
+Copilot CLI here.
+
+To use it in another project, copy the `skills/tech-writer` directory into
+that repository's `.github/skills/`, `.claude/skills/`, or your global
+`~/.copilot/skills/`.
+
+```bash
+cp -r skills/tech-writer /path/to/your-repo/.github/skills/tech-writer
+```
+
+## Ask Copilot for the document you need
+
+Just ask for the document type you need in a Copilot CLI session, and it's
+invoked automatically.
+
+- "Write a README", "Review this design doc", "Write the PR description",
+  "Make this how-to guide clearer"
+
+To run a quick structure-only diagnostic:
+
+```bash
+uv run skills/tech-writer/scripts/lint.py --json path/to/document.md
+```
+
+Without `uv`, `python3 skills/tech-writer/scripts/lint.py path/to/document.md`
+works too (standard library only).
+
+## Repository layout
+
+```text
+skills/tech-writer/          # the skill itself
+  SKILL.md                   # skill definition
+  references/                # structure constitution + doctype rules/checklists
+  references/doctypes/       # README, design doc, API docs, PR/issue, release notes, manual, comments, Qiita/Zenn
+  scripts/lint.py            # structural lint script
+  assets/templates/          # skeleton templates for the main doctypes
+.github/skills/tech-writer   # symlink to skills/tech-writer (where Copilot CLI reads it)
+```
+
+## Known limitations
+
+- `scripts/lint.py` only detects structural issues (headings, code blocks,
+  placeholders, links); it does not detect prose naturalness, vocabulary,
+  or rhythm.
+- The doctypes are written mainly with Japanese technical-writing
+  conventions in mind; most of the guidance (especially the commit-message
+  imperative-mood rule) applies directly to English documents as well.
+
+## Acknowledgment
+
+- [natural-japanese](https://github.com/coji/natural-japanese) (MIT
+  License) — the design principle "machines detect, humans (or agents)
+  judge" and "prevent at generation time rather than fix afterward"
+  informed this project's design.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "kotonoha",
+  "version": "0.1.0",
+  "description": "A GitHub Copilot CLI skill for structuring and polishing technical documents.",
+  "license": "MIT",
+  "author": "nahisaho",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nahisaho/kotonoha.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nahisaho/kotonoha/issues"
+  },
+  "homepage": "https://github.com/nahisaho/kotonoha#readme",
+  "keywords": [
+    "copilot",
+    "github-copilot",
+    "skill",
+    "technical-writing",
+    "documentation",
+    "markdown"
+  ],
+  "files": [
+    "skills/"
+  ]
+}

package/skills/tech-writer/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: tech-writer
+description: >-
+  Helps structure and polish technical documents: README, design docs/ADRs,
+  API reference, PR descriptions/commit messages/issue reports, release
+  notes/CHANGELOG, user manuals/how-to guides, code comments/docstrings, and
+  Qiita/Zenn articles. Use for requests like "write a README", "draft a
+  design doc", "write this PR description", "clean up my commit message",
+  "make this how-to guide clearer", "write API docs", "summarize the release
+  notes", "write a Zenn article", "write this up for Qiita", as well as
+  Japanese-language equivalents (「READMEを書いて」「設計ドキュメントを作って」
+  「PRの説明文を書いて」「コミットメッセージを整えて」「手順書を分かりやすくして」
+  「APIドキュメントを整備して」「リリースノートをまとめて」「Zennの記事を書いて」
+  「Qiitaに投稿する記事を書いて」). Especially useful when
+  the request is a bare goal without enough context to start (e.g. "I want
+  to write a README" / "○○を書きたい"), since this skill drives a one
+  question-at-a-time intake before writing. Supports both Japanese and
+  English documents, with Japanese as the primary target for polished,
+  natural phrasing (pairing well with https://github.com/coji/natural-japanese
+  for sentence-level Japanese refinement). Does NOT handle sentence-level
+  naturalness, word choice, or rhythm ("AI smell" removal) — that is the
+  domain of natural-japanese and similar prose-polishing skills. This skill
+  is specific to a document's structure, information completeness, and
+  reader fit.
+license: MIT
+argument-hint: "[write|review|score] [doctype] <target file or request>"
+---
+
+# tech-writer
+
+Structures technical documents so readers reach the information they need
+with the shortest path. Covers README, design docs/ADRs, API reference, PR
+descriptions/commit messages/issue reports, release notes/CHANGELOG, user
+manuals/how-to guides, code comments/docstrings, and Qiita/Zenn articles.
+
+Default format: Markdown for every doctype in this skill, except a git
+commit message body (plain text by convention — light "-" bullets are
+fine, but don't add Markdown headings or fenced code there) and code
+comments/docstrings (the target programming language's own comment/
+docstring syntax). Qiita and Zenn use Markdown with a platform-specific
+YAML frontmatter and a few platform extensions on top — see their doctype
+reference files.
+
+## Division of labor
+
+Document quality splits into two layers: "is the structure right" and "is
+the prose natural and readable". This skill owns the first layer (structure,
+document type conventions, completeness, reader fit). The second layer
+(sentence-level naturalness, removing "AI smell", rhythm) is out of scope and
+belongs to a prose-polishing skill such as [natural-japanese](https://github.com/coji/natural-japanese).
+When both skills are installed, use this skill to lock down the structure
+first, then hand Japanese prose to natural-japanese for polish.
+
+- Rule of thumb: "does removing a heading still make sense?" tests structure
+  (this skill's job). "Does rereading a single sentence change its meaning?"
+  tests prose (not this skill's job).
+- Code comments/docstrings document code itself, but the same
+  structure-and-completeness framing still applies.
+
+## Execution modes
+
+Infer the mode from the argument or the request:
+
+- `write` (default): new document, or restructuring a draft. Runs the full
+  §1–§4 workflow, starting with the intake loop in §1.
+- `review`: structural review of an existing document. Does not rewrite;
+  reports the gap against the doctype checklist (§5).
+- `score`: structure-only quick diagnostic. Runs
+  `scripts/lint.py --json <file>` and summarizes the findings (no rewrite).
+
+If no mode is given, interpret "write/create" requests as `write`,
+"fix/review" requests as `review`, and "how does this look?/diagnose"
+requests as `score`.
+
+## 1. Gather context — one question at a time, then act
+
+Requests are often bare goals ("I want to write a README", "○○を書きたい")
+without enough context to start. Do not front-load a long questionnaire or
+hand the user a checklist to fill in. Instead:
+
+1. **Determine the doctype first**, from the table below. If the request
+   itself doesn't make it clear, that ambiguity is your first question. If
+   the table maps the request to `pr-commit`, resolve the **subtype** —
+   commit message, PR description, bug report, or feature request — as
+   part of this same first question: `references/doctypes/pr-commit.md`
+   gives each a different skeleton and different musts, so don't proceed
+   past this doctype without knowing which one applies. Similarly, a bare
+   "write a tech blog post" request doesn't by itself say Qiita, Zenn, or
+   neither — ask which platform (or "no platform, just a plain document")
+   as part of this same first question.
+2. Open the matching reference file and note its target reader and any
+   "settle before writing" items. Combined with the general musts below,
+   this is your information checklist — but never show it to the user as a
+   form.
+3. **Ask exactly one question at a time**: pick the single most
+   information-gaining missing item, ask only that, and wait for the
+   answer before asking the next one. Never batch multiple questions into
+   one message.
+4. Stop asking once you have, at minimum: (a) the reader, (b) the
+   one-sentence outcome the reader should reach after reading, (c) the
+   doctype (and subtype, for `pr-commit`), and (d) any doctype-specific
+   musts (e.g. the decision and alternatives for a design doc, the
+   prior-knowledge floor for a user manual, breaking-change status for
+   release notes, the related issue for a PR description or bug report).
+5. **A "don't know" / "not applicable" / "no ticket for this" answer
+   satisfies a must — it is not a reason to keep asking.** Ask that must
+   at most once; if the answer is a non-answer, record it as a stated
+   assumption or an open question inside the document itself (design docs
+   already have an Open Questions section for this; for others, add a
+   one-line note) and move on.
+6. **Once complete, do not ask the user to compose anything.** Synthesize
+   the gathered answers into the best possible generation approach yourself
+   and immediately continue into §2–§4 in the same turn to produce the
+   document. Skip further confirmation unless the doctype is release-facing
+   and consequential (e.g. a public release note with breaking changes) or
+   the user explicitly asked to see a plan first.
+7. If the user already volunteered some of this information in the initial
+   request, skip the corresponding question — don't re-ask what's already
+   known.
+
+| Request | doctype | reference file |
+|---|---|---|
+| README / project overview | readme | `references/doctypes/readme.md` |
+| Design doc / ADR / RFC | design-doc | `references/doctypes/design-doc.md` |
+| API reference | api-docs | `references/doctypes/api-docs.md` |
+| PR description / commit message / issue report | pr-commit | `references/doctypes/pr-commit.md` |
+| Release notes / CHANGELOG | release-notes | `references/doctypes/release-notes.md` |
+| User manual / how-to guide / tutorial | user-manual | `references/doctypes/user-manual.md` |
+| Code comments / docstrings | code-comments | `references/doctypes/code-comments.md` |
+| Zenn article | zenn | `references/doctypes/zenn.md` |
+| Qiita article | qiita | `references/doctypes/qiita.md` |
+
+For technical documents that don't fit any of these, apply only the general
+principles in `references/style-constitution.md`, using the same
+one-question-at-a-time intake for reader and outcome.
+
+## 2. Outline first for long documents
+
+For documents likely to run long — design docs/ADRs, user manuals with
+multiple steps, API references covering several endpoints, or anything the
+user calls "long"/"detailed"/"comprehensive" — draft a table of contents
+(heading outline) before writing any body prose.
+
+1. Build the heading outline from the reader and outcome gathered in §1 and
+   the doctype's recommended skeleton (in its reference file).
+2. **Review the outline from the reader's point of view before writing
+   further**: read only the headings, in order, as the reader identified in
+   §1 would. Check whether they can predict what they'll learn from each
+   section, whether the order matches how they'd naturally look for that
+   information, and whether following the outline gets them to the
+   §1 outcome. Reorder, merge, or split headings if not — this is cheaper
+   to fix in outline form than after the prose is written.
+3. Only once the outline holds up under that reader-perspective read-through
+   should you write the body, section by section.
+
+Skip this step for inherently short, atomic artifacts (a single commit
+message, a short PR description, one new entry appended to an existing
+release-notes/CHANGELOG file, a code comment/docstring) and draft directly
+under §3 — see the scope note at the top of
+`references/style-constitution.md`. This exception is about a single
+*entry*, not the release-notes/CHANGELOG document as a whole: a CHANGELOG
+being drafted or restructured from scratch is still a living, multi-section
+document and needs the outline step below.
+
+## 3. Write — under the structure constitution
+
+For living, multi-section documents (README, design doc, API reference,
+release notes, user manual, Zenn/Qiita article), write under the 8 rules
+in `references/style-constitution.md`. Summary: state "what this is" and
+"the outcome for the reader" in the first three lines; make headings
+labels that preview content (not "Overview", but "Overview of what");
+order steps as executed and put prerequisites before the steps; one
+action per numbered step; put a concrete example or number right after
+any abstract term; keep code examples minimal and runnable, marking
+omissions explicitly; disclose known limitations and unsupported cases
+instead of hiding them; and keep a last-updated date or target version
+where staleness is a real risk. For Zenn/Qiita, rule 1's "first three
+lines" maps to the frontmatter `title` plus the lead paragraph right
+after it — see their doctype reference files for why there's no in-body
+'#' title.
+
+For atomic artifacts (commit messages, PR descriptions, issue reports,
+code comments/docstrings, a single entry appended to an existing
+release-notes/CHANGELOG file), follow their own skeleton in
+`references/doctypes/pr-commit.md`, `references/doctypes/code-comments.md`,
+or `references/doctypes/release-notes.md` instead — see the scope note in
+`references/style-constitution.md` for why the 8 rules don't apply
+verbatim there.
+
+Sentence-level concerns — keeping individual sentences concise, avoiding
+double negatives, not dropping the subject, and general naturalness — are
+out of this skill's scope regardless of doctype. When natural-japanese (or
+an equivalent prose-polishing skill) is available, hand Japanese prose to
+it for that pass; otherwise apply ordinary careful-writing judgment, but
+don't treat it as this skill's responsibility to enforce.
+
+
+## 4. Review — structural check
+
+After writing, work through the following in order. For atomic artifacts
+(commit message, PR description, issue report, code comment/docstring, a
+single appended release-notes entry), steps 1 and 4 collapse into simply
+re-reading the short artifact against its own doctype skeleton — treat
+step 2 as the primary check for those.
+
+1. **Skeleton read-through, from the reader's seat**: extract just the
+   headings and the first sentence of each section, and re-read them as the
+   §1 reader would — not as the author. Confirm the argument holds together
+   and nothing assumes knowledge that reader doesn't have yet. If not,
+   revisit how the headings are structured (for long documents, this is the
+   same lens as the §2 outline review, now applied to the finished prose).
+2. **Doctype checklist**: compare against the checklist at the end of the
+   matching reference file.
+3. **Structural lint**: where possible, run `uv run scripts/lint.py <file>`
+   (add `--atomic` for a commit message, PR description, issue report,
+   code comment/docstring, or a single release-notes entry) to
+   mechanically catch heading-level skips, code blocks missing a
+   language tag, leftover placeholders, and suspicious links. Findings
+   are flags, not mandates — deliberate exceptions can stay; note the reason
+   briefly.
+4. **Reader-goal recheck**: confirm the "what the reader can do after
+   reading" outcome from §1 is actually achievable from this document alone.
+
+## 5. Doctype checklist summary
+
+See each reference file for detail. The items below are for living,
+multi-section documents (README, design doc, API reference, release notes,
+user manual, Zenn/Qiita article). Atomic artifacts (commit message, PR
+description, issue report, code comment/docstring, a single appended
+release-notes entry) are already covered by their own doctype checklist
+via step 2 in §4 — these common items don't add extra requirements on top
+of that. Common items to confirm:
+
+- Do the first three lines convey the purpose and target reader?
+- Does reading only the headings trace the whole document's flow?
+- Are prerequisites/dependencies stated before the usage steps?
+- Can code/command examples be copied and run as-is?
+- Are known limitations/unsupported cases/caveats stated, not omitted?
+- Where staleness is a real risk, is the version/last-updated date/target
+  branch stated?
+
+## Acknowledgment
+
+The idea of separating structure from prose comes from
+[natural-japanese](https://github.com/coji/natural-japanese) (MIT License)
+and its design principle "machines detect, humans (or agents) judge" and
+"prevent at generation time rather than fix afterward". This skill extends
+that separation to the structural side of technical documents, deliberately
+leaving prose naturalness out of scope.

package/skills/tech-writer/assets/templates/design-doc.md

@@ -0,0 +1,29 @@
+# <Noun phrase naming the decision>
+
+<One-paragraph summary: the decision being proposed and why it matters now.>
+
+- Status: Proposed / Accepted / Rejected / Superseded
+- Date: <YYYY-MM-DD>
+
+## Context
+
+<Why this decision is needed now. State facts, not opinion>
+
+## Decision
+
+<State what was chosen in one sentence, then the details>
+
+## Alternatives considered
+
+### Option A: <name>
+
+<Description and why it was rejected>
+
+## Consequences
+
+- Gains: <...>
+- Costs / trade-offs accepted: <...>
+
+## Open questions
+
+- <If any>

package/skills/tech-writer/assets/templates/pr-description.md

@@ -0,0 +1,23 @@
+## What
+
+<What changed, 1–3 sentences>
+
+## Why
+
+<Why it's needed. Related issue: #___>
+
+## How
+
+<Main design decisions. Implementation detail is left to the diff>
+
+## How to verify
+
+1. <Concrete steps the reviewer can use to reproduce>
+
+## Impact / breaking changes
+
+- <State explicitly if any; otherwise state "none">
+
+## Remaining work
+
+- <If any>

package/skills/tech-writer/assets/templates/readme.md

@@ -0,0 +1,38 @@
+# <Project name>
+
+<What this is, in one sentence>
+
+## <The problem this project solves>
+
+<Problem → approach, 2–4 sentences>
+
+## What you can do
+
+- <Feature 1 (start with a verb)>
+- <Feature 2>
+
+## Setup
+
+### Prerequisites
+
+- <Required versions, permissions, OS, etc.>
+
+### Install
+
+```bash
+<Command(s) that run as copy-pasted>
+```
+
+## <Verb-first heading naming the smallest successful experience, e.g. "Generate your first README">
+
+```bash
+<Command/code showing the smallest successful experience>
+```
+
+## Known limitations
+
+- <What's not supported / caveats>
+
+## License
+
+<License name>

package/skills/tech-writer/assets/templates/user-manual.md

@@ -0,0 +1,22 @@
+# <What this guide gets you>
+
+Target reader: <floor of prior knowledge assumed>
+
+## Prerequisites
+
+- <Required permissions, environment, pre-installs>
+
+## Steps
+
+1. <Action> — after running this, you'll see <state change>.
+2. <Action> — after running this, you'll see <state change>.
+
+## Completion check
+
+<What should be displayed/generated to confirm success>
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| <...> | <...> | <...> |

package/skills/tech-writer/references/doctypes/api-docs.md

@@ -0,0 +1,33 @@
+# API reference type
+
+The recommended skeleton and checklist for endpoint/function-level
+reference documentation, optimized for a developer who wants to get a
+first call working.
+
+## Target reader
+
+A developer who wants to call this API from their own code. The goal is
+"get the smallest request to succeed".
+
+## Recommended skeleton (per endpoint/function)
+
+1. **Signature**: the endpoint (method + path) or function signature first.
+2. **One-sentence description**: what it does. State side effects (state
+   changes, billing, async processing) if any.
+3. **Parameters**: a table (name, type, required/optional, default,
+   description). Include units (seconds/ms, bytes/KB) in the description.
+4. **Request example**: a minimal, runnable code example (curl or the
+   target language). Mark credentials clearly as placeholders.
+5. **Response example**: a real success example (actual sample values, not
+   just types).
+6. **Errors / status codes**: a table (code, meaning, whether to retry).
+7. **Rate limits / deprecation notices** (if applicable): don't omit.
+
+## Checklist
+
+- [ ] Does the request example run after just swapping in values (URL/token
+      fields clearly marked as placeholders)?
+- [ ] Does the parameter table have a required/optional column?
+- [ ] Does each error code say what the client should do about it?
+- [ ] Do deprecated parameters/endpoints point to a migration path?
+- [ ] Are units (time, size, currency) stated explicitly?

package/skills/tech-writer/references/doctypes/code-comments.md

@@ -0,0 +1,39 @@
+# Code comments / docstrings type
+
+The principles and checklist for in-code documentation, where the same
+"why, not what" and completeness discipline applies at the scale of a
+single comment or docstring.
+
+## Target reader
+
+Whoever changes this code next (including your future self). The goal is
+to convey "why it's written this way" — the "what" should be conveyed by
+the code itself.
+
+## Principles
+
+1. **Write "why", not "what"**: don't repeat in a comment what the code
+   already shows. Explain why this implementation/ordering/exception
+   handling is necessary.
+2. **Write docstrings from the caller's perspective**: order arguments,
+   return values, exceptions, and side effects by what the *caller* wants
+   to know, not by internal implementation order.
+3. **Give `TODO`/`FIXME` a reason and, if possible, an issue link**:
+   `TODO: fix later` carries zero information. Write
+   `TODO(#123): running synchronously, async pending queue rollout`
+   instead.
+4. **Don't write comments that state the obvious**: delete comments like
+   `i += 1  # increment i by 1`.
+5. **Only comment on non-obvious choices**: implementations that look like
+   a detour, special code for performance reasons, or external constraints
+   (API quirks, past-bug workarounds) must always get a comment.
+
+## Checklist
+
+- [ ] Are there redundant comments left where the code's intent is clear
+      even without them?
+- [ ] Do non-obvious implementations have their reasoning explained?
+- [ ] Is docstring argument order driven by the caller's concerns rather
+      than internal variable order?
+- [ ] Do `TODO`/`FIXME` items have a reason or a tracking reference
+      (issue number, etc.)?

package/skills/tech-writer/references/doctypes/design-doc.md

@@ -0,0 +1,42 @@
+# Design doc / ADR / RFC type
+
+The recommended skeleton and checklist for a design decision record: a
+document meant to earn a reviewer's agreement now and explain the "why" to
+someone reading it long after the decision was made.
+
+## Target reader
+
+Someone reviewing to reach a decision, or someone later tracing the history
+of that decision. The goal is "consensus" or "record", not a how-to guide
+for implementation.
+
+## Recommended skeleton (ADR format)
+
+1. **Title**: a noun phrase naming the decision (e.g. "Adopt Redis for the
+   async job queue").
+2. **Status**: Proposed / Accepted / Rejected / Superseded — state one.
+3. **Context**: why this decision is needed now. State the current
+   constraints as facts, separate from opinion.
+4. **Decision**: say what was chosen in one sentence first, then the
+   details.
+5. **Alternatives considered**: keep at least one, including why it was
+   rejected. Prevents future re-litigation of "why not A".
+6. **Consequences**: not just the upside — include the costs/constraints
+   accepted.
+7. **Open questions** (optional): leave unresolved points during review.
+
+## Design doc (RFC format, pre-implementation) specifics
+
+- Stating "what we will *not* build" (Non-Goals) before "what we will build"
+  keeps review discussion from drifting.
+- If there are diagrams (sequence/architecture), make the diagram carry the
+  primary information; keep the prose as supporting detail only.
+
+## Checklist
+
+- [ ] Is the decision stated in one sentence up front?
+- [ ] Are alternatives and their rejection reasons present (not written as
+      "the only option")?
+- [ ] Are trade-offs (what's given up) stated explicitly?
+- [ ] Are Non-Goals stated (for RFCs)?
+- [ ] Does the status reflect the current state?