Content
81%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.
Strong instructional content: the authoring loop is clearly sequenced with explicit validation checkpoints and error-recovery loops, and the guidance is concrete with specific tools, commands, and JSON snippets. The body is mostly token-efficient but carries light redundancy between sections and defers exact schemas and the full walkthrough elsewhere. Overall a well-organized overview with only minor structural improvements available.
Suggestions
Consolidate the `author.record_decision` / `author.defeat` and retcon guidance, each currently explained in both "Authoring loop" and "Core tools", into a single section to remove redundancy (conciseness).
Move the 29-tool catalog to a reference file (or trim it to the handful of tools used in the loop), keeping the body as an overview with well-signaled links (progressive_disclosure).
Inline one short copy-paste sequence with actual JSON arguments (e.g., `author.open` followed by `author.add_fact`) so common cases are executable without first consulting `tools/list` or references/first-session.md (actionability).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and assumes competence — it never explains MCP, worldbuilding, or novel-writing basics — and is dense with domain-specific guidance. Minor instances could be trimmed: `author.record_decision`/`author.defeat` policy and retcon guidance each appear in both "Authoring loop" and "Core tools", and "Contract 2.0.0 is the served contract" pins a version number inline, which the guidelines penalize outside a compatibility section. Not anchor 5 because not every token earns its place; not anchor 3 because there is no unnecessary concept explanation. | 4 / 5 |
Actionability | Provides mostly executable guidance: concrete tool names, the registration command `deloreis mcp --project <directory>`, citation JSON like `{"kind":"cited","decisions":["d-0001"],"state":"ratified"}`, and specific parameters (`expected_digest`, `layer: "certain"`). Minor gaps remain — exact tool schemas are deferred to `tools/list` and the complete first walkthrough to references/first-session.md — so it falls short of anchor 5's fully copy-paste-ready coverage of common cases. | 4 / 5 |
Workflow Clarity | The five-step "Authoring loop" is clearly sequenced (open → typed operations → decisions → inspect → materialize/discard) with explicit validation checkpoints: "Check the returned findings even if the call itself succeeded", "`author.materialize`... It refuses errors", digest-freshness handling, and "Unknown citations are errors". Feedback loops for error recovery are present (repair mechanical errors, `author.discard`, escalate conflicts to the user's rulings), matching anchor 5 rather than anchor 4's "minor validation gaps". | 5 / 5 |
Progressive Disclosure | Good structure with a real, one-level-deep reference (references/first-session.md) that is well-signaled via "[First session](references/first-session.md)" and an anchor link that resolves, and installation detail is appropriately deferred to it. Minor organization gaps keep it below anchor 5: the 29-tool catalog is inlined in the body rather than referenced out, and some guidance (retcon/defeat, record_decision policy) is duplicated across "Authoring loop" and "Core tools" instead of consolidated. | 4 / 5 |
Total | 17 / 20 Passed |