Skip to content

Rewrite sessions-commands-events in a direct, guide-appropriate voice - #152

Merged
mmacy merged 2 commits into
mainfrom
rewrite-sessions-commands-events
Oct 15, 2026
Merged

mmacy merged 2 commits into
mainfrom
rewrite-sessions-commands-events

Conversation

@mmacy

@mmacy mmacy commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Two prose-only passes over docs/guides/sessions-commands-events.md. No code block changed: every fenced block is byte-identical to main (verified by diffing extracted fences against origin/main).

Pass 1 — voice rewrite (declaw)

Cut the AI-voice tells while keeping the guide-interior register:

  • Design justifications and asides the text already states: "A rejected command is a normal outcome, not a failure", "A referee correcting the world doesn't stop just because the party fell...", "because an objective the party finished is one the party can be told about", "One asymmetry is deliberate", "For the same reason... which is why a hand-driven completion grants nothing", "That's the additive-schema guarantee in practice" (the contract is named in determinism-saves-replay.md), the "referee typo" rationale, "isn't even worth a typed exception", "None of these are in-fiction outcomes. They tell you...".
  • Hedge/filler: "not a side effect", "deliberately tolerant", "on purpose", "A handful", the coined "validate-then-mutate" label, "It's total and pure" -> "It never raises".
  • Metaphor/throat-clearing: "The modes form a loop with two ways out" removed.
  • Over-explained restatements compressed ("contains exactly the facts" -> "carrying the facts"; "which is what makes X answerable" -> "so X is answerable").

Kept as deliberate terminology: headings and anchors, the quoted example questions ("why did the party get that item?", "has this session ended?"), exactly one entrance, spawn as the name of the command family.

Pass 2 — concision (subagent pass, reviewed)

Merged sentences that restated the same fact (the "exactly one way to mutate" guarantee, the untouched-session/only-clears-every-check pair, "a lost battle is not the only way" into the game_over sentence) and cut flabby constructions ("previously-dumped", "what the visibility field means", "for how you author", double "with... with the clock"). No fact added, dropped, or altered; all API names, codes, links, and anchors intact.

One deviation from the pass brief, flagged for review: "seven referee commands" became "a family of referee commands" — AGENTS.md forbids numeric surface counts in prose, and the sibling listeners-and-flags page states the same partition without a total. The count is derivable from the "Three of them... the other four" partition that follows.

Verification

  • Fenced blocks diffed against origin/main: identical
  • uv run pytest tests/test_docs_examples.py — 319 passed, 73 skipped (no-run blocks)
  • uv run mkdocs build --strict — clean

Review locally at http://127.0.0.1:8001/osrlib-python/guides/sessions-commands-events/ (mkdocs serve with livereload is running).

mmacy and others added 2 commits October 14, 2026 19:45
Prose-only pass over docs/guides/sessions-commands-events.md: cut AI-voice
tells (design justifications, over-explained restatements, hedging, the
coined "validate-then-mutate" label, "total and pure") while keeping the
guide-interior register. No code block changed; every fenced block is
byte-identical to HEAD.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
Second pass on docs/guides/sessions-commands-events.md, focused on
concision without changing technical meaning: merged sentences that
restated the same fact, cut flabby constructions, and dropped one
numeric surface count ("seven referee commands") per AGENTS.md's
no-counts-in-prose convention. Prose only; every fenced block remains
byte-identical to origin/main.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
@mmacy
mmacy merged commit d806fda into main Oct 15, 2026
5 checks passed
@mmacy
mmacy deleted the rewrite-sessions-commands-events branch October 15, 2026 03:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant