Content
77%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 highly actionable, rigorously gated workflow: exact CLI commands, explicit freshness and authorization checkpoints, and per-finding error semantics leave little ambiguity about what to do. Its weaknesses are verbosity from repeating core guardrails across multiple sections and a monolithic ~400-line body that inlines peripheral recovery procedures instead of moving them into the references directory.
Suggestions
State the freshness rule (completed review with commit_sha == PR head) once in a single authoritative section and reference it from 'Two modes', 'Read the session state FIRST', and 'Guardrails' instead of restating it four times.
Move the peripheral recovery procedures — the 'qodo: command not found' PATH fallback, the sandbox auth diagnostic, and the skill-update/runtime-recovery flows — into dedicated files under references/ (e.g., references/troubleshooting.md), keeping SKILL.md to the core read/resolve workflow.
Consolidate the repeated 'forge metadata reads are fine, don't scrape review comments' clarification (currently in Description, Instructions, Two modes, and Guardrails) into the Instructions note only.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is information-dense and assumes Claude's competence (no basic-concept explanations), but key rules are repeated verbatim several times: the freshness rule ("completed AND its `commit_sha` equals the head") appears in the Instructions note, 'Read the session state FIRST', 'Two modes', and 'Guardrails'; the "forge metadata reads are fine" clarification and the "never post to the forge" rule each repeat 3–4 times. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened'; it is not score-2 because the padding is redundant restatement of real rules rather than whole unnecessary explanation sections. | 3 / 5 |
Actionability | The Quick start block gives copy-paste-ready commands with exact flags ("qodo read pr-review-session findings --pr-url <PR_URL> --json", "--extended", "mark-implemented… --explanation", "dismiss… --reason intentional"), plus offline discovery commands ("qodo read tools pr-review-session --json", "qodo tools help… --json") and concrete per-finding result codes ("not_found", "conflict", "reconciled: false", "already_dismissed") with terminal-vs-retryable handling and a worked Example. Specific examples cover the common read, fix, dismiss, and watch cases. | 5 / 5 |
Workflow Clarity | A clearly gated sequence runs version probe → preflight (auth, PR resolution, repo/checkout binding) → fetch session → session-state-first check → triage → scope → resolve → record outcome, with explicit validation checkpoints throughout: "Act only on a completed review of the current commit", per-finding result verification ("Read `results` per finding, don't assume the call succeeded"), one-refresh recovery loops, bounded watch iterations ("stop after a few rounds with no progress"), and error feedback loops. Batch status writes (up to 100 ids) are explicitly paired with per-finding validation, satisfying the batch-operation feedback requirement. | 5 / 5 |
Progressive Disclosure | Section headers are clear and the single bundle reference is real and well-signaled ("follow the [manual-update procedure](references/skill-updates.md)" — one level deep, verified to exist), but the ~400-line body inlines large amounts of peripheral procedural detail (PATH/command-not-found fallback, sandbox auth diagnostic, update-notice and enterprise-update flows, extended-results recovery) that clearly belongs in reference files. This matches 'some structure; references present but content that should be separate is inline' rather than score-4, where most content would be appropriately placed. | 3 / 5 |
Total | 16 / 20 Passed |