Content
88%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 strong orchestration body: every instruction is skill-specific and actionable, validation and error-recovery paths are explicit, and detail is properly delegated to a disciplined on-demand bundle. The weaknesses are verbosity at the margins — restated rules and long multi-clause policy sentences — and reference paths that are not uniformly fully qualified.
Suggestions
State the `run_mode` ("decide" | "decide_and_execute") semantics once in a canonical section and cross-reference it from Execution, State Management, and Sidebar Placement instead of restating it three times.
Split or shorten the densest policy passages — the Clarify fast-path paragraph and the live-first Philosophy bullet — into shorter rule statements; the rationale sentences (e.g., "The eligibility rule exists precisely so that ...") can be cut once the rule itself is stated.
Use fully qualified paths consistently for phase and fragment references (e.g., `references/phases/clarify/clarify.md` § Step 0.5 instead of `clarify.md` § Step 0.5) so every reference resolves without searching the bundle.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, skill-specific policy with no padding about concepts Claude already knows ("Re-platform by default: pick the AWS service that matches the Azure workload type (App Service → Elastic Beanstalk, AKS → EKS, ...)"). It fits the 4 anchor (efficient, minor instances of over-explanation that could be trimmed): the `run_mode` semantics appear in three sections (Execution, State Management, Sidebar Placement), and passages like "The eligibility rule exists precisely so that the two cases named above ... never reach the short path" over-justify already-stated rules. It is not 3 because nearly every token carries non-inferable skill policy, and not 5 because some multi-clause sentences (e.g., the Clarify fast-path and live-first Philosophy paragraphs) must be re-read to parse. | 4 / 5 |
Actionability | Directives are specific and executable: an exact entry point ("begin at `references/phases/discover/discover.md`"), copy-paste-ready outputs ("Unrecognized phase: [value]. Valid phases: discover, clarify, design, estimate, workshop, generate, feedback."), a verbatim feedback prompt with [A]/[B] options, exact defaults ("Region: `us-east-1`", "CPU architecture: `x86_64`"), and named MCP tools (`aws___search_documentation`, etc.). For an instruction-only orchestrator this matches the 5 anchor — concrete, specific guidance covering the common cases; not 4, because there are no high-level hints without a corresponding executable directive. | 5 / 5 |
Workflow Clarity | Sequencing is unambiguous (cold start entry phase, `_advances_to` chain, warm-start rules, mandatory Clarify with no exceptions) and validation is explicit: seven numbered state-validation checks with STOP conditions, plus a full error-recovery feedback loop for corrupt `.phase-status.json` (enumerate artifacts → infer completed phases → confirm with the user → rewrite the file). This matches the 5 anchor (explicit validation steps, feedback loops for error recovery, checklists); it is not 4 because checkpoints are explicit rather than implicit, and the noted caveat that `generate.md`'s `_assert` "has no mechanical teeth" is disclosed rather than hidden. | 5 / 5 |
Progressive Disclosure | The body is a genuine overview that pushes detail into a well-organized bundle (phases/, design-refs/, shared/, vendored/), enforces load discipline ("~800 lines of instructions", "Do not speculatively load files", "a pattern may never change a deterministic mapping's target" lives once in Philosophy), and the vendored contracts (`INTERPRETER.md`, `phase-status.schema.json`, `PROTOCOL.md`) are loaded once and referenced by name. It fits the 4 anchor (good structure, references mostly clear, minor organization gaps) rather than 5 because references chain more than one level (SKILL.md → phase file → fragment → shared ref such as `extract-terraform.md`) and several mentions are bare filenames without paths ("`clarify.md` § Step 0.5", "`estimate-assemble.md` § Step 3b"). It is not 3 because nothing that belongs in a separate file is inlined and navigation is easy via the directory layout. | 4 / 5 |
Total | 18 / 20 Passed |