Skip to content

Rewrite the README in plain English - #14

Merged
pedro-pscunha merged 2 commits into
mainfrom
docs/readme-simple-english
Sep 22, 2026
Merged

pedro-pscunha merged 2 commits into
mainfrom
docs/readme-simple-english

Conversation

@pedro-pscunha

@pedro-pscunha pedro-pscunha commented Sep 22, 2026 •

Copy link
Copy Markdown
Owner

What changed

The README is rewritten in plain English (the simple-english skill, pragmatic mode). It now
follows the heading order and the glossary that the three guideme SDKs share: one word for one
meaning ("question", "answer", "option", "level", "rubric", "unsure", "setting", "state"), short
sentences, no semicolons outside the rendered rubric, and conditions before commands.

New heading order: Install, Quick start, Questions, When the model is not sure, Examples and
counterexamples, Several questions in one request, The receipt, Errors, Retries and timeouts,
Testing your code, Observability, Configuration, Sync and async, Lower layers, Other SDKs,
Development, License.

  • Every Python block is unchanged, so tests/typing/readme.py still mirrors the first example
    and the other blocks it copies.
  • Every name in guideme.__all__ is still inside code (tests/test_surface.py).
  • Lower layers keeps the second-tier semver promise (guideme.api, guideme.api.client,
    guideme.policy).
  • Other SDKs has three rows. The TypeScript row links the repository only and says
    "@guideme/sdk (not yet on npm)".
  • All links stay absolute, because the README is the PyPI long description.
  • The retry and timeout rules move out of Errors and Configuration into their own section.

What moved where

  • The measured 0.75 / 0.17 criteria case, why no timeout is resent, why a transport refuses a
    timeout, and the two Usage classes: already in docs/design.md. The README links them.
  • Why Client sits in guideme.api.client: new bullet in docs/design.md, Sharp edges.
  • The sdist test command: CONTRIBUTING.md, The loop.
  • The checker set, the test style, the live tests and the hooks: already in AGENTS.md.

Other files

  • CONTRIBUTING.md: the tier list drops guideme.question.Question, which AGENTS.md moved
    to the top-level list, and names guideme.api.client.
  • docs/contract.md: one reference renamed. The timeout divergence is now in the README's
    Retries and timeouts section. No new prose.
  • CHANGELOG.md: an Unreleased → Documentation note. No version bump. The PyPI 0.2.0 page
    keeps the old README until the next release.

Length

README: 568 lines before, 503 after the review fixes. Code blocks: 127 lines before, 121 after.
The shared target was "at most about 320". The review accepted about 470 as the honest length
of one file, because the code blocks are tied to the typing mirror and the rubric contract.

How I verified it

  • Every behavioural claim was checked against src/guideme/**: builder defaults and refusals
    (guide.py), retry and resend rules (api/client.py), rubric rules (enums.py,
    question.py), state serialization (_json.py), receipt and error fields.
  • A claim ledger maps each factual sentence of the old README to its new line, a docs/
    line, or a reason it was dropped. Three rows are dropped, all framing text with no user fact.
  • rg -n -i readme over the repository: every hit that names a heading or a block was checked,
    and docs/contract.md was updated.
  • The pre-push hook ran the full mise run check: ruff, pyright (0 errors), pylint (10.00),
    pytest (230 passed), build and audit.

Review fixes (second commit)

An opus review found 0 Critical, 4 Major and 17 Minor items. All are applied:

  • The quick start defines the state, the three constructors, the level order and "unsure".
  • The policy layers list the setter for each kind of question again.
  • The score value states its scale, from the TypeSafe API docs.
  • The base_url row says that guideme follows redirects.
  • The error rows now list the missing TransportError and ConfigError cases.
  • The typing notes moved to Lower layers.
  • Testing points to the retry rules in place of repeating them.
  • The spec-vendoring lines left Other SDKs.

The README mixed three readers (a new user, a user tuning policy, a
contributor) and used long sentences and shifting terms, so a first
read was hard. It now follows the heading order and glossary that
every guideme SDK shares, in short sentences with one word per
meaning, and lists the TypeScript SDK under Other SDKs.

Design rationale and measurements leave the README for
docs/design.md, where most of them already lived; the one missing
reason (why Client sits in guideme.api.client) is added there. The
sdist test note moves to CONTRIBUTING.md, whose tier list also drops
guideme.question.Question, which AGENTS.md moved to the top list.
docs/contract.md points at the section that now carries the timeout
divergence. Code blocks are unchanged, so tests/typing/readme.py still
mirrors the first example.
The review found places where a first read still stalled. The quick
start used ticket, noul and the fallback before saying what they are,
and it did not say that levels are ordered by declaration. Some terms
drifted, and the ConfigError and TransportError rows missed cases.

The quick start now defines the state, the three constructors, the
level order and "unsure". The policy layers list the setter for each
kind of question again. The score value states its scale from the
TypeSafe API docs. The base_url row says that guideme follows
redirects.

Typing notes move under Lower layers, and so does the Thresholds
sentence. Testing points to the retry rules in place of repeating
them. The contributor lines on spec vendoring leave Other SDKs, and
same-topic paragraphs merge. No code block changes, so
tests/typing/readme.py still mirrors the README.
@pedro-pscunha
pedro-pscunha merged commit 81aadb7 into main Sep 22, 2026
7 checks passed
@pedro-pscunha
pedro-pscunha deleted the docs/readme-simple-english branch September 22, 2026 22:46
pedro-pscunha added a commit that referenced this pull request Sep 22, 2026
PyPI shows the README as the package's description, and it only
changes when a version is uploaded, so the rewrite in #14 is not what
a PyPI reader sees until a release carries it. This bumps the version
in pyproject.toml and both lock files, and moves the Unreleased notes
under 0.2.1. There is no code, contract or spec/ change.
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