agentleFS
inclusionAIinclusionAI/Choruz/.agents/skills/choruz-prose-standard/SKILL.md

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.

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
  1. Very specific:

    Always exclude from discovery, review and edits: services/choruz-pipeline/src/instructions_fixtures/ (frozen compatibility fixtures), …

    line 18
  2. Distinctive:

    Treat generated artifacts and recorded expectations as derivative.

    line 20
  3. Distinctive:

    Before editing, identify every proposition in the passage.

    line 24
  4. Distinctive:

    Remove adjectives, repetition and narration only when every factual clause survives and the result is clearer.

    line 26
  5. Distinctive:

    Keep a complete local contract at the point of use.

    line 28
  6. Very specific:

    Rust public items: document caller-visible error variants, side effects, ownership, cancellation, ordering guarantees (server_seq, …

    line 34
  7. Distinctive:

    UI strings: treat text, accessibility names, tooltips and placeholders together.

    line 44
  8. Distinctive:

    Read the owning code or document before judging a passage.

    line 51
  9. Distinctive:

    Update the owner before derivative artifacts.

    line 54
  10. Very specific:

    Run the narrow relevant checks (cargo doc warnings for Rust doc comments, pnpm web:check, the instruction tests for templates, python3 …

    line 55

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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. A pub fn with 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 or localStorage, 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

  1. Confirm the scope, the branch or PR base, and the applicable AGENTS.md.
  2. Read the owning code or document before judging a passage.
  3. Inspect the requested scope, not only the largest files. Use git grep and word counts to find candidates, then judge passages semantically.
  4. 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.
  5. Update the owner before derivative artifacts. Re-check analogous passages after learning a new rule.
  6. Run the narrow relevant checks (cargo doc warnings for Rust doc comments, pnpm web:check, the instruction tests for templates, python3 scripts/verify_agent_notes.py for notes) and git diff --check.
  7. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.