Moai Workflow Docs Claim Check

Documentation Claim Check

Assess whether the statements a public-facing document makes are actually supported by the evidence supplied alongside it. The assessment reads, judges, and reports. It changes nothing and runs nothing.

Typical subjects: a README, a release note, an install guide, a quickstart, a migration note, a feature or compatibility table.

Hard boundaries

Three boundaries are absolute. They hold even when the request asks for more; in that case perform the assessment and decline the rest in Boundary Notes.

1. No command execution. Do not run builds, tests, package managers, linters, network requests, or any shell command as part of the assessment. When a claim can only be settled by running something, name the exact command and the file it should run against and label the claim needs-human. Naming the command is the deliverable; running it is not.
2. No fixes. Do not produce patches, diffs, rewritten passages, or file edits. Describe what a maintainer would change and where, then stop.
3. No code review and no security review. Do not assess code quality, architecture, performance, or vulnerabilities. If asked, state the boundary in Boundary Notes and continue with the claim assessment only.

Opening the files the user pointed at, to locate the evidence they supplied, is in scope — that is reading, not executing.

Phase 1 — Preflight

Complete all three steps before triaging a single claim. If a step cannot be completed, report that and stop rather than guessing.

1. Confirm the document is public-facing. This skill judges documents written for users of the software: README, release notes, install and usage guides, published site pages. Internal design notes, task trackers, and private runbooks are out of scope — say so and stop.
2. Inventory the supplied evidence. For every item record what it is, where it came from, its version identifier, and its timestamp. An item with neither is still usable, but record it as undated: it cannot later support a freshness judgment.
3. Flag secrets for redaction before proceeding. Scan the supplied evidence for credentials, tokens, private keys, connection strings, and personal data. On a hit, flag the location for redaction, never reproduce the secret in any output, and continue only once a redacted copy is available.

Phase 2 — Claim Triage

Turn the document into an inventory of atomic claims.

Extract. Walk the document and pull out every statement that asserts something checkable about the software: supported platforms and versions, install and usage steps, defaults, limits, guarantees, availability, counts.

Decompose composite claims. A composite claim bundles several independently-checkable assertions into one sentence. Split it so that each atomic claim carries exactly one assertion and therefore receives exactly one label. A sentence that would otherwise need two labels is not yet atomic.

"Installs with a single command on macOS and Linux" splits into three atomic claims: single-command install, macOS support, Linux support. Each is evidenced — and can fail — independently.

Set aside the subjective. Statements of taste or ambition ("fast", "developer-friendly", "production-grade") cannot be checked against evidence. Exclude them from labeling and list them under Input Scope Reviewed with a one-line reason. When a subjective adjective wraps a checkable core, split it: label the core, exclude the adjective.

Bind evidence. For each atomic claim, note which supplied evidence items bear on it — or record that none does.

Phase 3 — Validation

Assign exactly one label to every atomic claim by walking the ordered decision tree. Stop at the first gate that fires; do not re-open an earlier gate.

needs-human  ->  stale-suspected  ->  verified  ->  unsupported

unsupported always carries exactly one reason:

Anchoring rules: every verified names its evidence anchor; every stale-suspected names the mismatched field and both values; every needs-human names the command or file that would settle it; every unsupported carries its reason.

Gate criteria in full, tie-breaks between adjacent gates, and a claim-type table live in references/label-decision-tree.md. Worked end-to-end assessments live in references/worked-examples.md.

Output contract

Emit exactly these three sections, in this order, every time — including when the claim inventory is empty.