| name | readme-critique |
| description | High-judgment whole-document review for shape, pedagogy, and design-rationale. Catches the catalog-vs-teaching, composition-vs-enumeration, running-domain-vs-ad-hoc failure modes that readme-verify's gates pass on. Runs between draft and verify. |
| argument-hint | <readme-path> <source-analysis-path> [exemplar-path] |
readme-critique
The verify gates check coverage (Gate 4), self-consistency (Gates 1-2), and skim-experience (Gate 3). They pass on READMEs that are internally consistent and complete-by-name but that read as catalogs rather than teaching. This skill is the gestalt judge that the verify gates cannot be.
readme-critique runs AFTER readme-draft (or after readme-edit) and BEFORE readme-verify. Its job: read the candidate top to bottom as a real reader would, and report along eight axes whether the README teaches or merely lists.
Inputs
readme_path: the candidate README.source_analysis_path: the analyzer's output (includes the section-cluster output and the running-domain seeds — this is the contract the draft was supposed to follow).exemplar_path (optional): a reference README to compare against (typically git show origin/main:<module>/README.md for kyo modules).
The eight axes
For each axis, report PASS | WEAK | FAIL with line evidence.
Axis 1: Opening hook size and shape
Count the lines of the first fenced scala block in the README (the opening hook, between the opening and closing triple-backticks). It must be ≤15 lines and demonstrate ONE compelling thing on ONE running value. Or: no opening code block at all (spine prose alone hooks the reader). Comprehensive multi-capability examples belong in a ## Putting it together (or similar) section near the END of the README, after the cluster sections.
- PASS: ≤15-line opening block doing one verb on one value, OR no opening code block at all (spine paragraphs only).
- WEAK: 16-25 line opening block, OR a smaller block but with two unrelated capabilities crammed in.
- FAIL: 26+ line opening block, OR multi-capability "tour of the module" with
// section heading comments dividing sub-blocks at the top.
Rationale: walls of code at the top get skimmed past or close the README entirely. A short hook gets the reader committed; the comprehensive composition example survives, but moves to a final section where motivated readers will find it.
Axis 2: Running domain
Count distinct case-class declarations in the README, excluding sealed-trait variants. For a typical kyo module with a non-trivial domain (Schema, HTTP, flow), this should be at most 3 (one main value + one or two helpers).
- PASS: ≤ 3 distinct case classes; the main one appears in 5+ sections.
- WEAK: 4-6 distinct case classes; some clustering of reuse.
- FAIL: 7+ distinct case classes; every section introduces its own. Per-section ad-hoc domain.
For modules whose primary domain is genuinely diverse (e.g. a JSON parser README touching many shapes), this axis can be marked n/a. Justify the n/a.
Axis 3: Section names — use vs API
Walk every ## heading. For each, classify:
- Use name (gerund or noun phrase about what the reader is doing or the conceptual group): "Comparison and Mutation", "Construction", "Custom Formats", "Routes and handlers", "Cross-platform behavior".
- API name (singular noun matching a public name in the inventory): "Modify", "HttpRoute", "Json", "Compare", "Schema", "Builder".
- API name with suffix: "Modify: batched mutation", "HttpRoute: typed contracts". Still API-named.
Compute the ratio. PASS if ≥70% are use-named; WEAK if 40-69%; FAIL if <40%.
Exception: sections that are genuinely a single API with no cluster siblings (e.g. "Validation" when validation is one method) get a pass either way.
Axis 4: Section openers — WHY vs WHAT
Sample 5 random ## and ### sections (or all of them if there are <10). For each, classify the first sentence:
Compute ratio. PASS if ≥60% WHY; WEAK if 30-59%; FAIL if <30%.
Axis 5: Cluster grouping
Read the ## Section clusters block from the source-analysis output. For each cluster, check the README:
- Does the cluster's APIs appear together in one
## section, with each API as a ### sub-section?
- Or are the APIs split into separate
## sections at the top level?
PASS if all clusters are grouped; WEAK if some are grouped some are split; FAIL if no clustering applied (one section per API).
Axis 6: Cross-API teaching paragraphs
Read the source-analysis Step 6 cross-API callouts (entries with two file:line anchors) plus the cluster siblings. For each pair, check whether the README has an explicit "when to use which" paragraph somewhere.
Specific seam pairs that MUST be addressed when both APIs are documented:
Focus.set/update vs Modify (one-shot vs batched)Compare vs Changeset (in-memory vs serializable)Json.encode(value) vs transformedSchema.encode[Json](value) (ambient summoning vs transformed instance — implicit-summoning gotcha)withConfig(value) vs withConfig(f) (replace vs stack)body-only vs *Response methods (auto-fail vs raw response)
Count cross-API paragraphs found ÷ cross-API paragraphs needed. PASS if ≥80%; WEAK if 40-79%; FAIL if <40%.
Axis 7: Design rationale woven in
Sample 5 random ## sections (or all if there are <10). For each, count paragraphs that include reasoning words: because, unlike, compared to, the alternative, this means, so that, to avoid, the reason. Sections that contain at least one such paragraph (excluding > **Caution:** callouts which don't count) pass.
Threshold: ≥50% of sampled sections contain a rationale paragraph. PASS, WEAK, FAIL.
Axis 8: Reader's discovery path
Read ONLY the ## headings of the README, in order. Do they tell a coherent story that a skim reader could form a mental model from?
- : Headings form a curriculum arc — opening → first call → core capabilities (grouped) → advanced surfaces → operational concerns. A reader scanning only headings learns the design.
