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.
The body is an unusually actionable orchestration runbook with exact commands, deterministic-helper delegation, and rigorous verification checkpoints at every risky step. Its main weakness is redundancy: the same guardrails are repeated across the role section, Common Mistakes, Red flags, and Important, inflating token cost without adding information.
Suggestions
Merge 'Common Mistakes' and 'Red flags' into one anti-pattern section (or offload it to a reference file) — each rule currently appears 3–5 times across Role/Core principle/Mistakes/Red flags/Important, costing roughly 45 lines of restatement.
State 'per-dimension trust' and 'verify done against Jira + MR' once authoritatively (Inputs and Phase F) and keep at most a one-line reminder elsewhere instead of full re-explanations in Phase A, Common Mistakes, and Red flags.
Move the merge-gate-specific red flags (REVIEW: APPROVE at head SHA, lint-commit-after-approval, gate.py premerge rows) into merge-gate.md, keeping only the 2–3 epic-specific anti-patterns inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body restates the same rules three to five times each — "never write feature code" appears in the role table, Common Mistakes, Red flags ("#44 is tiny… I'll knock it out right here"), and Important; "verify done claims" and "per-dimension trust" likewise recur across Core principle, Phases A/F, Common Mistakes, and Red flags — roughly 45 lines of restatement. The guidance itself is otherwise non-obvious with no explanations of concepts Claude already knows, so this is 'could be tightened' rather than 'minor instances'. | 3 / 5 |
Actionability | Guidance is copy-paste ready throughout: exact commands ("python3 \"$gate\" mode \"<epic ref>\"" with a fallback find), a filled JSON input shape for schedule.py, per-exit-code handling (0 use, 10 show cycle and ask, 1 fix and re-run), spawn_task field specs (title ≤60 chars, tldr one-liner, line-1 slash-command prompt template), and a per-ticket brief format template — fully executable coverage of the common cases. | 5 / 5 |
Workflow Clarity | Phases A–F are clearly sequenced with explicit validation checkpoints and feedback loops: re-verify Jira status AND MR state before declaring anything unblocked ("a 'done' claim is verified, never assumed"), abstain-and-ask on a detected dependency cycle, fix-and-re-run on malformed input, and gate.py premerge with a REVIEW: verdict naming the head SHA before any merge. Checklists (Common Mistakes, Red flags) are present for the complex process. | 5 / 5 |
Progressive Disclosure | Conditional one-level-deep sibling references are well signaled ("read the sibling github-mode.md. It replaces the Jira-specific parts of Phases A, B, C and F"; merge-gate.md loaded only when a gate exists), but the ~240-line body inlines two large anti-pattern sections (Common Mistakes + Red flags) that are restatement a reference file could carry, and the referenced siblings (github-mode.md, merge-gate.md, lib/*.py) are absent from this bundle, so navigation cannot be fully verified — good structure with minor gaps, not the exemplary-split anchor. | 4 / 5 |
Total | 17 / 20 Passed |