Skip to content

Latest commit

 

History

History
187 lines (130 loc) · 6.35 KB

plan-validate.md

File metadata and controls

187 lines (130 loc) · 6.35 KB
name description
plan-validate
2-layer plan validation: instant structural checks + trigger-based specialist agents. Auto-fixes issues using ADRs and first principles. Every issue must be resolved before execution.

Plan Validate — 2-Layer Validation

Independently validate the plan produced by /plan-start. No code is written. Run /clear after this command before running /plan-execute.

Validation is separate from planning by design: validators that didn't write the plan are not anchored to its assumptions.

Prerequisite

A committed plan file must exist at docs/plans/plan-{name}.md. If multiple plans exist, list them and ask the user which to validate.

Layer 1: Structural Validation

Run immediately, no agents required. Check the plan document for:

Format & Completeness

  • All required sections present (Summary, Decisions, Architecture, Tasks, Test Plan, Out of Scope)
  • Each task has: description, files affected, acceptance criteria, layer assignment

Dependency Chain

  • No circular dependencies between tasks
  • Tasks in higher layers only depend on tasks in lower layers
  • All stated dependencies exist in the plan

File Existence

  • Every file listed for modification actually exists in the codebase (use Glob)
  • New files are in appropriate directories per project conventions

ADR Consistency

  • Plan decisions align with ADRs created during /plan-start
  • No contradiction with existing ADRs in docs/adr/

CLAUDE.md Compliance

  • Plan respects all hard rules in CLAUDE.md
  • No first principles violations (no workarounds, no backward-compat shims)

Test Coverage

  • Every new function/component has a corresponding test task
  • TDD-marked tasks have failing test written before implementation task

Record all Layer 1 issues with severity (BLOCKER / WARNING / INFO) before proceeding to Layer 2.

Layer 2: Specialist Review

Select agents by applying trigger rules to the plan content. No user input needed — triggers are objective.

Validation agent pool:

Agent Trigger Model
security-reviewer Auth, payments, PII, RBAC, new public APIs Opus
db-migration-reviewer New tables, columns, indexes, or migration files Opus
performance-reviewer New queries, resolvers, routes, or added dependencies Sonnet
design-system-reviewer New UI components or visual styling changes Sonnet
ux-reviewer New pages, forms, modals, or interaction patterns Sonnet
cross-platform-reviewer Changes touching both web and mobile, or shared packages Sonnet
native-app-reviewer Mobile screens, native UI package changes Sonnet
integration-reviewer New external services, libraries, or OTEL config Opus

Spawn triggered agents in parallel (Task tool, run_in_background: true). Each agent receives: the plan file, relevant ADRs, and targeted questions based on its domain.

Monitor via TaskOutput polling loop. Report progress to user.

Each agent must return structured findings:

FINDING: [BLOCKER|WARNING|INFO]
Location: [plan section or file reference]
Issue: [concrete description]
Risk: [what breaks if this isn't addressed]
Suggestion: [specific fix or alternative]

Auto-Fix Phase

Merge Layer 1 structural issues + Layer 2 specialist findings into a single issue list. Every issue must be resolved. No skipping.

Triage each issue:

Bucket A — Auto-resolve:

  • Issue matches an existing ADR decision → cite ADR, mark resolved
  • Issue matches a confirmed pattern in PATTERNS.md → cite pattern, mark resolved
  • Issue resolvable from first principles in CLAUDE.md → apply rule, mark resolved

Bucket B — Needs human input:

  • Novel architectural question not covered by existing decisions
  • Conflicting ADRs with no clear precedent
  • Blocker with no obvious resolution

For Bucket B items: present the issue, explain why it can't be auto-resolved, propose options, wait for decision. Record the decision in the plan's ## Decisions section and create a new ADR if it's architecturally significant.

Apply all fixes in one batch once all issues are triaged. Update the plan file. Commit the updated plan.

Issue Persistence

Record every issue in docs/plans/metrics/{name}.json under validation.issues:

{
  "id": "S-001",
  "layer": 1,
  "severity": "WARNING",
  "category": "test-coverage",
  "description": "No test task for the new webhook handler",
  "reporting_agent": "structural",
  "triage": "A",
  "resolution_source": "first-principles",
  "resolution": "Added test task in Layer 2 of the plan"
}

This data feeds /plan-metrics for pattern analysis over time.

Auto-Transition

If all issues are auto-resolved (Bucket A only): auto-start /plan-execute without asking.

If any human input was required (Bucket B): ask "All issues resolved. Ready to execute?" before proceeding.

Usage

/plan-validate

Picks up the most recent uncommitted plan automatically. Or specify:

/plan-validate plan-user-authentication

Output

Layer 1: Structural validation...
  ✓ Format complete
  ✓ Dependencies valid
  ⚠ WARNING S-001: Missing test task for webhook handler
  ✓ CLAUDE.md compliant

Layer 2: Triggering specialist agents...
  → security-reviewer (auth changes detected) [Opus]
  → db-migration-reviewer (new users table) [Opus]
  → performance-reviewer (new query in /api/users) [Sonnet]
  Monitoring... 1/3 complete... 2/3 complete... done.

  BLOCKER B-001 [security-reviewer]: JWT expiry not validated on refresh endpoint
  WARNING B-002 [db-migration-reviewer]: Migration lacks rollback strategy

Auto-fix phase:
  S-001 → auto-resolved (first principles: test coverage rule)
  B-001 → NEEDS INPUT (no existing ADR for JWT refresh strategy)
  B-002 → auto-resolved (ADR-0003: migration rollback pattern)

[User input requested for B-001]
Decision recorded. ADR-0011 created.

All 3 issues resolved. Plan updated.
→ Auto-starting /plan-execute

When to Use

Always — before any /plan-execute call. The cost of validation ($0.20-3.00) is negligible against the cost of discovering issues mid-execution.

See Also