Nbj Write Clearly

NBJ Write Clearly

Outcome

Produce prose that lets the reader understand the point, identify the actor and action, and complete the task without rereading. Preserve the author's facts, intent, uncertainty, and useful voice.

Apply the right authority

Use this order of precedence:

1. Follow the user's explicit request and the destination's requirements.
2. Preserve source facts, quotations, code, UI labels, product names, and intentional terminology.
3. Follow project-specific style.
4. Apply this skill's Google-derived guidance.
5. Consult other references only when the preceding sources are silent.

Depart from a guideline when doing so makes the content clearer for its actual readers. Stay consistent after making that choice.

Write or revise

1. Identify the reader, their goal, the artifact type, and whether the task is to draft, revise, or audit.
2. Mark content that must not drift: facts, claims, qualifications, quoted language, technical tokens, links, and required structure.
3. Put the result or purpose first. Give each paragraph one idea and put critical information early.
4. Name the actor. Prefer active voice, present tense, and second person when addressing the reader. Use imperatives for steps.
5. Put a condition or circumstance before the instruction it controls.
6. Prefer familiar, precise words. Define necessary jargon or abbreviations on first use. Keep one term for one concept.
7. Use short sentences and paragraphs, but don't flatten every sentence into the same rhythm. Use common contractions when they sound natural.
8. Remove throat-clearing, repeated conclusions, fake quotations, excessive claims, pre-announcements, clichés, idioms, and decorative metaphors.
9. Structure for scanning: sentence-case headings, numbered lists for sequences, bullets for parallel items, and descriptive links.
10. Read references/guide.md when the artifact includes procedures, code, commands, UI labels, tables, images, accessibility requirements, or a line-level style audit.
11. Read references/official-index.md only when the user requests Google Style Guide compliance or the task turns on a specialized rule such as word choice, product naming, punctuation, grammar, dates, units, mathematical notation, HTML, Markdown, filenames, or trademarks. Consult only the relevant official page when browsing is available.

Protect meaning and voice

• Do not add facts, certainty, praise, urgency, or product claims.
• Preserve source modality such as can, might, should, and will. Do not change it only to satisfy a tense preference.
• Do not replace exact code, commands, filenames, API names, UI labels, or quotations with stylistic alternatives.
• Do not rewrite when the user asked only for an audit. Report findings in priority order and give bounded examples.
• Do not force documentation conventions onto dialogue, fiction, legal language, quotations, or a deliberately personal voice.
• Do not make prose childish or robotic in the name of simplicity. Prefer the clearest accurate term, even when it is technical.

Validate

Before returning the result, check that:

• the opening answers the reader's main question;
• every instruction names or clearly implies the actor;
• conditions appear before the actions they govern;
• each pronoun has an unambiguous referent;
• terminology, capitalization, and formatting are consistent;
• claims remain factual, scoped, and supported by the source;
• a global reader can understand the prose without decoding slang or culture-specific references;
• the revision preserves all required facts, caveats, and technical tokens;
• the output still sounds like the author when voice matters.

Stop when the content is clear, accurate, consistent, and fit for its destination. Do not keep polishing lines that already do their job.