Style and Provenance

Public RFC style

Public RFCs should read as deliberate technical specifications.

• Use precise, direct language.
• Define terms before using them normatively.
• Use the selected pack's preferred names consistently.
• Prefer short sections with a clear job.
• Separate normative requirements from explanatory notes.
• Use examples only after validation or when they are clearly labeled illustrative.
• State design decisions as choices, not as discovered source facts.
• Avoid process commentary, provenance narration, and workflow self-reference.

Normative language

Use normative keywords only when an accepted claim record supports a requirement.

• MUST — required for conformance.
• MUST NOT — prohibited for conformance.
• SHOULD — recommended unless a documented reason applies.
• SHOULD NOT — discouraged unless a documented reason applies.
• MAY — permitted behavior.

Checklist for each normative sentence:

• [ ] The sentence maps to an accepted claim row.
• [ ] The requirement target is clear.
• [ ] The condition or scope is explicit.
• [ ] The consequence is testable or reviewable.
• [ ] The wording does not broaden beyond the evidence.

Examples are observed, never predicted

Public examples are not filler.

• Record the command, fixture, trace, or validation steps in evidence artifacts.
• Carry the public example into rendered output and validate from that rendered form.
• Preserve meaningful whitespace, counts, separators, and encoding details.
• Remove an example that cannot be observed, reproduced, or honestly classified as illustrative.
• Keep the evidence packet's reproduction method out of the public example unless the method itself belongs in the specification.

Provenance containment rule

Public RFCs carry the specification. Evidence artifacts carry the proof chain.

Keep the following out of public RFC text unless publication is explicitly approved:

• [ ] Source paths and locators.
• [ ] Claim IDs and matrix IDs.
• [ ] Discovery-aid query text, node IDs, edge IDs, and retrieval traces.
• [ ] Orientation-context maintenance fields.
• [ ] Scout notes.
• [ ] Prompt text and controller instructions.
• [ ] Agent names, tool names, and tool transcripts.
• [ ] Review arguments, correction history, and escalation notes.
• [ ] Internal manifest paths.
• [ ] Statements that the document is derived from source, calibrated, audited, or otherwise the product of a hidden workflow, unless a project pack explicitly requires one bounded disclosure.

Evidence artifacts should retain these details where useful for audit.

Evidence artifact style

Evidence artifacts should be compact, structured, and easy to diff.

• Use stable IDs.
• Keep one claim, finding, or correction per row or section.
• Quote only the minimum source text needed to disambiguate.
• Prefer locators and references over long excerpts.
• Record uncertainty explicitly.
• Record reviewer disposition separately from source evidence.
• Do not polish evidence artifacts into public prose.

Section pattern

Use this pattern for public sections when it fits the document:

1. Purpose of the section.
2. Definitions needed for the section.
3. Normative behavior.
4. Non-normative explanation.
5. Validated examples.
6. Edge cases and exclusions.
7. Cross-references by section title, not by internal evidence ID.

Voice self-check

Before final packaging, search the public prose for recurring defects rather than re-approving it by re-reading.

• Remove rhetorical not X but Y constructions unless the negation itself is technically necessary.
• Remove filler intensifiers such as exactly, precisely, clearly, or simply unless the counted value is itself normative.
• Replace hedging openers with the direct form.
• Reduce repeated colon-then-elaboration rhythm, connective stacks, and rule-of-three prose lists when cadence is doing more work than the technical distinction.
• Prefer plain mainstream vocabulary over coined or metaphorical jargon unless the specialist term is the one readers actually need.
• Keep statements objective; avoid narration about alternatives the writer considered.

Anti-leak review

Before final packaging, scan public deliverables for:

• [ ] Internal IDs.
• [ ] Source locators.
• [ ] Prompt language.
• [ ] Review comments.
• [ ] Tool transcripts.
• [ ] Placeholder text.
• [ ] Unsupported normative keywords.
• [ ] Evidence-only terminology.
• [ ] Workflow narration that says the source, documentation, audit, or toolchain governs the reader instead of the specification.