| name | document-writing |
| model | sonnet |
| description | Apply Bajutsu's language-independent prose rules when writing or revising roadmap items or documentation. Use it with the matching English or Japanese writing skill. |
Technical-writing norm
Bajutsu's writing is argued prose: BE items and the documents under docs/ make a case a reader
must be able to follow. This skill is the authoritative norm for that prose, in both languages.
Invoke it before you write or revise, not after — it shapes the draft, it is not a proofreading
pass.
- Scope. Every BE roadmap item (
roadmaps/BE-*/*.md and its *-ja.md mirror) and every
document under docs/ (and the docs/ja/ mirror), in both languages. It does not govern
code docstrings, which keep their own standard (BE-0065).
- An umbrella above two language layers. The language-agnostic principles below hold for both
languages. On top of them, apply the layer for the language you are writing: for English,
english-document-writing (serial comma, that / which,
dashes, numbers, and the rest of the English mechanics); for Japanese,
japanese-document-writing. Each language layer holds only the
guidance its own grammar and typography need, and never applies to the other language. Where a
language layer overlaps these principles (filler, redundancy, restraint of rhetorical flourish,
paragraph and argument structure, self-containment, anaphora), that layer's specific wording governs
for its language.
- Enforcement stays a review-time norm, not a CI gate. Judging clarity, emphasis, and argument order
needs semantic judgment; putting that on the gate would put an LLM on the
run / CI verdict path,
which prime directive 1 forbids. It holds the same way the bilingual-docs and DESIGN.md-alignment
(BE-0113)
norms hold: a contributor and reviewer expectation, checked by people.
Language-agnostic principles (both languages)
- Draft top-down, version by version. Do not write a long argued section linearly from its
first sentence. Build it in passes: first a rough outline of the points in the order you will
treat them; then the section titles and each section's main idea; then subideas and a story line;
then the near-final prose. The outline forces the organization the reader will need.
- Go for clarity and simplicity. On review, cut every word, phrase, and sentence that carries
no meaning. Streamlining is a required pass, not a nicety.
- State the contribution up front. A BE item's Introduction and Motivation state the problem,
the background, the contribution, and why it matters — before the detail. A reader who stops after
the first two paragraphs should still come away with the point.
- Say how a later reader could tell the contribution arrived. The same principle applied to a
BE item: alongside the contribution, Motivation names one observable difference the change is meant
to produce — a change in behavior, in output, or in a quantity a reader could later check against
the shipped result. That outcome is not the item's Progress checklist, which tracks whether the
work landed rather than whether the predicted effect followed. A number is optional; "the local
self-review pass converges before a push, instead of the live bot's cycle restarting on unrelated
findings" serves as well as one, because a reader can still tell whether it held
(BE-0383).
- The two stress points of a sentence are its beginning and its end. The end carries the most
emphasis, so reserve it for the most important element. Move from the known to the unknown, from
the given to the new, from background to result. Put transitional and background words
("Therefore", "However", "In the last section") at the front, saving the content for the end.
- Keep the verb close to the subject. A long clause wedged between a subject and its verb makes
a sentence hard to parse. Rewrite so the verb arrives early, then let the qualifications follow.
- Prefer the active voice, and write as "we". The active voice is clearer and shorter; the
first-person plural keeps it active without the "I" of a personal essay.
- Cut filler. Drop words and phrases that add no meaning — "actually", "basically",
"essentially", "it is important to note that", "note that", a bare "now". Keep "thus" /
"therefore" only where they genuinely signal a conclusion.
Paragraph structure (both languages)
Paragraph writing: treat the paragraph, not only the sentence, as the unit of argument. A reader
must be able to follow the case being made paragraph by paragraph, without re-reading to find where
one point ends and the next begins.
- One topic per paragraph. A paragraph that mixes several beats of a narrative (investigating,
reporting, verifying, evaluating) is really several paragraphs. Split it so each paragraph carries
exactly one step.
- Front-load the topic. A reader who reads only a paragraph's first sentence should know what
the paragraph is about. Do not bury the topic after a run-up.
- Open on the logical relation to what came before. Start the paragraph with the connective that
states how it relates to the previous one ("therefore", "in fact", "however", "even this example
alone shows"), not partway through.
- Argue in one direction. Reach a conclusion, then dispose of objections, then stop — do not
restate the conclusion afterward. State it once.
- Do not let an aside interrupt the climax. Handle an anticipated objection (an example that
might look contrived, a preemptive caveat) at a paragraph or section boundary, not right after the
moment it would otherwise interrupt.
- Name a misreading before correcting it. When a reader is likely to draw the wrong conclusion,
state that wrong conclusion explicitly, then give the real one — do not only assert the correct
account and leave the misreading unaddressed.
- Justify a denial in the same sentence. When writing "A, not B", give the reason for ruling out
B in that sentence rather than leaving it implicit.
- Do not preview the payoff. A number or fact meant to land with impact belongs in the paragraph
where it lands, not foreshadowed in an earlier one.
- Place forward references at a boundary. "Covered in a later section" belongs at the end of a
paragraph or section, once the point in hand is settled — not dropped mid-argument, where it
breaks the reader's flow.
- Quote the exact claim you are denying. When you deny or qualify something, name the specific
proposition you are ruling out — a vague denial ("not everything is solved") tells the reader
nothing; naming the precise claim that is false does.
Self-contained prose (both languages)
A document must be understandable on its own. A reader who has not read anything else in the
repository — no other BE item, no other page under docs/, no earlier commit — must still be able
to follow it start to finish.
- Never assume prior reading. Do not write as though the reader already read a linked document, an
earlier roadmap item, or an earlier section of the same document. Give each piece the background it
needs in place.
- Spell out an abbreviation or acronym on first use. Write the full term, with the acronym in
parentheses right after — "role-based access control (RBAC)" — then the acronym alone for the rest
of the piece. This holds everywhere a term appears, in a roadmap item as much as in
docs/.
Re-expand the acronym if a long document's later section could plausibly be read on its own.
- Define a term where you introduce it, and let a cross-reference only send the reader further.
A link is a supplement for a reader who wants depth — for elaboration, the canonical wording of a
cross-cutting rule, or the record — never a substitute for the context this document needs at
first use, and never the only place a fact the current sentence depends on is stated.
- No omissions. Do not skip a step, a definition, or a piece of context because it "should be
obvious" or "is covered elsewhere". If a reader would have to guess or go looking, the document is
not yet self-contained.
Minimize anaphora (both languages)
An anaphor — a pronoun or demonstrative that points back to something named earlier ("it", "this",
"that", "the former") instead of renaming it — costs the reader a lookup: the reader must hold the
earlier antecedent in memory, then resolve the pointer before the sentence means anything. Reserve an
anaphor for an antecedent that is unmistakable, one sentence back, and within the same paragraph;
beyond that, or once a paragraph, list, or heading boundary intervenes, repeat the noun.
- Repeat the noun once the antecedent is more than one sentence back, or crosses a paragraph, a
list, or a heading. By the time the reader reaches a boundary like that, an antecedent introduced
before it is no longer active in working memory, so pointing back to it forces a return trip. Name
the thing again instead.
- Repeat the noun when more than one candidate antecedent is nearby. A pronoun that could resolve
to either of two nouns mentioned in the same stretch of prose forces the reader to guess, then
double back to confirm the match. Name the one intended.
- Do not chain an anaphor onto another anaphor. A "this" pointing to a sentence that itself
used "it" makes the reader resolve two pointers instead of one. Resolve each reference to the
concrete noun, not to the previous pronoun.
- Disambiguate in place instead of sending the reader back. When an abstract phrase's referent is
not obvious from the immediate context, name it with a parenthetical aside at the point of use
rather than leaving the reader to recover it from an earlier passage.
Verify your work
After drafting, reread once against sentence-level technique: does the piece lead with its
contribution, does each sentence end on its most important element, is the verb near its subject, and
is every sentence free of filler?
Reread again against paragraph structure: does every paragraph carry exactly one topic announced in
its first sentence, and does the argument move in one direction without restating its conclusion?
Reread a third time against self-containment: could a reader who has not read anything else in the
repository follow this piece start to finish, with every acronym expanded and every term defined
where it is first used?
Reread a fourth time against anaphora: does every pronoun or demonstrative resolve to a single,
nearby, unambiguous antecedent, with the noun repeated everywhere it does not?
Then run the same four rereads under the layer for your language:
english-document-writing for English,
japanese-document-writing for Japanese.
This reread is a human-judgment pass. It does not replace the mechanical textlint check below —
run both.
Draft to pass textlint the first time
This repo's textlint config enforces added mechanical limits, beyond the judgment calls above. It
lives at tools/textlint/. Write to meet these limits in the first
draft. A short paragraph, fixed right away, costs less than a finished document with dozens of
findings.
- One clause, one sentence.
ja-technical-writing/sentence-length fails a long sentence. The cap
sits near 100 characters, in both languages. Split a sentence that needs "because", "which", or
"so that". Turn a sentence that needs a colon before a list into a bullet list instead. Draft short
sentences from the start; do not plan a later splitting pass.
- Cap reading marks at three.
ja-technical-writing/max-comma covers English commas. A matching
rule, max-ten, covers 読点 in ja prose. Both fail a sentence on a fourth mark. A fourth comma or
読点 is the same signal as a too-long sentence. Split the sentence. Or turn the enumeration into a
list.
- Prefer a list or a table. A two-item list beats one long sentence naming both options. Put a
comparison across options in a table instead. A table's cells carry no sentence-length or comma
limit. A long caveat per option fits a table cell, not list-item prose.
- Run textlint section by section, while drafting. Check a section right after writing it. A
document drafted straight through, then checked once at the end, compounds every habit above.
The result is dozens of findings. Catch each one right away; each costs little to fix on its own.
Mandatory textlint verification after drafting
The norms above guide human judgment; they are not machine-checkable. Once a piece is drafted, run
it through textlint and revise until it introduces no new
findings. The bar is the file you started from, not zero. textlint is a mechanical floor, not a
substitute for the norms above — clearing it does not mean the piece satisfies them. This applies to
English and Japanese prose alike; the same config and runtime cover both.
Zero is not the bar because zero is not reachable here, and a target nobody reaches is a target
nobody aims at. Every merged roadmap item carries findings — BE-0390's Japanese side reports 77,
BE-0376's 59 — and 69 of BE-0390's 77 come from a single rule, no-mix-dearu-desumasu, which
demands bullets in である調, the register CLAUDE.md forbids for *-ja.md.
Chasing zero therefore buys a long revise-and-rerun loop that can only end in an arbitrary stop, and
it is the largest single cost in authoring an item. Measuring against the file's own starting count
ends the loop on a fact instead.
- Count before you edit. Run textlint on the file as it stands and keep the number, then clear
what you introduced against it.
- A new file has no starting count, so that rule says nothing about one — reading it as "zero"
reinstates the unreachable bar this section exists to retire. Calibrate against the corpus
instead: run textlint on two or three merged items of comparable length and land in the same
order of magnitude. BE-0376 reports 140 English findings, so a new item scoring near that is in
family; one at several times it has a real prose problem worth finding.
- Clear what you introduced, and leave what you inherited — pre-existing findings in a file
you are touching in part are outside your lane, and clearing them widens the diff.
- A repository norm outranks a textlint rule where the two cannot both hold. The live case is
register: CLAUDE.md puts every
*-ja.md in 敬体, bullet lists included — so unify the whole
document, never just its running prose, and leave the no-mix-dearu-desumasu findings that
unification leaves behind. Switching the file to である調 to clear them inverts the hierarchy.
- Everywhere else textlint wins: clear the finding by revising the prose, never by loosening the
config or raising a threshold to dodge it.
Running it
The config and runtime live in tools/textlint/. It needs node and
npm (the same prerequisite as this repo's other JS checks). Run it from the repository root, passing
the Markdown file(s) you wrote or edited.
TEXTLINT_DIR=tools/textlint
npm --prefix "$TEXTLINT_DIR" ci --ignore-scripts
npx --prefix "$TEXTLINT_DIR" textlint \
--config "$TEXTLINT_DIR/.textlintrc.json" \
path/to/edited.md
Fix auto-fixable findings with --fix, then revise away the rest by hand. Always eyeball the
result of --fix and revert any rewrite that violates the norms above.
Changing the rules
Edit .textlintrc.json to change what's enforced. It
currently enables textlint-rule-preset-ja-technical-writing (the standard Japanese
technical-writing preset) plus a set of individual rules for English prose and for Japanese prose
beyond the preset. The full list and why each rule was chosen live in the "The rules enabled today"
section of tools/textlint/README.md; the same file covers
how to add or retire a rule. Change the config only for structural reasons — adopting or retiring
a rule, or stopping a rule from double-reporting what another already covers. Do not loosen a rule or raise a threshold to
dodge a finding on prose you have written; per the priority above, fix the prose instead.
References
- Jeffrey Scott Vitter, Structure + Style = Communication (The University of Kansas, 2011) — the
source of the language-agnostic principles above (and of the English mechanics now in
english-document-writing).
english-document-writing — the English layer beneath
this norm.japanese-document-writing — the Japanese layer beneath this
norm.docs/ai-development.md — the Documentation style section
this skill is the authoritative reference for.
