Plan Validation

Plan Validation

> Quality gate ensuring every implementation plan meets enterprise standards > before being presented to the user for approval.

---

Overview

This skill is used by the planner agent as a self-validation checklist after creating a plan but BEFORE presenting it to the user. The planner applies the validation pipeline below to its own output, verifying against the quality schema (plan-schema.md), checking cross-cutting concerns, and calculating a completeness score. Plans that fail validation are revised before presentation.

Invocation: The planner runs this checklist during /plan workflow step 3.5. This is NOT a separate agent — the planner validates its own plan against these criteria.

---

Validation Pipeline

Step 1: Task Size Classification

Determine the task size from the plan content:

| Indicator | Classification | |-----------|---------------| | Plan references 1-2 files | Trivial | | Plan references 3-10 files | Medium | | Plan references 10+ files | Large | | Estimated effort 4 hours | Large |

Use the HIGHER classification when indicators conflict.

Step 2: Schema Compliance

Verify all required sections are present and substantively populated:

Tier 1 Sections (Always Required):

| # | Section | Check | |---|---------|-------| | 1 | Context & Problem Statement | Present and >= 2 sentences | | 2 | Goals & Non-Goals | Both goals AND non-goals stated | | 3 | Implementation Steps | Steps have file paths and verification criteria | | 4 | Testing Strategy | Test types specified with coverage targets | | 5 | Security Considerations | Substantive content or explicit "N/A — [reason]" | | 6 | Risks & Mitigations | At least 1 risk with severity and mitigation | | 7 | Success Criteria | Measurable, checkable outcomes |

Tier 2 Sections (Required for Medium/Large):

| # | Section | Check | |---|---------|-------| | 8 | Architecture Impact | Components and files identified | | 9 | API / Data Model Changes | Schemas defined (or N/A with reason) | | 10 | Rollback Strategy | Concrete undo procedure | | 11 | Observability | Logging/metrics plan | | 12 | Performance Impact | Assessment provided | | 13 | Documentation Updates | Specific docs identified | | 14 | Dependencies | Blockers and dependents listed | | 15 | Alternatives Considered | At least 1 rejected alternative with reasoning |

Step 3: Cross-Cutting Verification

These sections MUST be non-empty regardless of task domain:

| Section | Acceptable Content | |---------|-------------------| | Security Considerations | Specific requirements from rules/security.md OR N/A — [valid justification] | | Testing Strategy | At least unit test plan with coverage target OR N/A — [valid justification] | | Documentation Updates | Specific docs listed OR N/A — no docs affected |

Unacceptable: Empty section, placeholder text, section completely missing.

Step 4: Specificity Audit

Verify that implementation steps are actionable, not vague:

| Vague (FAIL) | Specific (PASS) | |-------------|-----------------| | "Update the component" | "Add onSubmit handler to src/components/LoginForm.tsx" | | "Add tests" | "Create tests/auth.test.js with login success/failure cases" | | "Fix the bug" | "Change line 42 of lib/parser.js: replace == with ===" | | "Style the UI" | "Add Tailwind classes flex gap-4 p-6 to Header.tsx" |

Rule: Every implementation step MUST include a file path.

Step 5: Completeness Scoring

Calculate the score using the rubric from plan-schema.md:

Tier 1 Scoring (60 points max):

| Section | Points | |---------|--------| | Context & Problem Statement | 10 | | Goals & Non-Goals | 10 | | Implementation Steps | 10 | | Testing Strategy | 10 | | Security Considerations | 10 | | Risks & Mitigations | 5 | | Success Criteria | 5 |

Tier 2 Scoring (20 additional points):

| Section | Points | |---------|--------| | Architecture Impact | 4 | | API / Data Model Changes | 3 | | Rollback Strategy | 3 | | Observability | 2 | | Performance Impact | 2 | | Documentation Updates | 2 | | Dependencies | 2 | | Alternatives Considered | 2 |

Score Rules:

• Section present and substantively populated = full points
• Section present but placeholder/minimal = half points
• Section missing = 0 points
• "N/A" with valid justification = full points

Domain Enhancement Scoring (bonus/penalty on top of tier score):

• For each domain in matchedDomains from the loading engine:
• Domain enhancer section present and substantive = +2 bonus points
• Domain matched but enhancer section missing = -2 penalty points
• Domain matched with "N/A — [valid reason]" = no bonus, no penalty
• Maximum domain bonus: +6 points (3 domains × 2 points)
• Domain scoring does not change the pass threshold — it provides additional quality signal

Step 6: Verdict

| Condition | Verdict | Action | |-----------|---------|--------| | Score >= 70% of tier max | PASS | Present plan to user with score | | Score < 70% of tier max | REVISE | Identify gaps, revise, re-validate |

Revision Protocol:

1. Identify the specific missing or weak sections
2. Provide targeted instructions to the planner for revision
3. Re-run validation after revision
4. Maximum 2 revision cycles — then present with warnings

---

Output Format

After validation, append to the plan:

## Plan Quality Assessment

**Task Size**: [Trivial/Medium/Large]
**Quality Score**: [X]/[max] ([percentage]%) [+N domain bonus / -N domain penalty]
**Verdict**: [PASS/REVISE]

### Validation Results

| Check | Status |
|-------|--------|
| Schema Compliance | [sections present]/[sections required] |
| Cross-Cutting Concerns | [All addressed / Missing: X, Y] |
| Specificity Audit | [All steps have file paths / X steps lack paths] |
| Domain Enhancement | [N domains matched, N enhancer sections present] |
| Rules Consulted | [list of rule files referenced] |
| Matched Domains | [list from loading engine] |

---

Integration

• Invoked by: /plan workflow (step 3.5, between plan creation and user presentation)
• Depends on: plan-schema.md for scoring rubric, domain-enhancers.md for domain sections
• Feeds into: Plan quality score shown to user alongside the plan
• Learning: Quality scores are logged to .agent/contexts/plan-quality-log.md for adaptive improvement

---

Principles

1. Validate, don't block: The goal is quality improvement, not gatekeeping. After 2 revision cycles, present the plan with warnings rather than blocking indefinitely.
2. Score transparently: The user sees the quality score and understands what was checked.
3. Learn from outcomes: Post-implementation retrospectives compare predicted vs. actual to calibrate future scoring.
4. Cross-cutting is non-negotiable: Security, testing, and documentation sections must ALWAYS be addressed. This is the single most impactful quality gate.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: besync-labs
• Source: besync-labs/antigravity-ai-kit
• License: MIT
• Homepage: https://besync-labs.github.io/antigravity-ai-kit/

Install and usage instructions live in the source repository linked above.