roadmap-with-file
Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable).
37
36%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.codex/skills/roadmap-with-file/SKILL.mdQuality
Discovery
32%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 communicates the general purpose (requirement decomposition into roadmaps and issues) and specifies concrete output formats, which is helpful. However, it lacks an explicit 'Use when...' clause, uses somewhat jargon-heavy language rather than natural user trigger terms, and the actions described are more process-oriented than concretely actionable.
Suggestions
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to plan features, break down requirements into tasks, create a project roadmap, or generate issues/tickets from a specification.'
Replace or supplement jargon like 'iterative decomposition' with concrete user-facing actions such as 'breaks down high-level requirements into actionable issues/tickets'.
Include common user vocabulary variations like 'project planning', 'feature breakdown', 'backlog creation', 'tickets', or 'epics' to improve trigger term coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (requirement roadmapping) and some actions (iterative decomposition, issue creation), and specifies outputs (roadmap.md, issues.jsonl), but the actions are somewhat abstract — 'strategic requirement roadmap' and 'iterative decomposition' are more process-oriented than concrete user-facing actions. | 2 / 3 |
Completeness | Describes what it does (creates roadmaps and issues via decomposition) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also somewhat vague, placing this at 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant terms like 'roadmap', 'requirement', 'issue creation', and 'decomposition', but misses common natural user phrases like 'plan features', 'break down requirements', 'create tickets', 'project planning', or 'backlog'. The terms lean more toward methodology jargon than what users would naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | The specific output artifacts (roadmap.md, issues.jsonl) and the combination of roadmapping + issue creation provide some distinctiveness, but 'requirement' and 'roadmap' are broad enough to potentially overlap with general project planning or issue tracking skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has excellent workflow clarity with well-defined phases, validation gates, and error handling, but is severely undermined by extreme verbosity and lack of progressive disclosure. The ~500+ line monolithic file includes full implementation code, templates, schemas, and repeated rules that should be split across referenced files. The actionability is moderate — code examples are present but mix executable API calls with pseudocode flow control.
Suggestions
Extract the roadmap.md template, JSONL schema, and subagent API reference into separate bundle files (e.g., TEMPLATE.md, SCHEMA.md, API.md) and reference them from the main skill with one-level-deep links.
Remove duplicate statements — 'planning-only' constraint, 'testable convergence' rule, and 'single source of truth' concept are each stated 2-3 times across different sections.
Trim implementation code blocks to show only the critical decision points and API calls; remove boilerplate like the full roadmap template string literal and the complete session initialization code that Claude can generate from a brief specification.
Remove the 'Why No Separate JSON Files?' table and the 'Usage Recommendations' comparison table — these explain design rationale and skill selection that don't help Claude execute this specific skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. Contains massive amounts of implementation detail (full JavaScript code blocks for session init, phase logic, agent spawning), template boilerplate, and explanatory tables that Claude could infer. The 'Why No Separate JSON Files?' table explains internal design decisions unnecessarily. Multiple sections repeat the same rules (e.g., 'planning-only' stated 3+ times, 'testable convergence' repeated in Core Rules and Best Practices). | 1 / 3 |
Actionability | Contains concrete JavaScript code examples and specific commands (ccw issue create, spawn_agent calls), but much of it is pseudocode-like with placeholder variables (${requirement}, ${selectedMode}) and conditional logic that isn't truly executable. The code mixes real API calls with conceptual flow control, making it unclear what's literal vs illustrative. | 2 / 3 |
Workflow Clarity | The 4-phase workflow is clearly sequenced with explicit validation checkpoints: Phase 3 has a mandatory confirmation gate before handoff, the terminal gate in Phase 4 is marked as CRITICAL/MANDATORY, feedback loops with max 5 rounds are defined, and error handling covers failure modes with specific resolutions. The ASCII diagram provides a clear overview of the entire flow. | 3 / 3 |
Progressive Disclosure | Monolithic wall of text with no bundle files to reference. Everything is inlined in a single massive SKILL.md — the roadmap template, JSONL schema, full implementation code for all 4 phases, subagent API reference, error handling, best practices, and usage recommendations. No content is split into separate files despite clear candidates (template, schema, API reference, implementation details). | 1 / 3 |
Total | 7 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (907 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- catlog22/Claude-Code-Workflow
- Commit
5ff5e86
- 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.