Content
72%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 well-organized backend guide that routes tasks to real one-level-deep references and supplies executable everyday commands. Its main weakness is workflow clarity: verification steps are not tied to specific tasks as explicit checkpoints, particularly for destructive migration work.
Suggestions
Add a per-task verification line in the 'What Are You Doing?' table (e.g. after a migration: run make graphql, then make typecheck-python, then uv run pytest tests/unit/server/) so validation is sequenced rather than left as generic everyday commands.
For migration/model changes, include an explicit validate->fix->retry checkpoint note (or pointer to the matching section in references/database-patterns.md) given their destructive nature.
Trim the editorial rationale in the Naming and Docstrings sections to the rule plus a one-line why, reducing over-explanation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean with compact command blocks and a structured directory listing; rationale prose in Hard Rules/Naming/Docstrings is largely justified context rather than padding, with only minor editorial over-explanation. | 4 / 5 |
Actionability | Provides concrete executable commands (make dev-backend, uv run pytest), a real directory map, and a task-to-reference routing table with specific class names; full pattern code lives in references rather than inline, leaving minor gaps. | 4 / 5 |
Workflow Clarity | The task table gives a clear routing sequence and verification commands exist (typecheck, test), but validation checkpoints are not sequenced per task and destructive migration work lacks inline validate/verify steps, capping it at 3. | 3 / 5 |
Progressive Disclosure | Four real reference files are each clearly signaled one level deep via the task table and inline pointers (e.g. "See references/graphql-patterns.md → 'Query vs Mutation'"), with the overview appropriately split from detail. | 5 / 5 |
Total | 16 / 20 Passed |