Plan Quality Verifier

Purpose

Score an implementation plan across 8 quality dimensions and gate execution on a minimum threshold. Returns { pass, score, dimensions } where pass is true when overall score ≥ 60/100.

When to Use

Invoke this skill before handing off a plan to executing agents:

Skill({ skill: 'plan-quality-verifier' });

Use when:

• A planner agent has finished drafting an implementation plan
• The router wants to gate execution behind a quality check
• An architect needs to validate a submitted plan before approval
• A developer receives a plan and wants to sanity-check it before starting

Iron Law

NO PLAN EXECUTES WITHOUT PASSING QUALITY VERIFICATION FIRST

A plan that scores < 60/100 must be revised before spawning executing agents.

Workflow

Step 1: Load the plan content

Read the plan file:

cat .claude/context/plans/<plan-file>.md

Expected output: Raw markdown text of the plan.

Step 2: Run the verifier

const { verifyPlan } = require('.claude/lib/validation/plan-quality-verifier.cjs');
const planContent = require('fs').readFileSync('<plan-path>', 'utf8');
const result = verifyPlan(planContent);
console.log(JSON.stringify(result, null, 2));

Expected output:

{
  "pass": true,
  "score": 72,
  "dimensions": [
    { "name": "requirement-coverage", "score": 8 },
    { "name": "task-completeness", "score": 7 },
    { "name": "dependency-validity", "score": 9 },
    { "name": "scope-sanity", "score": 6 },
    { "name": "artifact-wiring", "score": 7 },
    { "name": "risk-assessment", "score": 8 },
    { "name": "testability", "score": 7 },
    { "name": "estimation-quality", "score": 9 }
  ]
}

Verify: result.pass === true and result.score >= 60.

Step 3: Interpret results

Result	Action
pass: true	Proceed — hand off plan to executing agents
pass: false	Block — return feedback to planner with failing dimensions
Score 60-69	Marginal pass — flag low-scoring dimensions for improvement in next iteration
Score < 40	Hard block — plan needs significant rework before re-evaluation

Step 4: Report failing dimensions

When pass: false, format feedback:

Plan quality check FAILED (score: {{score}}/100)

Failing dimensions (score < 6):
{{#each dimensions where score < 6}}
- {{name}}: {{score}}/10 — needs improvement
{{/each}}

Action required: Revise the plan and re-run verification.

Dimension Reference

Dimension	What it Measures	Good Signals
requirement-coverage	Are all stated requirements addressed by tasks?	Keywords: requirement, feature, user story
task-completeness	Do tasks have clear ownership and deliverables?	Keywords: implement, create, update, agent
dependency-validity	Are task dependencies explicit and cycle-free?	Keywords: depends, blocked by, after, before
scope-sanity	Is the plan scope realistic and bounded?	Phase/wave structure, bounded scope language
artifact-wiring	Are output artifacts explicitly listed per task?	Keywords: artifact, output, file, deliverable
risk-assessment	Are risks identified with mitigations?	Keywords: risk, mitigation, fallback, contingency
testability	Are acceptance criteria and test hooks defined?	Keywords: test, verify, acceptance, criteria
estimation-quality	Are effort/time estimates provided?	Keywords: estimate, hours, days, effort, wave

Enforcement Hooks

Input validated against schemas/input.schema.json before execution. Output contract defined in schemas/output.schema.json.

Anti-Patterns

• Never skip verification to "save time" — a bad plan costs more to fix mid-execution
• Never treat a marginal pass (60-69) as a strong pass — flag and iterate
• Never modify verifier scoring thresholds per-project — the 60/100 gate is standard
• Never run verifier on a partial/draft plan — only run on complete plans

Memory Protocol

Before starting:

Read .claude/context/memory/learnings.md for past plan quality issues and common failures.

After completing:

• Failed plan with specific dimension scores → Append to .claude/context/memory/issues.md
• New plan pattern discovered → Append to .claude/context/memory/learnings.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Related Skills

• plan-generator — Generates plans that should pass this verifier
• verification-before-completion — Gates task completion (complements plan gating)
• tdd — TDD methodology that complements testability dimension scoring

Implementation Reference

• Verifier lib: .claude/lib/validation/plan-quality-verifier.cjs
• Tests: tests/lib/validation/plan-quality-verifier.test.cjs
• Schema: .claude/skills/plan-quality-verifier/schemas/input.schema.json