Content
78%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, concrete instruction skill with a complete schema template, explicit output rules, and a verification checklist. Its weaknesses are modest repetition of the quality-gates emphasis, an unnumbered tail of workflow sections, and an orphaned example file in references/examples/ that the body never points to.
Suggestions
Reference the bundled example in the body, e.g., under Step 2: "See [json-prd-example.md](references/examples/json-prd-example.md) for a complete worked example" — this surfaces the existing asset and could let the inline template be trimmed.
State the error-recovery loop after Verification (e.g., "If any check fails, fix the JSON and re-verify before reporting") and number or merge the post-Step-2 sections so the full workflow reads as one sequence.
Consolidate the triple quality-gates emphasis (The Job step 3, the Step 1 focus bullet, and the example question) into one authoritative statement to save tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is prescriptive and assumes competence — it never explains what a PRD or JSON is — with exact paths, schemas, and commands. Minor trimmable repetition: quality gates are stated three times ("Always ask about quality gates", the "Quality Gates... (REQUIRED)" bullet, and the example question), keeping it below anchor 5 but well above anchor 3. | 4 / 5 |
Actionability | Fully executable guidance throughout: exact input/output path mappings ("prd.md -> prd.json"), a complete copy-paste JSON schema template, a concrete question-format example, explicit install-command requirements ("pnpm add <pkg>"), and a verbatim closing message ("PRD JSON saved to <path>. Close this chat and run \`ralph build\`.\") with no gaps for the common cases. | 5 / 5 |
Workflow Clarity | A clear sequence (The Job -> Step 1 clarifying questions -> Step 2 JSON structure), a NO-GO gate when no PRD markdown exists, and a concrete Verification checklist ("JSON parses", "contains required keys", "no loss"). Minor gaps: no explicit error-recovery loop after verification, and the post-Step-2 sections (No Information Loss, Output Requirements, Verification) are unnumbered, so the full flow is slightly less crisp than anchor 5. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned and the inline JSON schema template legitimately belongs inline, but the bundled references/examples/json-prd-example.md — a complete, ready-made example PRD JSON — is never referenced anywhere in the body, leaving a useful bundle file undiscoverable. That is more than the minor organization gap of anchor 4, though the body's own structure is far better than anchor 2's minimal/inlined-content characterization. | 3 / 5 |
Total | 16 / 20 Passed |