Writing

Most readers land on one page from a list, a search result or a link, with nothing read before it. A page that opens with its subject and its stake answers that reader on its own; a page that opens with a pointer sends the reader elsewhere before it has given them anything. The tone throughout is a product explaining itself plainly: plain words, checkable facts and honest roles, with no selling and no decoration.

A Claimwick problem opens "Employees wait three weeks for reimbursement while approvers batch decisions monthly." A reader who has opened no other page knows who waits and what it costs them.

Reviewed forWhich records, sections and pages open with a pointer, a code or a field name instead of who and what is at stake? Look at the first sentence of each page the change adds.

Marked guidance: a reviewer answers this question.

A sentence that opens with its actor states who does what before the reader reaches the verb, and the present tense states what holds today rather than what a plan intends. Passive and future forms hide the actor or promise a behavior no record states. Second person belongs only on tutorial and how-to pages, where the reader is the actor; records stay in the third person, as the text-kind table on the Record Language page states.

Claimwick writes "Finance reimburses the due expense." The actor Finance opens the sentence, and the present tense states what holds.

Reviewed forWhich sentences open with a thing instead of an actor, use the passive voice, or promise in the future tense? Look at the statements and summaries the change adds.

Marked guidance: a reviewer answers this question.

A metaphor reads smoothly while hiding what the project means: each reader pictures a different act behind the same flourish, and a metaphor title hides its subject in every list that shows it. A literal phrase names the act itself, so no reader has to decode it. Each concept keeps its one glossary term, as litespec/core/authoring#use-one-term-for-one-concept states; this page adds only that a term a cold reader may not know is defined where it first appears or linked to its glossary entry.

A Claimwick problem is titled "Expenses Wait Weeks for Reimbursement". The title names the wait and the delay literally, with no figure of speech to decode.

Reviewed forWhich titles or sentences use a metaphor, a stock phrase or an undefined term where a literal phrase exists? Look at the titles and first uses the change adds, beside the glossary.

Marked guidance: a reviewer answers this question.

A record sentence carries one fact a builder implements, and a sentence past 25 words usually carries two facts joined by a comma, so the reader weighs both at once or misses the second. Twenty-five words is the longest sentence a reader parses once, and the bound is mechanical, so a check counts it the same way on every record. A longer explanation belongs in the explanation file, split into sentences that each carry one fact.

"Employees wait three weeks for reimbursement while approvers batch decisions monthly." The sentence holds 11 words and one fact.

Reviewed forWhich record statements or summaries carry a sentence past 25 words? Look at the statements and summaries the change adds.

Marked guidance: a reviewer answers this question.

A paragraph that holds a rule, an exception and a fallback in one block forces the reader hunting for one of them to untangle all three. One idea per paragraph puts each fact where a scanning reader finds it, and one line per paragraph keeps diffs readable, so a changed sentence shows as one changed line. A list drawn from prose that is not parallel hides the reasoning that connects its items; connected reasoning stays in prose, and only parallel items become a list.

The Claimwick decision explanation gives What Would Reopen It its own paragraph. A reader looking for what would reopen the choice finds that paragraph without reading the example above it.

Reviewed forWhich paragraphs carry two ideas, wrap across hard line breaks, or list items that are not parallel? Look at the explanation files and documents the change adds.

Marked guidance: a reviewer answers this question.

One mechanical form per fact keeps every search, diff and listing exact: license in one page and licence in another split every lookup, and a curly quote or a typographic dash renders differently in terminals, generated context and plain-text tools. Numerals for measured quantities keep a count scannable beside its unit, while small counts in prose stay words a reader absorbs without stopping. An ISO date in a field sorts and checks as data; the same date in prose reads "2 November 2026", in the order a person says it. Contractions belong on documentation pages, where the voice is a person explaining; records hold none, because a record states a fact in its shortest checkable form. ASCII prose follows litespec/core/authoring#keep-authored-prose-ascii-safe.

Claimwick prose writes "The tenant keeps receipts for 7 years, files them by month, quarter, and year, and closes the period on 2 November 2026." The field beside it holds 2026-11-02.

Reviewed forWhich pages use British spelling, drop the serial comma, spell out a measured quantity, shorten a prose date, or carry a contraction inside a record? Look at the prose the change adds.

Marked guidance: a reviewer answers this question.

A title is the record's name in book lists, outlines, tabs and search results, so it reads as a name, never as a sentence: Title Case capitalizes every major word and lowercases a, an, the, and, but, or, nor, for, so, yet, as, at, by, in, of, off, on, per, to, up, via, with, from, into, over and than unless the word stands first or last. One casing rule for every title is the only casing rule a check enforces the same way everywhere; mixed casing makes two records of one kind read as two kinds. Eight words keeps the whole title on one scannable line in a list while leaving room for the longest form, a problem clause naming who and the pain. LiteSpec headings follow the same casing under litespec/core/authoring#use-controlled-capitalization.

The Claimwick requirement title reads "Expense Above Threshold Carries Receipt", five words in Title Case with no final period.

Reviewed forWhich record titles fall outside Title Case, end in a period, or run past eight words? Look at the titles the change adds.

Marked guidance: a reviewer answers this question.

One form per type makes a list of mixed records scannable: the form tells the reader what kind of thing the record is before the title is weighed, and a literal subject tells them what it is about. A feature titled with one word, a goal titled with a milestone code, or a problem titled with a metaphor gives the reader neither, and a problem title that names no person leaves the reader guessing who has the pain. The number and date of a goal stay in its fields, where a check reads them; the title names the outcome alone.

A Claimwick feature is titled "Approval Reminders for Waiting Expenses". The noun phrase names the capability; no date, milestone or promise sits in the title.

Reviewed forWhich titles miss the form of their type, name no subject, or carry a code, date or metaphor? Look at the titles the change adds, beside the title-form table.

Marked guidance: a reviewer answers this question.

A statement states what holds, as a fact a builder implements. A modal word such as must, should, shall, may, can or will turns the fact into an intention, a permission or a promise, and each reader grades its strength differently. One sentence keeps one commitment per statement, so a change to one commitment changes one statement. The value style on the Record Language page states the same form; this provision states the prose reason and the check covers every record type.

Claimwick states "An expense above the threshold carries a receipt." The sentence states what holds, with no modal word grading it.

Reviewed forWhich record statements carry a modal word or a second sentence? Look at the statements the change adds.

Marked guidance: a reviewer answers this question.

This field is the lead a cold reader meets in the book, before any field table or link. A first sentence that restates who and what is at stake lets that reader judge the record without opening its links; a bare pointer such as "described on the launch page" gives them nothing to judge and breaks the moment the pointed page moves. A pointer that follows the content helps the reader who wants more; a pointer that replaces the content helps no one.

A Claimwick problem summary opens "Employees wait three weeks for reimbursement while approvers batch decisions monthly." Who waits and what it costs stand in the first sentence, and any link follows after it.

Reviewed forWhich summaries open with a pointer, a field name or background instead of who and what is at stake? Look at the first sentence of each one the change adds.

Marked guidance: a reviewer answers this question.

Intent records state what the product promises, and a promise mixed with how the company runs buries the product fact a builder came for. A launch date in a problem, a headcount in a goal, or a price list in a feature reads as part of the promise and changes with every company change, even when the product behavior stands still. Company facts enter only as a constraint the application enforces or as dated research, where their form states what they are. The scope boundary itself lives on the Scope and Intent pages; this provision states the prose consequence.

A Claimwick goal states the reimbursement target in its target field. Its prose names no sprint, no headcount and no launch calendar.

Reviewed forWhich Intent records carry a schedule, an effort estimate, a headcount, an offered price, a market fact or a launch date in prose? Look at the Intent records the change adds.

Marked guidance: a reviewer answers this question.

A fixed section list answers the same questions on every record of one type, so a reader who learned one problem page reads the next without relearning where the evidence sits. Each list answers what a cold reader needs: who has the need, why it matters, what good looks like, and what the record connects to. A problem earns four sections because its reader judges a pain: who has it, what they do today, the evidence for it, and what would retire it. Free sections may follow the fixed ones; they never replace one.

The Claimwick problem explanation for waiting expenses runs Who Has It, What They Do Today, Evidence, What Would Retire It. The evidence stands in its own section instead of inside a pointer to another page.

Reviewed forWhich explanation files miss a fixed section, reorder the list, or open without their H1 title? Look at the explanation files beside the records the change adds, beside the explanation-section table.

Marked guidance: a reviewer answers this question.

A tutorial that stops to explain a trade-off loses the reader mid-path, and a reference page that teaches leaves the reader hunting for the value they came to look up. One job per page puts each fact where its reader looks for it, and the opening tells a reader from a search result within two sentences whether this page answers their question. A README earns its first screen the same way: what the folder holds, who reads it, and where each reader goes next, before any file list. The page styles and their sections live in the Authoring Standard; this provision states the prose each kind opens with.

A Claimwick how-to page opens "Remind an approver who has held an expense past three business days." The reader and the one problem solved stand before the first step.

Reviewed forWhich pages mix two jobs, open with background instead of their kind's opening, or state no reader and purpose in their first lines? Look at the opening lines of each documentation page the change adds, beside the documentation-kind table.

Marked guidance: a reviewer answers this question.

The code already states what it does, so a comment that restates it adds words a maintainer must keep true without adding knowledge. The reason a boundary exists, the constraint a caller must respect, or the failure a member reports is what the next reader cannot recover from the code alone. History belongs in the commit that made the change, where a reader looking for it finds it; commented-out code is history with no commit to explain it. An API summary states the contract first: what the member does, what it needs, what it returns, and which failures belong to the contract, in the form the stack's pages state.

A Claimwick handler comment states why the approval check runs before the payout call. It names no step the code below it already shows, and holds no earlier version of the call.

Reviewed forWhich comments restate the code, hold commented-out code, or recount how the code arrived? Look at the comments and API summaries the change adds.

Marked guidance: a reviewer answers this question.

A changelog serves a reader deciding whether to upgrade and a reader checking what changed after upgrading, and both need the observable change, its condition and the required action, never an inventory of the work. Stating the present state first lets every other page describe what is true today without carrying a former behavior; the changelog is the one place where the comparison with the previous release belongs. A breaking change, a removal and a security fix each state what stops working, who is affected, and the replacement or action, in the entry itself rather than behind a link.

A Claimwick changelog entry states "Submitting an expense without a receipt above the threshold is refused. Employees attach the receipt before submitting." The behavior, the reader and the action stand in the entry.

Reviewed forWhich entries inventory files or work, bury their condition or action, or describe a former behavior outside the changelog? Look at the entries the change adds.

Marked guidance: a reviewer answers this question.

A decision record exists for a reader who was not there when the choice was made, and that reader needs the forces, the alternatives and the consequences, not the discussion that produced them. Options compared on the same points let a later reader rejudge the choice when the world moves; a record that names only the winner forces the whole argument to run again. What would reopen the choice belongs in the record beside the choice, so a stable decision stays stable until the named condition holds. Any option singled out from the decision carries its own sentence saying why it stands apart.

A Claimwick decision compares a receipt threshold of EUR 25 with EUR 50 on refusal rate and approver load, chooses EUR 25, and names a refusal rate above the stated bound as what would reopen it.

Reviewed forWhich decision records name no real alternative, compare options on different points, recount the discussion, or omit what would reopen the choice? Look at the decision records the change adds.

Marked guidance: a reviewer answers this question.