From 63e115ad6f49e3a58766067b16fecadb6931e2bb Mon Sep 17 00:00:00 2001 From: Jason Cook Date: Thu, 5 Nov 2026 15:34:17 -0500 Subject: [PATCH] Require prose review in agent and commit workflows Add a repository prose skill with rules and examples for writing without conversation history. Require agents to read it on entry, apply it before writing and publication, and pass it to delegates. Include staged prose and the final commit message in the existing design-review acknowledgment. Validation: skill validator and relative-link checks passed; all 18 existing commit-hook tests passed; git diff --cached --check passed. This documentation change does not alter runtime behavior. The hook checks acknowledgments, not semantic writing quality. Design-Signed-Off-By: Codex (GPT-6); design-review=4d3a Signed-off-by: Jason Cook --- .agents/skills/repo-prose/SKILL.md | 86 ++++++++++++++++++++++++++++++ AGENTS.md | 29 ++++++++-- docs/design-review.md | 18 +++++-- 3 files changed, 126 insertions(+), 7 deletions(-) create mode 100644 .agents/skills/repo-prose/SKILL.md diff --git a/.agents/skills/repo-prose/SKILL.md b/.agents/skills/repo-prose/SKILL.md new file mode 100644 index 00000000..b814254d --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index 4e106e5f..46a10718 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/design-review.md b/docs/design-review.md index e4f58fff..27816468 100644 --- a/docs/design-review.md +++ b/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