plan-improve

Iteratively improve plan M2 scores with deterministic fixes and LLM-driven semantic updates.

Updated May 13, 2026
One-click install
npx skills add https://github.com/usetheodev/theo-ui --skill plan-improve
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: plan-improve
Source: https://github.com/usetheodev/theo-ui/tree/main/.claude/skills/plan-improve
Command: npx skills add https://github.com/usetheodev/theo-ui --skill plan-improve

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Iteratively improve a /to-plan plan's M2 score by applying deterministic fixes + LLM-driven semantic fixes via a ralph-loop-style autonomous iteration. Use after /plan-confidence returns a verdict below SHIPPABLE_WITH_CAVEATS (NON_SHIPPABLE or INVALID) and you want the system to attempt auto-improvement before human intervention.

Core Features & Use Cases

  • Deterministic fixes: apply weak-imperatives, remove loopholes, and inject TDD templates in bugfix tasks to lift scores.
  • LLM-driven semantic improvements: coordinate ADR alternatives and strategic guidance to converge toward the target verdict.
  • Loop orchestration: wraps the ralph-loop plugin with state handling, pre-flight guards, and post-promise sanity checks.

Quick Start

Trigger Plan-Improve to automatically lift a plan's M2 score by applying deterministic fixes and semantic improvements through a ralph-loop workflow.

Frequently Asked Questions about plan-improve

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automatically improve a plan confidence score after it fails validation?

To improve a plan confidence score automatically, you can run an autonomous iteration loop that applies deterministic fixes like removing loopholes and injecting TDD templates, followed by LLM-driven semantic updates. The system re-scores after each iteration until the target verdict is reached.

What is a ralph-loop autonomous iteration for plan improvement?

A ralph-loop autonomous iteration is an orchestration pattern that repeatedly applies fixes to a plan and re-scores it until a target confidence verdict is achieved. It wraps state handling, pre-flight guards, and post-promise sanity checks to converge NON_SHIPPABLE or INVALID plans toward a passing score.

How do I fix weak imperatives and loopholes in a project plan to lift its quality score?

To fix weak imperatives and loopholes in a project plan, apply deterministic fixes that replace ambiguous language and close gaps in task definitions. This process lifts the plan's M2 confidence score by ensuring tasks meet strict validation criteria before human review.

When should I use automated plan improvement instead of manually editing a rejected plan?

You should use automated plan improvement when a plan is judged NON_SHIPPABLE or INVALID and you want the system to attempt auto-improvement before human intervention. It coordinates ADR alternatives and strategic guidance to converge toward a target verdict without manual edits.

Does the plan improvement loop validate scores after each automated fix?

Yes, the plan improvement loop validates scores after each automated fix by re-scoring the plan during the ralph-loop iteration. It only emits a PLAN_IMPROVED promise and stops the autonomous cycle when the target verdict is successfully reached.

Can I coordinate ADR alternatives automatically to improve a plan's confidence verdict?

Yes, you can coordinate ADR alternatives automatically through LLM-driven semantic improvements during the autonomous iteration loop. This process adjusts architectural decision records and strategic guidance to converge the plan toward a SHIPPABLE_WITH_CAVEATS or higher verdict.