# 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.