prose-discipline

Files (5)

• SKILL.md
• complexity-settings.md · references/
• check-prose.py · scripts/
• check-readability.py · scripts/
• source.py · scripts/

SKILL.md (first lines)

# Prose style

Prose governs what humans read; code governs what machines run. They need
different disciplines. A correct but unreadable document has failed its reader.

## Applicability

This standard is always required wherever prose is used.

It applies to prose in governing text, documentation, instructions, workorders,
reports, comments, reviews, and agent interaction, regardless of profile,
deliverable, workflow, or user interaction.

Human legibility and drift control are the same reliability concern. LLMs
operate through human language; if prose is difficult for a human to interpret
reliably, treat the model input or output as defective.

## Summary

This skill sets the minimum prose quality bar. Clarity comes before
compression, and the reader should understand on one pass. Precision limits
semantic drift for humans and language models.

## Priority order

When principles conflict, resolve in this order:

1. **Clarity** — the reader understands on one pass
2. **Accessibility** — concepts are introduced before being compressed
3. **Accuracy** — the content is structurally correct
4. **Compression** — no word is wasted

Clarity and compression frequently conflict. Clarity wins.

## Voice

Prose governed by this standard is:

* calm — no urgency, no alarm, no hype
* authoritative — states facts, not opinions dressed as facts
* understated — the structure carries the argument; the prose does not
  push it
* pragmatic — oriented toward consequence, not description for its own
  sake

Authority is earned through clarity. It is not asserted through volume,
repetition, or confident-sounding language.

## Accessibility

The reader should not need to decode meaning. Every sentence should be
clear on first contact.

* introduce a concept before compressing it
* reduce cognitive load — if two readings of a sentence are possible,
  eliminate one
* do not use ambiguity as a stylistic device
* prefer explicit nouns over pronouns unless the referent is unambiguous
* the reader should feel guided, not tested

## Sentence structure

* short declarative sentences for emphasis — use selectively
* explanation before compression — never the reverse
* one conceptual move per paragraph
* paragraphs of one to three sentences as the default
* one-line paragraphs reserved for structural conclusions, not for
  every point
* avoid long runs of one-line paragraphs — they create pressure without
  context

## Section flow

Each section completes one conceptual cycle:

1. observation — what is true
2. explanation — why it is true or how it works
3. operational implication — what follows from it
4. structural resolution — the conclusion, stated plainly

A section that stops at observation or explanation is unfinished. A
section that opens with its conclusion before establishing the context
is unreadable.

## Structural lines

A structural line is a compressed statement that resolves a section's
argument. It must:

* be preceded by sufficient explanation
* resolve a clearly established idea
* feel inevitable given the preceding context

If a structural line can be removed without loss of meaning, remove it.
If it cannot be understood without re-reading the section, expand the
section first.

One structural line per section is the norm. Two is the maximum.

## Subject discipline

Keep the system, process, or document as the primary subject of each
sentence. Avoid unnamed human actors when the action can be expressed
through the mechanism itself.

Preferred:

```
The workorder authorizes the change.
The validator rejects the file.
The boundary holds.
```

Avoid:

```
Someone needs to authorize the change.
You should run the validator.
They held the boundary.

From iamthenop/infurnet-skills, MIT.

More from iamthenop/infurnet-skills