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.
The body is extremely executable and well-sequenced — every phase has concrete commands, explicit validation gates, and error-recovery branches — and it uses its 16-file reference bundle correctly with verified anchors. Its main weakness is token efficiency: ~1,100 lines with inline incident histories, duplicated rationale, and worked configuration examples that should live in reference files.
Suggestions
Move the Phase 7 routing-tier material (the two illustrative routing.yaml examples, purposes/tier_for() precedence prose, and capacity-cache operator command reference) into a references/routing.md and keep only the dispatch-relevant summary inline.
Replace inline incident narratives (e.g. "Datalena run go-20260811-132806", "confirmed live 2026-08-24", "live incident: run worktrail/go-20260825-163910") with a one-line rule plus a pointer to a history/rationale reference file — the dates and run ids cost tokens without changing the instruction.
State the agent_cli vs native_skill_available independence rule once in the Invocation Context section and reference it from later phases instead of re-explaining the embedded-Codex example in both the Invocation Context and Dispatch sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~1,100-line body is noticeably verbose: inline incident narratives ("confirmed live 2026-08-24", "Datalena run go-20260811-132806", "live incident: run worktrail-go-20260825-163910", "observed: brief 20260812-163747 scored E=11"), the agent_cli/native_skill_available independence rationale explained twice, and two worked YAML routing examples flagged as "illustrative" are all padded sections a competent agent does not need inline. Not 1: there is no explanation of concepts Claude already knows — everything is operational specifics; not 3: the volume of rationale, history, and inline configuration detail goes well beyond "some unnecessary explanation." | 2 / 5 |
Actionability | Every phase gives copy-paste bash with exact flags, exit-code semantics (exit 2 with distinct blocked_* stderr lines), the liveness/same_dispatch decision table, and an exact Dispatch Contract ("Skill(\"worktrail-sdd-workflow\", args=\"<repo-path> route:<X> [spec-folder] run:<run-path>\")"). Specific examples cover the common cases from /go spec fix to bare /go. Not 4: even edge cases (argv-overflow via mktemp files, assert-terminal hard gate) carry exact commands. | 5 / 5 |
Workflow Clarity | Phases 0–8 are clearly sequenced with validation checkpoints and feedback loops at nearly every step: parse-then-act classification, exit-status checks with distinct blocked_* failure classes, "worktrail-run-record assert-terminal \"$RUN\"" as a hard gate, the same_dispatch/fresh resume matrix, and pre-checks before destructive operations (openspec validate --strict, ownership checks before claiming). Not 4: checkpoints are explicit and systematic, not merely present — batch/PR-owning operations all have verification, so no workflow-clarity cap applies. | 5 / 5 |
Progressive Disclosure | All 16 references/*.md files referenced from the body exist and anchors verify ({#handoff-seed}, {#subprocess-dispatch}, {#ci-wait-discipline} in ci-watch-loop.md, {#overlap-check}, {#fix-branch-worktree-setup}, {#already-implemented-check} in subagent-prompts.md), with clearly signaled one-level-deep pointers ("Full procedure: references/auto-mode.md", "Field contract: references/dashboard-render.md"). Not 5: significant inline content belongs in references — the Phase 7 routing-tier deep-dive with two worked YAML examples, the capacity-cache operator command reference, and the repeated incident histories are inlined rather than split out; not 3: structure is consistent and references are clearly signaled, not buried. | 4 / 5 |
Total | 16 / 20 Passed |