Content
61%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A dense, project-specific reference with concrete API names, real file references, and well-signaled when-to-read navigation. It is weakened by narrative verbosity, explanations of general CRDT/Yjs concepts, and the absence of any sequenced workflow with validation checkpoints.
Suggestions
Trim or move design-history narrative (e.g., the retired 'scalar'/'prose' vocabulary and the pre-ADR-0295 row-document design) into a short 'retired patterns' note or reference file.
Cut explanations of general Yjs semantics Claude already knows (commutativity/idempotency of updates, 'Yjs is network-agnostic') and keep only the Epicenter-specific consequences.
Add a short ordered workflow for the most common task (e.g., structuring a new row: read document-design.md, declare the table, choose value vs. node fields, verify against the conformance lens) with an explicit validation step.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body carries substantial genuinely non-obvious project knowledge (ADR pointers, wire frames, compaction rules), but it also explains concepts Claude already knows ("Yjs updates are commutative and idempotent", "Yjs is network-agnostic") and includes narrative design-history prose ("There are no independent row documents. A row's content node used to live in its own top-level document...") that could be trimmed. Mostly efficient with tightening possible, matching anchor 3; not 4 because several paragraphs are justification essays rather than lean instruction. | 3 / 5 |
Actionability | Concrete API calls appear throughout ("Y.encodeStateVector(doc)", "Y.encodeStateAsUpdateV2(doc, remoteStateVector)", "doc.transact(() => { ... }, origin)", "mergeUpdatesV2") plus real file paths and a TypeScript example, so guidance is mostly executable. Not a 5 because only one code snippet exists and it is illustrative rather than copy-paste ready, and much guidance is prohibitive ('Do not add...') without a positive recipe; clearly above 3 because specifics dominate over vagueness. | 4 / 5 |
Workflow Clarity | Conditional reading directives provide a decision structure ("Read [references/document-design.md] before choosing how a new row document is structured", "Read [references/debugging.md] when a document converges to unexpected state"), but the body is organized topically rather than as a sequenced workflow, and there are no validation checkpoints or feedback loops. Matches anchor 3 (structure present, checkpoints missing); not 2 because the trigger-based navigation is coherent and unambiguous. | 3 / 5 |
Progressive Disclosure | Both referenced bundle files exist (references/document-design.md, references/debugging.md), are one level deep, and are clearly signaled with purpose and when-to-read conditions. Not a 5 because the ~190-line body inlines substantial detail (compaction mechanics, store connection rules) that could be split into further reference files; not 3 because the existing split and signaling are clean. | 4 / 5 |
Total | 14 / 20 Passed |