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