Stop making reviewers excavate your chat history

.agents/skills/repo-prose/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: repo-prose
+description: Write or review repository prose and technical reports that make sense without conversation or development history. Apply to documentation, code prose, commits, PRs, issue comments, plans, and agent reports.
+---
+
+# Write Without Hidden Context
+
+All repository prose must make sense to a technically capable reader who has the
+repository but none of the conversation or development history. Apply this skill
+to documentation, comments, docstrings, names, errors, commit and PR text, issue
+and review comments, plans, progress messages, handoffs, and completion reports.
+
+- Describe the system as it exists. State its purpose, behavior, invariants,
+  interfaces, evidence, and limitations directly. Do not narrate the journey.
+- Do not use lifecycle labels as identities: `Phase 2`, `pilot`, `next`,
+  `current`, `new`, `old`, `latest`, and similar terms are not technical names.
+- Do not use false definite references. Phrases such as `the 1M-token capture`,
+  `the experiment`, or `this approach` require a locally introduced, unambiguous
+  referent. Counts, dates, and versions are attributes, not identities.
+- On first reference, give the object's semantic role and, when relevant, its
+  durable identifier: artifact name, path, schema, revision, manifest, or hash.
+- Explain concepts before identifiers. Do not make internal codenames,
+  experiment labels, profile numbers, implementation shorthand, or names such
+  as `XOR-Cheb-T12` the vocabulary of the design. Mention literal identifiers
+  only after describing what they mean and only when the reader needs them.
+- Canonical documentation is a present-state specification, not a changelog.
+  Replace stale claims instead of layering history on top. Put chronology,
+  rejected attempts, and retrospectives only in explicitly historical documents.
+- Distinguish implementation from qualification. Where support or readiness
+  matters, state what is implemented and the conditions under which it is
+  qualified; identify research-only or unsupported behavior explicitly. An
+  implementation or passing test suite does not establish support for untested
+  workloads.
+- State evidence as conditions, measurement, result, and conclusion. Identify
+  the tested artifact and relevant configuration, separate measurements from
+  hypotheses, and disclose missing hardware, inputs, and unrun checks.
+- Comments explain invariants, intent, and non-obvious constraints, never change
+  history. TODOs name the missing condition and the criterion for removal.
+- Commits and PRs state the problem, resulting behavior, technical reason,
+  compatibility impact, and validation relevant to the change. They do not
+  recount attempts or pivots. Scale detail to the change; a small correction
+  does not need a full report.
+- State the substantive fact, requirement, assumption, or limitation directly.
+  Do not add commentary about why a statement is present or how the author
+  wants the reader to interpret it.
+
+## Review before publishing
+
+Read the final text as a reader without the development conversation. Check that
+the affected component, behavior, and evidence can be understood from the text
+and its explicit references. Rewrite unexplained references and claims that
+exceed the evidence before committing, posting, or sending the result. Review
+revised PR titles and descriptions as well as the text accompanying code changes.
+
+When reporting a prose defect, quote the passage, identify the missing context
+or unsupported claim, and describe the information needed to repair it. Supply
+a rewrite when the facts are known; do not invent details to make it sound
+complete. Judge meaning, not the presence of individual words on a banned list.
+
+Illustrative rewrites:
+
+| Requires hidden context | States the behavior or evidence |
+|---|---|
+| "The new path fixes the capture issue." | "Mixed speculative export preserves separate hidden-state and sampling buffers, allowing Qwen graph construction to complete." |
+| "Phase 2 removes the duplicate buffers." | "Dense Qwen graph variants share scratch storage because their executions are serialized." |
+| "All tests passed; ready to ship." | "The GPU regression suite passed on SM120. Tensor-parallel execution has not been tested." |
+
+Use these forms only when the implementation and evidence support the statements.
+
+Final test: if understanding any sentence requires "you had to be there,"
+rewrite it.
+
+## Delegation and reports
+
+- Include this skill's resolved absolute path in each delegated assignment and
+  require the delegate to read and follow it for progress messages, findings,
+  completion reports, and handoffs. Pass the requirement to further delegates.
+- Supply the task context and relevant artifacts explicitly. A skill reference
+  does not replace the context needed to do the work.
+- Lead reports with the result and its practical consequence. Identify the
+  affected component or artifact, provide supporting evidence, and distinguish
+  applied changes from proposals and executed checks from planned checks.
+- Use ordinary readable sentences. Keep spaces around words and numbers; do
+  not compress reports into concatenated tokens or unexplained abbreviations.
+- Resolve ambiguous references and unsupported conclusions in returned reports
+  before incorporating them into documentation, decisions, or published text.

AGENTS.md

@@ -9,16 +9,37 @@ Heliopause depend on Helios; Helios has no Python or preparation-tool dependency
 
 ## Required setup and commit review
 
-On entering a clone or worktree, and after pulling changes, re-read this file and
-[the design self-review](docs/design-review.md). Before committing, ensure the
-repository's `.githooks/commit-msg` hook is enabled by following that document's
-installation instructions. Preserve any existing active hooks when installing.
+On entering a clone or worktree, and after pulling changes, re-read this file,
+[the design self-review](docs/design-review.md), and
+[the repository prose skill](.agents/skills/repo-prose/SKILL.md). Before committing,
+enable the repository's `.githooks/commit-msg` hook by following the
+[hook installation instructions](docs/design-review.md#hook-installation).
+Preserve any existing active hooks when installing.
 
 Before every commit, follow the staged-diff review and acknowledgment instructions
 in `docs/design-review.md`. A rejected acknowledgment requires reading that
 document and reviewing the staged change before retrying; do not treat the
 rejection as a formatting repair.
 
+## Required prose review
+
+Before writing or reviewing repository prose, read and apply
+[the repository prose skill](.agents/skills/repo-prose/SKILL.md). It applies to
+documentation, code comments, docstrings, names, errors, commit messages, PR titles
+and descriptions, issue and review comments, plans, and technical reports. Code
+tasks are included whenever they produce prose, including progress messages and
+completion reports.
+
+Before committing or publishing, review the final text against the skill. Rewrite
+passages that require conversation history, introduce unexplained identifiers, or
+claim results beyond the stated evidence. Review edited PR descriptions and
+comments before publishing them, even when no repository files change.
+
+Every delegated task must include the skill's resolved absolute path and require
+the delegate to read and follow it. Pass this requirement to further delegates,
+and review returned prose before incorporating or publishing it. A review
+acknowledgment does not substitute for reading the skill and reviewing the text.
+
 ## Contribution scope and rejection criteria
 
 Flare prepares and serves supported model recipes on NVIDIA GPUs through

docs/design-review.md

@@ -130,6 +130,14 @@ before committing; a design acknowledgment cannot authorize them.
     behavior, weaken numerical or lifetime contracts, or shift model computation
     or policy across the preparation/runtime boundary. Do not make a violating
     contribution acceptable by weakening its governing rule.
+16. **Write without hidden context.** Read and apply the
+    [repository prose skill](../.agents/skills/repo-prose/SKILL.md). Review changed
+    prose and the final commit message for an audience without the development
+    conversation. Reject descriptions whose affected component, resulting
+    behavior, or supporting evidence depends on unexplained references or
+    development history. Identify the missing context or unsupported claim and
+    rewrite it before committing. PR descriptions, comments, and agent reports
+    require the same review before publication.
 
 ## Review and acknowledgment
 
@@ -139,6 +147,9 @@ before committing; a design acknowledgment cannot authorize them.
    apply to the affected behavior; documentation changes do not require GPU tests.
 2. Read the staged checklist with `git show :docs/design-review.md`. When changing
    this document, stage the intended version before reviewing and acknowledging it.
+   Also read the staged prose skill with
+   `git show :.agents/skills/repo-prose/SKILL.md` and apply it to the staged prose
+   and final commit message.
 3. Compute SHA-256 over the exact staged document bytes and take its first two
    bytes as four lowercase hex characters:
 
@@ -160,9 +171,10 @@ before committing; a design acknowledgment cannot authorize them.
    ```
 
    Use the reviewing agent's name and model, or the human reviewer's identity.
-   The acknowledgment means: **I read the staged checklist, reviewed the staged
-   diff against every applicable principle, found no unapproved design violations,
-   and accurately disclosed validation and material limitations.**
+   The acknowledgment means: **I read the staged checklist and prose skill,
+   reviewed the staged diff and final commit message against every applicable
+   principle, found no unapproved design violations, and accurately disclosed
+   validation and material limitations.**
 
 Read and review before acknowledging. Do not automatically insert the footer or
 copy an acknowledgment from another commit. A missing or rejected acknowledgment