---
name: docs-style
description: Apply OkaneWorks house style to technical prose. Use when writing or reviewing READMEs, AGENTS.md or CLAUDE.md, code comments, commit messages, PR descriptions, or technical work reports, including prose-only cleanup.
license: MIT
---

# Docs style

Help the reader understand the point, make a decision, or complete a task.
Follow the requested audience, format, and repository conventions. Preserve
deliberate quotations and creative voice when the task calls for them.

## Establish scope

Read the material and surrounding context. Identify the reader's task and the
allowed edits. Use supplied evidence for new writing; verify claims that need
checking. For factual updates, change the requested facts and affected text.
For prose-only cleanup, follow the preservation rules below.

Ask only for missing information that would change the result. A writing request
does not authorize code changes, publication, or configuration changes.

## Write

1. Lead with the point. Follow with the explanation the reader needs.
2. Use active voice, concrete terms, and consistent names. Name the actor when
   it matters.
3. Cut filler, inflated claims, stacked hedges, and repeated conclusions. Keep
   uncertainty required by the evidence.
4. State behavior directly. Avoid contrasting it with an unrequested alternative.
5. Keep each paragraph on one subject. Use bullets for parallel items and
   numbered steps for an ordered procedure.
6. Maintain each fact or procedure in one place and link to it. Update existing
   text instead of appending a contradictory correction.
7. Describe supported behavior in standing guidance. Keep chronology, dates,
   and compatibility history when needed to understand or use it, or when the
   document itself is a historical record.
8. Omit what the reader can infer; retain constraints and reasons that prevent
   mistakes. Brevity must not remove an operational requirement.
9. Use commas, periods, or parentheses for ordinary sentence breaks. This is a
   house preference, not a correctness test.
10. End when the useful content ends.

Read [tells](references/tells.md) when removing filler and
[examples](references/examples.md) when deciding what to preserve. Keep words
that carry technical meaning, even when listed as possible filler.

## Fit the deliverable

**READMEs and procedures:** start with the title, purpose, and use. Put
prerequisites before the step that needs them. Give exact commands or UI paths,
required inputs, and an observable success check. Link to separately owned
procedures. Use settings or placeholders for private machine-specific inputs;
retain values needed to execute a command. Keep progress diaries in their
intended record. Choose instructions, explanation, reference, or a tutorial to
match the task. Use descriptive headings and links, text alternatives for
meaningful images, and instructions that work without color cues. Check
executable examples with available tools when safe and authorized; otherwise
state what remains unverified.

**Agent instructions:** keep rules that prevent plausible mistakes. Make them
checkable, distinguish requirements from preferences, and retain useful reasons.
Put rules in the narrowest scope that owns them; link to skills or docs for
detail. Follow the target harness's actual precedence; proximity alone does not
establish authority. Use emphasis sparingly.

**Code comments:** explain constraints, invariants, surprising behavior, or
reasons the code cannot express. Keep them near the code and match surrounding
density. Use enough space to preserve the reason; link to a maintained document
for long design discussions. Remove redundant comments within scope. Correct or
remove verified stale comments only when factual changes are authorized.
Preserve tool-readable comments, directives, doctests, generated documentation,
and structured documentation contracts unless changing them is part of the task.

**Commits, PRs, and reports:** follow repository subject conventions. Otherwise
use an imperative, specific, sentence-case subject, about 50 characters, with no
final period. Explain what changed and why. Lead PR text with the concrete
problem and resulting behavior; include relevant validation, material risk, and
required follow-up. Rewrite the description when scope changes. Reports need
the outcome, remaining work, and any decision required. When the reader must
act, give the command or UI path and how to tell it worked.

Keep newly written public text free of private values, internal jargon, ticket
IDs, private agent names, and incidental infrastructure details. Keep public
issue references and tool names relevant to the subject.

## Prose-only cleanup

1. Establish the requested files or diff. For branch cleanup, cover changed
   documentation and prose comments in changed code; include PR text when
   authorized. Leave unrelated lines alone.
2. Preserve code, commands, flags, paths, tool directives, executable examples,
   quotations, and useful technical meaning. Keep legal, copyright, license,
   and attribution notices verbatim.
3. Add no facts. Cut filler and repetition. Remove history, status, or facts
   visible in adjacent code only when unnecessary to the document's purpose;
   list factual cuts in the commit body or handoff. Report questionable claims,
   suspected stale comments, and other proposed factual omissions without
   silently correcting them.
4. Report pre-existing private disclosures outside the edit scope without
   repeating sensitive contents; do not silently redact them as style edits.
5. Inspect the diff. When committing, separate prose-only cleanup from behavior
   changes.

## Final check

- The reader can find the point and complete the intended task.
- Claims match evidence; uncertainty, constraints, and useful rationale remain.
- Edits stay within scope; cleanup adds no facts and records permitted cuts.
- Commands, examples, links, and paths retain their meaning and resolve for the
  target environment. Tool-readable content retains its behavior.
- Each comment earns its space; no filler or duplicate section remains.
- Introduced public text contains no private values or incidental private IDs.

Read [sources](references/sources.md) when checking provenance or maintaining
the writing guidance.