plan-with-docs

Doc-aware planning skill. Turns a PRD, ADR, existing plan, or raw idea into a tracer-bullet implementation plan via a relentless one-question-at-a-time interview. Reads accepted ADRs and a PRD together as constraints: ADRs fix architectural decisions; the PRD supplies goals, non-goals, and acceptance criteria that gate each phase. Drafts Proposed ADRs — asking whether a decision is new or supersedes an existing one — and updates CONTEXT.md as terms resolve. Optional tribunal stress-test before finalizing. Use when asked to "plan with docs", "plan this ADR", "turn this PRD into a plan", "break this down into phases", "tracer bullets", "review my plan", "stress test this approach", or /plan-with-docs.

Quality

96%

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

Quality

Content

92%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.

A well-engineered orchestration skill: actionable templates and exact paths, a clearly sequenced five-phase workflow with explicit validation gates and feedback loops, and clean progressive disclosure to verified bundle files. The only minor drag is conciseness — a long illustrative example and repeated contract-pointer annotations could be trimmed.

Dimension	Reasoning	Score
Conciseness	The body is dense and assumes Claude's competence — no padding explaining what a PRD or ADR is — but a few spots could be trimmed, notably the long illustrative 'Captured:' example in Phase 1 step 5 and the repeated '(Contract: references/prd-format.md.)' / '(Gating contract: references/prd-format.md.)' annotations. This sits at 'efficient with minor instances that could be trimmed', not the fully lean top anchor.	4 / 5
Actionability	Highly actionable for an instruction-only skill: exact output paths ('docs/plans/<source.basename>.md'), exact required plan sections, copy-paste-ready prompt templates ([Non-Goal Conflict], [Decision Capture], [ADR Conflict → Decision Capture]), and concrete agent-spawn instructions (subagent_type, name, parallel).	5 / 5
Workflow Clarity	Five phases are clearly sequenced with explicit validation checkpoints — AC-N completion gates, non-goal conflict halt, AC-N traceability flagging before finalizing, the 3-condition decision-capture test — and feedback loops (jury question resolution 'Repeat until the jury has no more questions', re-validate on errors). An edge-cases section covers failure modes.	5 / 5
Progressive Disclosure	SKILL.md is a clear overview that signals one-level-deep references up front with one-line descriptions and points to them inline at the right moments ('Read references/interview-guide.md for the full protocol'); all eight referenced files exist, and content is appropriately split (protocol, templates, formats, personas, jury rules) rather than inlined.	5 / 5
	Total	19 / 20 Passed

Description

100%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.

An exemplary description: it states concrete capabilities, supplies a rich set of natural trigger phrases, explicitly answers both what and when, and carves out a distinct niche with low conflict risk. Every dimension lands at the top anchor.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Turns a PRD, ADR, existing plan, or raw idea into a tracer-bullet implementation plan', 'Reads accepted ADRs and a PRD together as constraints', 'Drafts Proposed ADRs', 'updates CONTEXT.md', 'Optional tribunal stress-test' — covering the skill comprehensively with no real gaps.	5 / 5
Completeness	Explicitly answers both 'what' (turns input into a tracer-bullet plan via one-question-at-a-time interview, dual ADR+PRD constraints, drafts ADRs, updates CONTEXT.md, tribunal) and 'when' (an explicit 'Use when...' clause with concrete trigger phrases).	5 / 5
Trigger Term Quality	Provides comprehensive natural trigger phrases users would actually say — 'plan with docs', 'plan this ADR', 'turn this PRD into a plan', 'break this down into phases', 'tracer bullets', 'review my plan', 'stress test this approach' — plus the /plan-with-docs slash command.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche — doc-aware planning with dual ADR/PRD constraints, tracer-bullet output, and a tribunal stress-test — and its triggers ('plan this ADR', 'turn this PRD into a plan', 'tracer bullets') are distinctive enough to minimize wrong-skill activation.	5 / 5
	Total	20 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 2 missing, 1 suspicious	Warning

	Total	15 / 16 Passed

Repository: MrToxy/claude-skills
Path: plan-with-docs/SKILL.md
Commit: 66c7102

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.