Content
80%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 lean and highly actionable with concrete commands and full script syntax, so an agent knows exactly how to invoke each capability. However, the end-to-end workflow connecting the three commands is implicit rather than explicit, there are no validation checkpoints, and the referenced script paths plus a circular self-reference do not resolve within the provided bundle. Fixing the reference structure and spelling out the scan→prioritize→report pipeline would lift the weaker dimensions.
Suggestions
Add an explicit workflow line such as "1. Run scan to produce inventory.json → 2. Feed inventory.json to prioritize → 3. Run report for the dashboard", so the data flow between subcommands is explicit.
Include a validation checkpoint (e.g., verify inventory.json exists and is well-formed before prioritizing) to satisfy the feedback-loop expectation for batch operations.
Fix the reference structure: point the Scripts section to bundle-relative paths (scripts/debt_scanner.py) and remove or correct the circular "Skill Reference" link to the SKILL.md itself.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~30-line body contains only usage syntax, copy-paste examples, and a script inventory with no concept explanations or padding; every line is operational, matching the lean anchor. | 5 / 5 |
Actionability | Concrete executable commands with flags ("/tech-debt scan . --format json --output debt-report.json") and exact script invocations with argument lists ("debt_prioritizer.py <inventory.json> [--framework cost_of_delay|wsjf|rice]") make the guidance copy-paste ready and cover the common cases. | 5 / 5 |
Workflow Clarity | The three subcommands are listed with their inputs, but the scan → inventory.json → prioritize → report pipeline is only implicit, and there are no explicit sequence or validation/verification steps; the batch codebase scan also caps workflow clarity at 3 per the rubric guidelines. | 3 / 5 |
Progressive Disclosure | Sections are clearly labeled, but the bundle contains no scripts/references/assets directories while the Scripts section points to external "engineering/skills/tech-debt-tracker/scripts/..." paths outside the bundle, and "Skill Reference" is a circular link to the SKILL.md itself; references are present but not resolvable against the actual bundle structure. | 3 / 5 |
Total | 16 / 20 Passed |