Design Docs Review Checklist¶

Use this checklist for manual readability and information-architecture passes. It is a review aid, not an automated gate.

Reference Shape¶

Does the page lead with the rule a reader is likely looking for?
Does an active topic page use !!! status "Accepted" style page-level status instead of !!! info "Status" or a plain Status: line?
Is a pure navigation, index, backlog, or process page left without a page-level status block?
Does the local order usually follow rule, syntax/API, example, boundary/deferred status, related links?
Are lookup rules, allowed forms, visibility behavior, phase ownership, or decision matrices written as bullets or tables instead of dense prose?
Would term-to-description lists, field glossaries, phase ownership maps, or status vocabularies scan better as definition lists?
Is rationale separated from current behavior?

Can a first-time reader tell what is V1, deferred, future, invalid, or open?
Would any boundary, trap, invalid form, or open question read more clearly as a note, warning, failure, or question admonition?
Are deferred forms grouped under Boundaries, Deferred, or Future Decisions?
Are invalid or future examples introduced in prose instead of relying only on comments such as // deferred or // error?
Do rejected Catalyst examples use ct-invalid fences instead of ordinary ct fences or heavy failure admonitions?
Does deferred work link to current-scope.md when the scope map is the better canonical home?
Is a deferred idea mentioned only to mark a local V1 boundary, or has it grown into a coherent future design that should move to a CEP?
If a deferred idea needs examples, acceptance questions, semantic rules, or multiple paragraphs, should it be captured as a CEP instead of living in the active page?

Are admonitions reserved for high-signal status, clarification, warning, invalid-form, or open-question content?
Does each admonition use a precise type and short title, such as status "Working direction" or warning "Backend boundary"?
Does each status admonition title hold the status category while the body carries the descriptive status text?
Is every admonition body indented by four spaces, including bullets and fenced code blocks?
Are ordinary invalid examples left as ct-invalid code blocks rather than promoted into failure admonitions?
Would any admonition be clearer as normal prose because it contains the page's primary rule rather than a side callout?

Is there one canonical home for each concept?
Does this page link to canonical docs instead of repeating full semantics?
Are duplicated phrases or definitions intentional summaries rather than competing definitions?
Does the page avoid repeating adjacent source-form, type-system, ownership, diagnostics, or reflection rules that belong elsewhere?
If a contradiction appears, is it reported separately instead of resolved silently during an IA pass?

Has the CEP been checked against CEP Format?
Does the CEP keep future behavior out of active V1 reference docs, with active docs linking to it only for deferred scope?
Do active docs link to the CEP only where it clarifies a deferred boundary or future direction?
If a CEP changes status or direction, are stale active-doc references updated instead of leaving contradictory future guidance?

Is a README.md acting as an index or guide rather than carrying full feature semantics?
Would several link-only sections scan better as one Related Details list?
Has a broad page grown enough to split into focused subtopic files?
Are headings specific enough to avoid catch-alls such as "Miscellaneous" or "Other"?
Do headings use title case consistently, with short prepositions and articles lowercased unless first or last?

Flag paragraphs that combine several of: syntax, semantics, ownership, diagnostics, implementation notes, rationale, and deferred work.
Split long mixed-topic paragraphs before finalizing.
Keep examples short and deterministic.
Preserve existing design meaning while improving scan order.