iterative-planner
State-machine driven iterative planning and execution for complex coding tasks. Cycle: Explore → Plan → Execute → Reflect → Pivot. Filesystem as persistent memory. Use for multi-file tasks, migrations, refactoring, failed tasks, or anything non-trivial.
75
68%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./src/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description effectively communicates both what the skill does and when to use it, with a clear methodology (Explore → Plan → Execute → Reflect → Pivot). However, the actual coding actions remain abstract—it describes a process rather than concrete capabilities—and the catch-all 'anything non-trivial' weakens distinctiveness. Trigger terms cover some common scenarios but miss natural user phrasings.
Suggestions
Replace 'anything non-trivial' with more specific trigger scenarios (e.g., 'large-scale code changes spanning multiple modules', 'tasks requiring investigation before implementation') to reduce conflict risk with other skills.
Add more natural user-facing trigger terms like 'break this down', 'step by step approach', 'complex change', 'code restructuring', or 'systematic approach' to improve keyword coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (complex coding tasks) and describes the methodology (state-machine driven iterative planning with Explore → Plan → Execute → Reflect → Pivot cycle), but the actual concrete actions are abstract process steps rather than specific coding actions like 'refactor modules' or 'migrate database schemas'. | 2 / 3 |
Completeness | Clearly answers both 'what' (state-machine driven iterative planning and execution with a defined cycle and filesystem as persistent memory) and 'when' (explicitly states 'Use for multi-file tasks, migrations, refactoring, failed tasks, or anything non-trivial'). | 3 / 3 |
Trigger Term Quality | Includes some useful trigger terms like 'multi-file tasks', 'migrations', 'refactoring', and 'failed tasks', but misses many natural variations users might say such as 'large refactor', 'complex project', 'step by step', 'break down this task', or 'code restructuring'. The term 'non-trivial' is vague. | 2 / 3 |
Distinctiveness Conflict Risk | The methodology-focused description (state machine, iterative planning) is somewhat distinctive, but triggers like 'refactoring', 'migrations', and 'multi-file tasks' could easily overlap with more specific refactoring or migration skills. The catch-all 'anything non-trivial' significantly increases conflict risk. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is an extraordinarily comprehensive and well-structured planning protocol with excellent workflow clarity, actionability, and progressive disclosure. However, it suffers significantly from verbosity — the document is far too long for a skill file, with substantial redundancy across sections (rules restated in multiple places, concepts explained that Claude already understands). The content would benefit enormously from aggressive compression, potentially cutting 40-50% of the text while preserving all actionable guidance.
Suggestions
Aggressively deduplicate repeated rules — Revert-First, 3-Strike, checkpoint procedures, and mandatory re-reads are each stated 3-4 times across different sections. State each rule once in a dedicated section and reference it elsewhere.
Remove explanatory framing that Claude doesn't need — e.g., 'Context Window = RAM. Filesystem = Disk.' and explanations of why persistence matters. Jump straight to the rules.
Consolidate the Consolidated File Management and Lessons Learned sections — the compression protocol alone is ~40 lines that could be reduced to ~15 lines of concrete rules without the format examples and failsafe explanations.
Consider moving the Sub-Agent Architecture section (which is marked as optional) entirely to a reference file, since it adds ~80 lines for an optimization layer that isn't required.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~500+ lines. While the domain is complex, there is significant redundancy — the same rules (revert-first, 3-strike, mandatory re-reads, checkpoint procedures) are repeated across multiple sections. Many concepts (like compression protocols, sliding window mechanics, consolidated file management) could be dramatically tightened. Claude doesn't need explanations of why context windows are like RAM or why filesystem persistence matters. | 1 / 3 |
Actionability | The skill provides highly concrete, executable guidance throughout: specific bootstrap commands, exact file paths, precise state transition triggers, detailed checklists with checkboxes, specific commit message formats, exact line count thresholds, and clear decision frameworks. Every state has explicit allowed actions and gate conditions. | 3 / 3 |
Workflow Clarity | The state machine is exceptionally well-defined with a mermaid diagram, explicit transition triggers, validation checkpoints at every stage (Gate-In reads, Post-Step Gate, exploration confidence checks), feedback loops (REFLECT→EXPLORE, REFLECT→PIVOT→PLAN), and clear error recovery procedures (Autonomy Leash, Revert-First). The REFLECT phase alone has 20 numbered steps with explicit sequencing. | 3 / 3 |
Progressive Disclosure | The skill maintains a clear overview structure with well-signaled one-level-deep references to 6 separate reference files (file-formats.md, complexity-control.md, code-hygiene.md, decision-anchoring.md, planning-rigor.md, convergence-metrics.md) and 7 agent definition files. The main file serves as the protocol overview while detailed templates and procedures are appropriately externalized. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- NikolasMarkou/iterative-planner
- Commit
3983e7e
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.