choruz-prose-standard
Skill1.1k starsChanged 20 days agoApache-2.0View on GitHub
Use when writing, reviewing, restoring, trimming, or auditing prose in this repository, including deciding where documentation or comments are required across Markdown, Rust doc comments, JSDoc, code and test comments, agent instruction templates, prompts, diagnostics, and CLI or UI strings.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/notes/implemented/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- choruz-archive-agent-notesSkill
- choruz-ci-test-reliabilitySkill
- choruz-code-reviewSkill
- choruz-docSkill
- choruz-find-simplificationsSkill
- choruz-merging-stacked-prsSkill
- choruz-pre-push-checksSkill
- choruz-pre-simplify-auditSkill
- choruz-prSkill
- choruz-record-demoSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
Always exclude from discovery, review and edits: services/choruz-pipeline/src/instructions_fixtures/ (frozen compatibility fixtures), …
- Distinctive: line 20
Treat generated artifacts and recorded expectations as derivative.
- Distinctive: line 24
Before editing, identify every proposition in the passage.
- Distinctive: line 26
Remove adjectives, repetition and narration only when every factual clause survives and the result is clearer.
- Distinctive: line 28
Keep a complete local contract at the point of use.
- Very specific: line 34
Rust public items: document caller-visible error variants, side effects, ownership, cancellation, ordering guarantees (server_seq, …
- Distinctive: line 44
UI strings: treat text, accessibility names, tooltips and placeholders together.
- Distinctive: line 51
Read the owning code or document before judging a passage.
- Distinctive: line 54
Update the owner before derivative artifacts.
- Very specific: line 55
Run the narrow relevant checks (cargo doc warnings for Rust doc comments, pnpm web:check, the instruction tests for templates, python3 …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Choruz 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, producer or consumer relies on. This skill owns editorial judgement and required prose coverage; choruz-doc owns placement and validation. It is guidance, not a script.
Comments describe non-obvious contracts or rationale that code cannot express; they do not restate what code already implies.
Inputs and exclusions
Require an explicit scope. If it is missing, report the required input and stop; do not infer a repository-wide scope.
Review and audit tasks report findings without editing; explicitly requested write, fix or trim tasks apply clear changes.
Always exclude from discovery, review and edits: services/choruz-pipeline/src/instructions_fixtures/ (frozen compatibility fixtures), generated build output, node_modules/, target/, and migrations/ files listed in scripts/historical-migrations.sha256 (checksum-frozen). Inspect an excluded target only to understand an inbound citation.
Treat generated artifacts and recorded expectations as derivative. Trace every consumer before editing: the doc comment on a template may also be model-visible text that a test pins. Edit the owning source first, then regenerate or re-record every derivative.
Preserve the complete proposition
Before editing, identify every proposition in the passage. 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.
Keep a complete local contract at the point of use; link the owning document for architecture, rationale, algorithms, history or extended examples. One explanation has one home; essential contract facts may repeat locally.
Required coverage by prose location
This is not a one-way shortening pass. Add or restore prose when code, types and structure do not communicate a required contract below.
- Rust public items: document caller-visible error variants, side effects, ownership, cancellation, ordering guarantees (
server_seq, idempotency) and durability. Apub fnwith a non-obvious contract has a doc comment; an obvious getter does not. - TypeScript exports (
apps/web/lib, SDKs): JSDoc for return distinctions, thrown errors, side effects on caches orlocalStorage, and timing (debounce, optimistic state). - Internal comments: orient non-local structure and obviously complicated local structure: invariants, race ordering, ownership, security and workspace boundaries, surprising failure behaviour. Delete control-flow narration and code restatement.
- Module comments: state the module's role, dependencies, responsibilities and non-obvious architecture choices, linking the choice's note.
- Tests: explain only non-obvious test design: why a fixture, an indirect observation, a parallel-safety measure or a real entry path is necessary. Delete walkthroughs and inventories.
- Agent instruction templates and prompts (
services/choruz-pipeline/src/instructions.rs,crates/choruz-host-runtime/assets/agent-templates,CLAUDE.md): wording is behaviour. Change it with the instruction tests and fixtures, and state the agent-behaviour risk in the PR. - READMEs and
docs/: the consumer contract: configuration, semantics, failures, limitations, extension points. Keep durable gaps and maintainer traps, not cleanup inventories. - Agent Notes: retain unique rationale, mechanisms, alternatives, consequences and named coverage gaps. Implemented notes state shipped reality in the present tense.
- Skills and agent instructions: behavioural guardrails and explicit scope limits ("guidance, not a checklist"). Keep the workflow concise and link its source of truth.
- Diagnostics and error messages: name the failing subject or path, the violated rule and the correction when non-obvious. Remove internal execution narration.
- UI strings: treat text, accessibility names, tooltips and placeholders together; keep a change visible in the affected e2e or component test.
Preserve searchable mechanism names and meaningful modal, temporal or negative emphasis. Normalise decorative emphasis only.
Workflow
- Confirm the scope, the branch or PR base, and the applicable
AGENTS.md. - Read the owning code or document before judging a passage.
- Inspect the requested scope, not only the largest files. Use
git grepand word counts to find candidates, then judge passages semantically. - Classify each candidate as keep, add, trim, restore, restructure or defer. Apply clear changes only when the task authorises edits; do not manufacture edits to satisfy a deletion target.
- Update the owner before derivative artifacts. Re-check analogous passages after learning a new rule.
- Run the narrow relevant checks (
cargo docwarnings for Rust doc comments,pnpm web:check, the instruction tests for templates,python3 scripts/verify_agent_notes.pyfor notes) andgit diff --check. - Report the inspected scope, clear changes, deliberate keeps, deferred cases and checks actually run.
Borderline decisions
A case is borderline only when at least two versions satisfy the complete-proposition rule but trade accepted principles. Apply clear edits when authorised and report genuine borderline cases without asking; do not weaken a proposition to make progress. When the user wants to calibrate, present two or three viable versions, recommend one, and state the factual difference.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

