Content
73%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.
An exceptionally well-sequenced execution workflow with validation gates and feedback loops on every risky operation, backed by a real one-level-deep reference bundle. The main costs are token efficiency — repeated procedure naming, editorial asides, and a long inline build-freshness section — and MCP tool calls that stop short of copy-paste-ready form.
Suggestions
Move the six-step Build-current/index-current procedure into its own reference file and refer to it by name, cutting significant inline tokens and the repeated restatements of when to run it.
Trim editorial rationale (e.g., "the plan travels with the work it drives", "'the fix doesn't work' is more often 'the fix never loaded'") to bare instructions.
Show the exact MCP tool-call shapes for impact and detect_changes (as done for the evidence-provenance CLI) so every gate is copy-paste executable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and prescriptive but noticeably repetitive and padded in places: the "Build-current/index-current procedure" name is restated at least five times, and editorial asides like "the plan travels with the work it drives", "interleaving other work between the gate and the commit is how the gate gets skipped", and "'the fix doesn't work' is more often 'the fix never loaded'" could be trimmed without losing instruction. It is not a 2 because there is little explanation of concepts Claude already knows — nearly every line is skill-specific guidance; it is not a 4 because the repetition and rhetorical asides are more than minor. | 3 / 5 |
Actionability | Most guidance is executable: exact commands like "scripts/evidence-provenance.mjs read-plan --repo <root> --generated-plan <candidate>", "node gitnexus/dist/cli/index.js analyze --index-only --pdg", "cd gitnexus && npm run build", and a concrete commit message format. It is not a 5 because the MCP tool calls (impact, detect_changes, status --json) are described semantically rather than as complete copy-paste invocations, and some parameters are placeholders that require assembly. | 4 / 5 |
Workflow Clarity | The four-phase sequence is explicit with validation checkpoints throughout: a two-layer drift check, assumption re-verification, a pre-completed check, impact gates before every edit, detect_changes gating every commit with a defined stage → gate → commit unbroken sequence, and explicit failure handling (partial/truncated results block commits; procedure failure blocks completion). Feedback loops are present for every failure mode, including routing back to gitnexus-plan Deepen mode. This clearly matches the top anchor. | 5 / 5 |
Progressive Disclosure | Structure is good: the deep evidence-provenance protocol is correctly delegated to the real, well-organized references/evidence-provenance.md (one level deep, clearly signaled), and the body uses clear section headings. It is not a 5 because the ~60-line inline "Build-current/index-current procedure" section is substantial content that could live in a reference file (the body even leans on it as a named procedure), and Phase 1's drift-check details partially duplicate the reference's territory. | 4 / 5 |
Total | 16 / 20 Passed |