holistic-writing

Files (4)

• SKILL.md
• openai.yaml · agents/
• consolidation.md · references/
• reading-examples.md · references/

SKILL.md (first lines)

# Holistic writing

Write for readers without the originating conversation, investigation, or design session.
This skill owns what the artifact explains, how its explanation develops, and how the prose reads.
Completeness and extractable facts do not establish that the writing is worth following.
Use the same editorial criteria when writing and reviewing: prose that needs revision does not become good because a reviewer can reconstruct its meaning.

## Scope and authority

For a routed editorial pass, use the established reader, purpose, requirements, and factual evidence.
Review the artifact rather than restarting its investigation, design, or authoring workflow.
Specialized owners decide its substance; an editorial pass does not expand permission to change it.
A review request does not authorize prose edits.
For review-only work, report findings, evidence, consequences, and the smallest useful corrections.
For authoring with no named artifact, establish the intended reader, purpose, and deliverable before drafting.
Ask when missing context would materially change the result rather than inventing its audience or authority.

Use adjacent owners only for their tasks, not as compulsory stages of this pass:

- `technical-docs` owns documentation-specific authoring decisions; placement alone uses its [placement reference](../technical-docs/references/placement.md).
- `readme-writing` owns introductory README writing and review, not every file named README.
- `reorganize-docs` owns existing documentation trees, page splits, renames, consolidation, and navigation.
- `new-tool-development` owns its tool lifecycle and human-authored product briefs.
  Agents may review those briefs and add only the TODO comments it permits, not write or rewrite brief prose.
- `requirements-definition` owns requirements authoring from an approved product brief.
- `human-review-packets` owns selection and framing of human decision questions and approval handoffs.
- [Design review](../review/references/design.md) owns review-only consistency and completeness analysis of designs or specifications.
- `skill-authoring` owns skill behavior, discovery, and procedure; this skill owns written presentation without silently changing those decisions.
- `typst` owns Typst syntax; use it when the artifact needs that markup, not for every prose review.
- `tighten-prose` owns bounded sentence- and paragraph-level polishing within an established explanation.

If an owner is unavailable, preserve its boundaries, state the limitation, and do not claim that its specialized review occurred.

## 1. Read the artifact and establish its authority

Read the complete current artifact, its relevant entry points, authoritative inputs, and representative uses.
For creation, inspect the material the new artifact must explain and any established destination or form.
For an editorial pass, retain the destination unless relocation is requested.
Use the placement reference when the documentation owner or destination is not already established.
Do not force essays, reports, or instructions into documentation forms.

Before interpreting craft, encounter the reading experience: what comes to matter, what you expect, and what stays with you afterward.
Distinguish pleasure or friction in following the prose from what readers come to understand and how they feel about the subject or themselves.
Be specific about whether a detail changes their mental model, their feelings, or both.
Precise understanding, quiet satisfaction, curiosity, changed appreciation, and felt danger can all matter; neither positive affect nor a tidy mechanism or plot account substitutes for the effect.
When a revision is merely smoother, or an explanation seems clear but its reading judgment feels thin, read the [contrasting readings and revisions](references/reading-examples.md) before choosing edits.

Readers skim headings, search for terms, skip familiar material, and return to earlier passages.
Read the whole artifact to assess it, then trace the paths its readers are likely to take for their tasks.
Check whether they can recognize where to go and understand what they find without having read every preceding word.
A reference can serve a reader who wants one answer; an argument may need sustained reading to develop its thought.

Establish what is observed, selected, provisional, and unresolved.
Do not turn conversation context, search snippets, generated output, or an analysis script into unexplained authority.
Preserve provenance for measurements and reconstructed decisions.
Your review limits are not facts about the author's investigation.
Do not add a first-person claim such as “I have not tested this” unless supplied evidence establishes it.
When reviewing, describe the language and its reading effects rather than inferring the author's identity or effort.
A low-effort impression concerns the presentation; it does not establish who wrote the prose or how hard they worked.

## 2. Choose and develop what matters

Identify the reader's task, assumed background, and the understanding or action the artifact must support.
Make its title and opening intelligible without session context.
Define named proposals or policies rather than relying on their labels.
Explain unfamiliar specialist terms before consequential use while preserving precise established domain terms.
Distinguish facts, decisions, proposals, examples, and unresolved questions.

Choose what deserves attention and explain the connections that matter to that reader.
Your judgment can be wrong; refusing to make it leaves the reader to decide, often with less context and her own risk of error.

When the artifact supports a choice, explain what each relevant option changes, what the reader gains or gives up, and which circumstances make that difference matter.
An inventory of mechanisms, settings, or data does not by itself establish that the prose helps the reader decide.
Trace the connection from the described behavior to its consequences for this reader; do not substitute a recommendation without reasons for that explanation.
Credit connections the prose makes through warranted inference: not every implication must be explicit, and not every artifact needs an exhaustive comparison or a table.
When reviewing, identify the consequential connection the reader must supply and why that effort matters to the stated task.
Stay within the supplied evidence; do not invent missing product facts or treat an unverified factual premise as an established defect.

For an explanatory distinction, identify what it helps these readers understand or decide.
If neither side changes their understanding or choice, it is a distinction without a difference: remove or rework it when writing, and count its wasted attention or false emphasis against the prose when reviewing.
A corrective contrast needs a plausible misconception and an explanation that gives these readers reason to reconsider; do not invent confusion to defend it.

Read forward using the intended reader's assumed background and what the document has introduced so far.
Supply enough context for each passage to make sense when the reader reaches it; develop the connection locally or move its explanation earlier.
Explain the property that makes a technical detail relevant, not just its name.
For a mechanism the reader needs to understand, show why one step leads to the next.
For a loop, walk through one iteration and explain why it leaves the condition for another iteration intact.
Numbered steps, source links, and words such as “therefore” do not supply a missing relationship.
If an essential connection is unsupported, identify that specific gap rather than inventing evidence or retreating to disconnected facts.
When a mechanism remains a list of facts, compare the [property-and-consequence and feedback-loop examples](references/reading-examples.md#explain-what-the-detail-changes-for-the-reader).

Develop a hypothesis as a hypothesis, explaining its proposed mechanism and uncertainty without claiming confirmation.
For a nontrivial mechanism, explain the problem, show a concrete example or trace, then explain the solution and its invariant.
Introduce one conceptual layer at a time, with plain-language meaning before notation and a worked example before an algorithm when useful.
Preserve deliberate concrete-to-general development.
A reader may understand a particular case before learning the broader concept or its name.
Before recommending an earlier definition, identify what the reader cannot understand at that point without it; needing the concept later does not establish that it belongs earlier.
Explain why a schema or invariant exists before listing its fields.
Do not force every artifact into a design-document progression or require a worked example of every application.

Give a thought room to develop.
Joining sentences or packing definitions together can preserve facts while making their connections harder to follow.
Concision makes good use of attention; it need not mean compressing the prose.
Use the space that helps the reader follow, without rewarding either length or brevity on its own.

For important measurements, identify the population or denominator, what was counted, input revision or time range, method, and limitations.
Explain what the number demonstrates and whether it is provisional or an acceptance constant.
Comparisons need comparable results for the alternatives, not merely a winning conclusion.
Use labeled tables or definition lists rather than an uninterrupted wall of figures.
Avoid wide Markdown tables; use bullets or short subsections for prose, commands, or more than three columns.

## 3. Revise connected passages without losing meaning

Identify the reading problem before choosing edits: a buried relationship needs different work from an awkward sentence.
Develop a connected explanation before polishing its sentences; do not inherit the source's sentence order as the revision's plan.
Revise connected passages when selection or arrangement causes the difficulty; retain what already works.
Judge diction, rhythm, emphasis, selection, and development, not words removed or paragraphs joined.
Words can earn attention through emphasis, rhythm, tone, or a needed connection, not only by adding facts.
Cut explanatory padding too: a second paraphrase needs a purpose beyond being another way to say the same thing.

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles