arch3rPro/dsh-skills / skills/documentation/prose-standard
prose-standard
VerifiedWrite prose that preserves every contract while deleting reasoning transcripts, repetition, and decoration — across comments, JSDoc, docs, prompts, diagnostics, and user-visible strings. Use when writing, reviewing, trimming, restoring, or auditing prose, or deciding where documentation or a comment is required. It owns two rules: preserve the complete proposition, and never let an authoring-session vantage leak into durable text.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| agents/openai.yaml | config | 338 B |
SKILL.md
View on GitHub---
name: prose-standard
description: "Write prose that preserves every contract while deleting reasoning transcripts, repetition, and decoration — across comments, JSDoc, docs, prompts, diagnostics, and user-visible strings. Use when writing, reviewing, trimming, restoring, or auditing prose, or deciding where documentation or a comment is required. It owns two rules: preserve the complete proposition, and never let an authoring-session vantage leak into durable text."
---
# Prose Standard
Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. A **contract** is an obligation, invariant, precondition, postcondition, or compatibility promise that a caller, callee, implementer, producer, or consumer relies on. This skill owns editorial judgment and required prose coverage; it applies to any document or string an agent or human reads — comments, JSDoc, docs, prompts, diagnostics, and visible UI strings.
**The defining constraint:** a smaller word count is never the goal by itself. The goal is *every factual clause preserved, nothing more*. Trim or add as the proposition demands.
## Preserve the complete proposition
Before editing a passage, enumerate every proposition it carries. Preserve each relevant:
- actor and action;
- condition, timing, and ordering;
- modality — *must*, *may*, *never*;
- negative guarantee and exception;
- ownership, side effect, failure mode, and consequence.
Remove adjectives, repetition, and narration only when every factual clause survives and the result is clearer. A smaller word count alone is not an improvement. Do not weaken a proposition to make progress.
## Required coverage by location
This is not a one-way shortening pass — add prose where code and structure do not communicate a required contract.
- **Public API docs:** document caller-visible return distinctions, throws or rejections, side effects, ownership, timing, cancellation, and durability.
- **Internal comments:** orient non-local structure and obviously complicated local structure — invariants, race ordering, ownership, security boundaries, surprising failure. Delete control-flow narration and code restatement.
- **Module comments:** state the module's role, dependencies, responsibilities, and non-obvious architecture choices; link choices to their rationale.
- **Tests:** explain only non-obvious test design — why a fixture, an assertion, or an indirect observation is necessary. Delete walkthroughs.
- **READMEs / package docs:** include the consumer contract — configuration, semantics, failures, limitations, extension points.
- **Prompts and visible strings:** treat wording as behavior; inspect generated output and run behavior validation, or state why no check applies.
- **Diagnostics:** name the failing subject or path, the violated rule, and the correction when non-obvious. Remove internal execution narration.
## Never let an authoring-session vantage leak in
Durable prose states the current state from the repository's vantage — never the authoring session's. A reader at the latest state, with no access to any transcript, PR thread, or uncommitted draft, must be able to resolve every reference and verify every claim. In practice:
- **State the present, not the history.** Avoid "previously", "now", "no longer", "used to", "renamed", "was moved". State the current mechanism; put change stories in commits and change descriptions, not in durable prose.
- **No review or PR vantage.** No "a later PR in this stack", "this PR adds", "rejected in review", "the reviewer confirmed". State the shipped mechanism or extension point.
- **No reasoning transcript.** No step-by-step derivation, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
- **No hedges or planning residue.** "Probably fine for now", "should be enough" — promote to a tracked marker or restate as the actual bound; delete the hedge.
## Name the exact subject
Write directly: name actors and facts. Before writing a vague abstraction (*contract*, *boundary*, *shape*, *surface*, *gate*), ask whether a more exact term names the subject — *response fields*, *JSON validation*, *ESM exports*. Keep a term when it names the exact technical subject. Do not narrate control flow or tests, preserve review history, or restate code.
## One home per fact
State a fact in exactly one place; elsewhere, link. The same rationale repeated beside sibling methods keeps one home. Grep a distinctive phrase to find duplicates and replace copies with links.
## Workflow
1. **Scope the passage.** Confirm what is in scope and what the document or string must communicate.
2. **Enumerate the propositions** before touching anything; keep each relevant clause.
3. **Classify each candidate** as keep, add, trim, restore, or defer — and apply clear changes only when the task authorizes edits.
4. **Check for session-vantage leakage** and restate surviving facts from the repository's vantage.
5. **Verify the result** against the owning code or behavior; confirm no proposition was dropped.
## Completion criteria
- Every proposition that matters is preserved; nothing added or dropped.
- The passage states the current state, with no history, review, or reasoning-transcript vantage.
- Every abstraction is checked against a more exact term; the precise subject is named.
- Each fact has one home; duplicates are links.
- Visible strings and prompts are treated as behavior, not decoration.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |