---
name: check-readme
description: Review and improve the README of the current project. Use when the user asks to check, audit, verify or update a README, especially when correctness against the public API matters.
---

Review and improve the README of the current project.

**Goal:** a README that is **correct, precise, complete and brief** (in that order).

## Phase 1: Gather context

1. **Read the README** end to end.
2. **Read the public API** to ground every claim against real code:
   - Swift package: `Sources/`, public types, doc comments, `Package.swift`.
   - Other languages: equivalent entry points and exported surfaces.
3. **Cross-check every code sample** in the README:
   - Do type and method names match the current code?
   - Do the samples follow the patterns recommended in doc comments?
4. **Verify all internal links and paths** resolve (demo folders, screenshots, anchor links).

## Phase 2: Analyse

Complete the full analysis before presenting anything. Check every claim against each category:

**Correctness** — every claim matches the code:
- Public API names, signatures and observable behavior.
- Error handling: which paths trap, which recover.
- Isolation and concurrency guarantees.
- Platform / OS / language version requirements.
- Test and preview affordances.
- When overrides or resets are allowed.

**Spelling and grammar**

**Ambiguity** — flag anything open to misinterpretation.

**Completeness** — the README lists, at minimum:
- Every public feature. Exception: for packages of independent utilities with no shared architecture, prefer generic section summaries over listing every public type. Feature discoverability is left to the API documentation.
- Every non-obvious limitation that would surprise a new user.
- Every design choice that explains *why* a feature behaves the way it does (locking strategy, lifetime model, error policy, isolation guarantees, lifecycle/scoping rules, etc.).
- The smallest example needed to use each feature.
- Platform / OS / language version / package dependencies requirements stated in the README body (not only in badges).

**Brevity** — as short as possible while keeping all of the above:
- Prefer bullets over prose where it shortens without losing nuance.
- Drop filler ("simple", "easy", "powerful") unless backed by a concrete claim.
- Combine examples that demonstrate the same idea.
- No marketing voice and no emojis unless already used.

## Phase 3: Present findings

Present findings using the standard format defined in AGENTS.md.

When done, suggest running `/reflect` to capture any process improvements from the session.

## Constraints

- Do not invent features. If a behavior is unclear from code, ask before documenting.
- Do not remove badges, links, or licensing references unless they're broken or outdated.
- Keep tone consistent with the existing README.
- Do not introduce a "we" voice or first-person perspective unless already used.
- Do not remove TODO/FIXME items. Preserve them as in source code unless explicitly asked to remove.