encero-systems/incan / .agents/skills/review-docs-claims
review-docs-claims
VerifiedReview user-facing docs, CLI reference text, examples, and scaffolds for truthfulness, prose quality, and RFC leakage. Use when a broad review needs a dedicated docs/claims pass or when the user asks for docs-truth review specifically.
Review Docs Claims — Incan Compiler
Purpose
/review-docs-claims is a narrow report-only reviewer for touched user-facing documentation and examples.
Own:
- docs/CLI/examples/scaffolds claiming unimplemented behavior
- Divio page intent and public-reference completeness
- user-facing RFC leakage outside explicit inventories
- touched markdown prose quality
- release-note inventory consistency when applicable
Do not own:
- Rust comment prose
- architectural placement
- test style
- final branch-clean judgment
Output artifact
Write a slice report at:
.agents/state/review-report.docs-claims.md
Do not write to the canonical .agents/state/review-report.md.
Reference pages state the contract only
A page under a reference/ directory states the public contract and nothing else: the exact rule, the types, signatures, parameters, returns and defaults, each refusal with its stable diagnostic code, and small examples annotated with what is accepted or refused. Read every changed sentence of a reference page against the list below. Each hit is a blocker finding, even when the sentence is true, MkDocs passes, and the rest of the page is good. The fix is to delete the sentence, restate it as contract, or move it to the matching how-to (for advice) or explanation (for rationale and mechanics) page and link to it.
- Pages shaped by their history. A reference names its scope and covers every item in it, each with the same structure (for a language feature: every form, its syntax, what it matches or does, and its refusals with codes). Sections that grew one per fix or per issue, prose that covers some forms and skips others, and rules scattered across paragraphs are a blocker even when every sentence is true; rebuild the page around the surface it documents.
- Quoted diagnostic messages. The contract is the refusal and its code (
INCAN-T0001), never the message wording (Non-exhaustive match: missing patterns for _). Message text changes without notice; a reference that quotes it goes stale. - Where the implementation reaches. Lists such as "applies to the same module, imported source modules, the standard library and compiled libraries" describe coverage, not a rule. State the rule; if something is outside it, that is a limitation to fix or to state once as a rule, not an inventory.
- Implementation gaps phrased as rules. "Is not judged by this rule", "is not checked yet", "a trait's default body is not judged" expose the checker's current reach. Remove them or turn them into a stated contract.
- Compiler-internal vocabulary. Columns, pattern matrix, facts, projections, recorded identities, passes, lowering, the emitter. A reader of the language contract never meets these.
- Mechanics. How the compiler arrives at a result: how bounds are inferred ("bounds another method of the same model put there", "receives those bounds in the same way…"), how a diagnostic is formatted ("spelled with wildcard payloads…"), what the generated Rust looks like.
- Example comments that narrate. A comment on a reference example says accepted or refused and, if needed, the contract reason in a few words (
# refused: T does not declare Clone). It does not explain the mechanism (# U receives Display (from show) and Clone) or walk through an evaluation (# ("b", "a") is "other": the first alternative binds x); that walkthrough belongs on the explanation page. Every annotation must hold: check each accepted or refused example against the implementation or a test, down to the modifiers it depends on (a field withoutpubis private). - Advice and rationale. "Write X instead", "use Y when", "prefer", "because…", "so that…".
- Comparisons. With Python, Rust or any other language ("as Python spells it", "like Rust's
Display"). - Time-bound wording. "Currently", "today", "yet", "for now", "no longer", "-style message".
- Issue and RFC numbers in reference text.
Two rules apply to every change that touches a reference page, and each break is a blocker:
- Move, don't delete. A true sentence taken off a reference page moves, in the same change, to the page it belongs on: advice and task steps to the matching how-to, rationale and mechanics to the matching explanation. Check every removed line of the diff for a new home.
- The whole page. A change that touches a reference page brings the whole page to contract, not only the changed lines. Read the page end to end, not the diff.
make reference-contract-check (part of make pre-commit-fast and CI) catches the lexical part of the list above on every reference page a change touches; it cannot judge meaning, so this review still reads each page.
Workflow
- Review the touched user-facing
.mdfiles, CLI help surfaces, examples, and scaffolds assigned by the orchestrator. Identify each page's Divio intent using the repository'sAGENTS.mddocs rules: tutorial, how-to, reference, or explanation. Check the content against that intent, not just its directory. For a reference, compare its inventory against the relevant public source surface and verify signatures, parameters, returns, defaults, errors, constraints, and lookup structure. A walkthrough or overview underreference/is a finding even when every sentence is true and MkDocs passes. Then read every changed sentence of a reference page against Reference pages state the contract only below: completeness and truth are necessary but not enough. Small illustrative examples are allowed; do not require four separate pages for every feature. - Check actual implementation against the docs. Prefer the current code and current tests over optimistic prose, stale assumptions, or superseded branch history.
- RFC text is still canonical, but if the current branch deliberately diverges and the divergence is explicitly documented with a coherent reason, report that as a documented deviation rather than blindly calling it fiction.
- Flag:
- mixed or incorrect Divio intent, including task recipes or implementation narratives replacing API reference material
- any sentence on a reference page that goes beyond the contract (see Reference pages state the contract only)
- incomplete reference contracts or missing public APIs within the page's stated scope
- docs-generated fiction
- user-facing RFC references outside explicit inventory contexts
- short-prosed or mechanically chopped markdown
- stale release-note inventory for implemented user-facing work
- If behavior is out of scope, prefer correcting the docs rather than inventing implementation in the report.
Slice report shape
Keep slice reports findings-first. Do not enumerate every clean file with a full checklist. Only record:
- actual findings,
- and, optionally, a short
## Reviewed Clean Surfacessection for risky or non-obvious clean calls.
# Review Slice Report
- role: docs-claims
- worker: <agent-id or stable label>
- status: in_progress | clean | blocked
## Scope
- assigned files:
- workspaces/docs-site/docs/foo.md
## Findings
- [ ] blocker | docs | docs-generated fiction | workspaces/docs-site/docs/foo.md:76
Claims `requires-incan` is enforced today, but the branch does not implement that.
## Reviewed Clean Surfaces
- workspaces/docs-site/docs/bar.md — docs/claims reviewed; no findings
If there are no findings, say so explicitly.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |