Content
77%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-crafted skill that clearly defines a structured TODO workflow using JJ with concrete commands, clear role delineation, and strong validation checkpoints. Its main weakness is moderate verbosity — some sections could be tightened without losing clarity, and the document is long enough that some content could benefit from being split into reference files. The actionability and workflow clarity are excellent, with complete executable examples and explicit guidance on when to stop, report, or proceed.
Suggestions
Trim explanatory prose in sections like 'When to Use draft vs todo' and 'Completion Discipline' — the tables and examples already convey the information clearly without the surrounding narrative.
Consider moving the 'Writing Good TODO Descriptions' and 'AI-Assisted TODO Workflow' sections into separate reference files to reduce the main SKILL.md length and improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-written but includes some unnecessary verbosity: the NOTE about renaming 'broken' to 'standby', repeated reminders about which role each section applies to, and some explanatory text that could be trimmed. The 'When to Use draft vs todo' section and 'Completion Discipline' section are somewhat verbose for concepts Claude can infer. However, most content earns its place given the complexity of the workflow. | 2 / 3 |
Actionability | The skill provides concrete, executable bash commands throughout, with specific script invocations, flag values, and clear examples. The Quick Start section shows a complete cycle with real commands. The helper scripts table, flag reference table, and workflow steps are all copy-paste ready with specific command syntax. | 3 / 3 |
Workflow Clarity | The multi-step workflow is clearly sequenced (Plan → Work → Complete → Next) with explicit validation checkpoints: verify acceptance criteria before marking done, check dependencies before starting, run tests before transitioning. The 'When to Stop and Report' section provides clear error recovery guidance. The `jj-todo-next` without args serves as a review/validation checkpoint before proceeding. Feedback loops are present (fix and re-validate, stay on wip and keep working). | 3 / 3 |
Progressive Disclosure | The skill references external files (references/parallel-agents.md, working-with-jj skill) appropriately, and the helper scripts table provides a clean overview. However, the SKILL.md itself is quite long (~300 lines) with substantial inline content that could potentially be split out (e.g., the detailed 'Writing Good TODO Descriptions' section, the 'AI-Assisted TODO Workflow' section). The structure is good with clear sections, but the document is somewhat monolithic for its length. No bundle files were provided to verify referenced paths. | 2 / 3 |
Total | 10 / 12 Passed |