Content
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured process skill that clearly sequences a multi-step review workflow with appropriate human checkpoints. It's concise, well-organized, and makes good use of references to other skills and documents. The main weakness is the lack of concrete examples showing what the summary output or register updates should look like, which would make the skill more immediately actionable.
Suggestions
Add a brief example of what the summary report (step 5) should look like when presented to the human, e.g., a sample markdown output with one item per category.
Include a concrete example of a tech-debt.md table row being moved from Outstanding to Resolved, showing the expected format.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is lean and efficient. It doesn't explain what tech debt is or how markdown tables work. Every section serves a clear purpose and there's no padding or unnecessary context. The table format for categorization is an efficient use of tokens. | 3 / 3 |
Actionability | The skill provides clear procedural guidance with specific file paths and categories, but lacks executable code or commands. The assessment criteria are concrete but somewhat subjective (e.g., 'blast radius'). The commit message and file references are specific, but there are no concrete examples of what a summary output should look like or how to format the tech-debt.md updates. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced with numbered steps from reading through assessment, reporting, acting, and updating. It includes a critical human-in-the-loop checkpoint (step 6: 'Ask the human which items to act on') before any action is taken, and references external verification steps (TDD workflow, implement-spec skill) for approved fixes. The categorization table provides clear decision criteria. | 3 / 3 |
Progressive Disclosure | The skill appropriately references external resources (CONSTITUTION.md §3, implement-spec skill, draft-spec skill/routine) without inlining their content. References are one level deep and clearly signaled. The content is well-organized into logical sections (read, assess, report, update) that are appropriately sized for a single SKILL.md file. | 3 / 3 |
Total | 11 / 12 Passed |