041-planning-plan-mode

Use when creating or refining a structured Java implementation plan from trusted issue summaries, approved designs, ADRs, OpenSpec changes, existing plans, or a valid combination. The plan records its source artifacts and derivation direction and can remain the execution artifact without requiring OpenSpec. This should trigger for requests such as Create a plan from an issue; Create a plan from OpenSpec; Design an implementation plan; Refine an existing plan. Part of Plinth Toolkit

Quality

78%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/041-planning-plan-mode/SKILL.md

Quality

Content

63%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-structured interactive workflow with explicit approval and conflict-resolution checkpoints, but it suffers from noticeable duplication across the Constraints, 'What is covered', and 'When to use' sections. Its biggest structural defect is at the bundle level: the referenced plan template is a dangling xi:include pointing to a nonexistent assets file, so the deferred detail the workflow depends on cannot actually be reached.

Suggestions

Consolidate duplicated guidance: state the sanitized-summary and source-authority rules once (either in Constraints or Step 1) and drop the verbatim trigger list from 'When to use this skill' since the description already carries it.

Fix the bundle's broken reference chain: create assets/java-design-plan-template.md or inline the template into references/041-planning-plan-mode.md, since the reference's xi:include currently points to a nonexistent file.

Add an explicit post-generation validation step (e.g., verify the generated plan records all source artifacts, derivation direction, and Execution Instructions) to close the workflow's feedback loop.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with no explanations of concepts Claude already knows, but content is duplicated across sections: the sanitized-summary rule appears in both Constraints ('Use maintainer-provided sanitized summaries for issue, PR, wiki...') and Step 1; 'When to use this skill' repeats the frontmatter trigger list verbatim; and the 'What is covered' bullets overlap the Constraints. This is more than the 'minor instances that could be trimmed' of the anchor above.	3 / 5
Actionability	Instruction-only skill with mostly concrete guidance: 'Run `date` before starting', 'Ask one or two focused questions at a time', an enumerated plan structure in Step 4, and explicit MUST/MUST NOT constraints. Minor gaps remain — the plan template and filename conventions are deferred entirely to the reference file.	4 / 5
Workflow Clarity	Clear numbered sequence (steps 0–5) with most checkpoints present: 'Validate the summary and wait for approval before writing' and 'Do not propagate conflicting changes until the user makes an explicit decision'. Falls short of the top anchor because there is no validation or feedback loop after the plan is generated.	4 / 5
Progressive Disclosure	The body itself is a clean overview with one clearly signaled, one-level-deep reference (references/041-planning-plan-mode.md, which exists). However, scored against the actual bundle structure, the reference contains '<xi:include href="assets/java-design-plan-template.md" parse="text"/>' and no assets/ directory exists — a dangling second-level reference that breaks the bundle's navigation chain, keeping it below the 'references mostly clear' anchor.	3 / 5
	Total	14 / 20 Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it explicitly states what the skill does and when to use it, with concrete natural-language trigger phrases and clear scoping to Java implementation planning from specific source artifacts. Its main weaknesses are minor — the action vocabulary is narrow (create/refine) and some common phrasings users might say ('write a plan', 'draft a plan') are not covered.

Dimension	Reasoning	Score
Specificity	Names concrete actions — 'creating or refining a structured Java implementation plan' from an enumerated set of source types, and 'records its source artifacts and derivation direction'. It lists several specific actions with minor gaps, but coverage centers on essentially two verbs (create/refine) rather than the comprehensive multi-action coverage of the top anchor.	4 / 5
Completeness	Explicitly answers both what ('creating or refining a structured Java implementation plan from trusted issue summaries, approved designs, ADRs, OpenSpec changes, existing plans, or a valid combination') and when ('Use when creating or refining...', plus a concrete trigger-phrase list). Both are explicit with concrete triggers, matching the top anchor.	5 / 5
Trigger Term Quality	Includes natural user phrasings ('Create a plan from an issue', 'Refine an existing plan') and a synonym variant ('Design an implementation plan'). Good coverage, but misses common variations such as 'write a plan', 'draft a plan', or 'make a plan', so it falls short of the comprehensive anchor.	4 / 5
Distinctiveness Conflict Risk	Scoped to Java implementation planning from specific artifact types (OpenSpec changes, ADRs, approved designs), making it mostly distinct with only minor overlap risk against generic planning skills for phrases like 'Refine an existing plan'.	4 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: jabrena/plinth
Path: skills/041-planning-plan-mode/SKILL.md
Commit: dca88dc

Reviewed: 3 hours ago

Table of Contents

Discovery Implementation Validation

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.