Plan Validator

简体中文

Plan Validator is an evidence-oriented Agent Skill for reviewing an existing plan before execution. It evaluates whether the plan is feasible, worth choosing, and ready to begin without turning every review into a generic risk checklist.

The skill is designed for technical plans, agent workflows, product and business proposals, migrations, rollouts, operational procedures, purchasing decisions, research plans, travel logistics, and other multi-step decisions where assumptions and failure costs matter.

Why It Is Different

Plan Validator focuses on the claims that can change the decision:

• Separates feasibility, value, and execution readiness.
• Traces the real producer-consumer path instead of reviewing prose alone.
• Distinguishes confirmed, disconfirmed, inconclusive, and unchecked claims.
• Records the method, observed result, scope, freshness, and decision effect of evidence.
• Converts manageable uncertainty into conditions with an owner, deadline, pass threshold, and failure action.
• Uses an explicit evidence budget and stopping rules to avoid endless research.
• Treats missing evidence as a reason to hold, not as proof that a plan is wrong.
• Does not treat agreement between multiple models as factual verification.

Recommendation States

Every review ends with one semantic recommendation, rendered in the user's language:

• Proceed — decisive conditions are satisfied and residual uncertainty is acceptable.
• Proceed with conditions — reversible work may begin, but named checkpoints control further execution.
• Hold — decisive evidence, input, authority, or a repairable plan element is missing.
• Do not proceed — a core premise is disconfirmed, a hard constraint makes success infeasible, or the downside exceeds the stated tolerance.

Installation

Codex

git clone https://github.com/chosuicide/plan-validator.git ~/.codex/skills/plan-validator

Restart Codex if the skill is not discovered immediately.

Claude Code

git clone https://github.com/chosuicide/plan-validator.git ~/.claude/skills/plan-validator

Other Agent Skills-compatible runtimes can place this repository in their configured skills directory.

Usage

Example requests:

Review this rollout plan and identify the assumptions that could invalidate it.

这个方案合理吗？请重点检查技术可行性和现在是否适合执行。

Stress-test this migration plan. Do not revisit the database choice; focus on data integrity and rollback readiness.

The skill should not activate for plan creation, copy-editing, simple factual questions, or execution-only requests.

Review Depth

• Quick — low-cost, reversible decisions with few dependencies.
• Standard — meaningful cost, coordination, or dependency risk.
• Deep — material safety, legal, security, privacy, data-integrity, production, financial, or irreversible risk.

Depth is determined by exposure, uncertainty, dependency reach, and reversibility. Mentioning money, software, APIs, or multiple agents does not automatically make a plan Deep.

Examples

• Technical migration plan
• Business pilot plan
• Sample evidence-backed review

The sample review intentionally avoids claiming that code, system behavior, performance, or rollback was verified when only the written plan was available.

Evaluation Data

The repository includes two evaluation sets:

• Trigger cases — 8 positive and 8 near-miss negative cases.
• Behavior cases — 6 scenarios covering high-risk migration, business value, Quick mode, language adaptation, current external facts, and incremental re-review.

For a fair comparison, run the same model with identical tools and context in fresh sessions:

1. Baseline without the skill.
2. Treatment with the skill loaded.
3. Blind the outputs before judging them.
4. Compare scope adherence, evidence honesty, actionable conditions, recommendation calibration, over-review, hallucinated verification, token use, and tool calls.

Do not provide examples/sample-review.md to the generating model during evaluation; it is a human reference and would leak the expected answer.

The current evaluation files are structurally validated test data. They are not published benchmark results.

Repository Structure

plan-validator/
|-- SKILL.md
|-- agents/
|   `-- openai.yaml
|-- examples/
|   |-- technical-plan.md
|   |-- business-plan.md
|   `-- sample-review.md
|-- evals/
|   |-- trigger-cases.json
|   `-- behavior-cases.json
|-- README.md
`-- README.zh-CN.md

Validation

The skill passes the official structural validator:

Skill is valid!

Structural validation confirms frontmatter and packaging. It does not prove behavioral quality; use the included eval cases for that purpose.

Design Constraints

• Review-first and read-only by default.
• No mandatory extra confirmation turn when a labeled assumption is sufficient.
• No automatic multi-agent review.
• No fabricated praise or quota-driven findings.
• No general reliability claim from a single successful test.
• No rejection based only on missing evidence.

Status

The skill is ready for practical testing. Behavioral evals have been defined but have not yet been executed as a published benchmark.