# Caseyharalson Orrery Refine Plan > Refine Plan Skill - Skill: `tomevault-io/caseyharalson-orrery-refine-plan` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/caseyharalson-orrery-refine-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/caseyharalson-orrery-refine-plan/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/caseyharalson-orrery-refine-plan --- # Refine Plan Skill ## When to Use Use this skill when you have an existing plan and want to **improve it** before execution. Unlike Simulate (which is read-only), Refine analyzes the plan and implements improvements directly. **Triggers:** - "This plan needs work" - "Can you improve this plan?" - "Check if this plan is ready for execution" - "The context seems thin, can you fill it out?" - "Make sure this plan follows the schema" - Plan validation failed and you need to fix issues **Skip if:** - No plan exists yet (use Discovery first) - You want to explore the plan interactively (use Simulate instead) - You need to fundamentally restructure the plan or change outcomes (use Discovery) - The plan is already validated and well-formed --- ## How to Do It ### Step 1: Load and Parse the Plan Read the plan file and understand its structure: - Parse the YAML to identify all steps, dependencies, and metadata - Note the outcomes (what success looks like) - Map the dependency graph - Identify which steps have context_files, risk_notes, and other optional fields Announce what you've loaded: ``` I've loaded [plan name]. It has [N] steps with [X] outcomes. Let me analyze it for improvements. ``` ### Step 2: Analyze for Improvements Check each improvement category systematically. Build a list of findings. For each issue found, note: - What the problem is - Which step(s) it affects - What the fix should be ### Step 3: Report Findings or Exit Clean **If no improvements found:** ``` The plan looks good. No structural issues, dependencies are correct, context is sufficient for autonomous execution, and acceptance criteria are testable. Ready for execution. ``` Exit cleanly without modifying the file. **If improvements found:** ``` Found [N] improvements: - [Category]: [Brief description] (steps X, Y) - [Category]: [Brief description] (step Z) Implementing these changes now. ``` ### Step 4: Implement Improvements Write the updated plan directly to the file. The PostToolUse hook will automatically validate the plan after writing. Make changes in order of impact: 1. Schema compliance issues first (required fields) 2. Structural issues (malformed steps) 3. Dependency issues (missing deps, cycles) 4. Context and criteria improvements ### Step 5: Summarize Changes After writing: ``` Updated the plan with [N] changes: - Added missing deps to steps 2.1, 2.3 (they now depend on install step 0.1) - Expanded context for step 1.2 to include integration patterns - Made criteria in step 3.1 more specific and testable - Added risk_notes to step 2.1 (high complexity) Plan validated successfully. ``` --- ## Improvement Categories Check the plan against these categories: ### Structural Issues - **Missing required fields**: Every step must have `id`, `description`, `context`, `requirements`, `criteria` - **Malformed step IDs**: IDs should follow `{feature}.{step}` format (e.g., "1.1", "2.3") - **Missing metadata**: Plan must have `created_at`, `created_by`, `outcomes` - **Empty arrays**: Requirements and criteria must have at least one item **Fix approach:** Add missing fields with sensible defaults or flag for user input if context is unclear. ### Dependency Issues - **Missing install step deps**: If step "0.1" installs dependencies, ALL subsequent steps should include "0.1" in their deps - **Circular dependencies**: Step A depends on B, B depends on A - **Missing sequential deps**: Step uses output from another step but doesn't declare the dependency - **Unnecessary sequential deps**: Steps that could run in parallel but have artificial dependencies **Dependency Detection Rules:** When checking if a step is missing dependencies, apply these rules: 1. **Installation/Setup First**: Any step that creates files depends on the step that installs dependencies or sets up the project structure. 2. **File Creation Before Use**: If step B reads or modifies files created by step A, then B depends on A. Check the `files` field. 3. **Import Dependencies**: If step B's code will import from modules created in step A, then B depends on A. 4. **Test Infrastructure**: Steps that include tests depend on the step that sets up test infrastructure. 5. **API Before Consumers**: Backend API endpoints must exist before frontend components that call them. 6. **Schema Before Implementation**: Database schema/migrations must exist before repository code. **Fix approach:** Add missing deps, remove circular deps, suggest parallelization opportunities. ### Parallelization Issues - **Unsafe parallel marking**: Steps marked `parallel: true` that share files or have logical dependencies - **Over-serialization**: Steps that could safely run in parallel but are all marked serial - **Plan order ignored**: Steps relying on plan position instead of explicit dependencies **Parallelization Safety Rules:** Mark a step as `parallel: true` ONLY when ALL of these are true: 1. **No file overlap**: The step's `files` do not overlap with any other parallel-eligible step at the same dependency level. 2. **No logical dependency**: The step does not use outputs, types, or patterns established by a peer step. 3. **Independent domain**: The step works in a different area of the codebase (e.g., frontend vs backend, different features). **Common parallel-safe patterns:** - Backend setup + Frontend setup (different directories) - Independent feature implementations (no shared files) - Documentation + Docker config (no code dependencies) **Common parallel-unsafe patterns:** - Two steps modifying the same configuration file - API routes that share model definitions - Components that import from each other **Default to `parallel: false`** when uncertain. Sequential execution is always safe; incorrect parallelization causes merge conflicts and bugs. **Plan ordering matters:** Serial steps act as implicit barriers for subsequent steps. A serial step earlier in the plan must start before later steps can begin, even without explicit deps. Place foundational work early in the plan. **Fix approach:** Remove unsafe parallel markings, add `parallel: true` where safe, ensure plan order reflects execution intent. ### Context Quality Thin context prevents autonomous execution. Check for: - **Vague context**: "Add the feature" without explaining what, where, or why - **Missing context_files**: Steps that reference existing code but don't list which files to read - **No integration guidance**: Steps that modify existing code without explaining the patterns to follow - **Assumed knowledge**: Context assumes the agent knows project-specific conventions **Fix approach:** Expand context with specifics. Add relevant context_files. Reference existing patterns. ### Acceptance Criteria Quality Criteria must be **specific** and **testable**. Check for: - **Vague criteria**: "Works correctly" or "Handles errors" - **Untestable criteria**: "Code is clean" or "Performance is good" - **Missing criteria**: Steps with empty or single-item criteria arrays - **Inconsistent scope**: Criteria that don't match what the step actually delivers **Fix approach:** Rewrite vague criteria with specific, observable conditions. Add missing criteria based on requirements. **Examples:** - Bad: "Error handling works" - Good: "Returns 400 status with error message when input validation fails" - Bad: "Component renders correctly" - Good: "Component renders loading skeleton while data fetches; displays chart when data arrives; shows error message if API returns 500" ### Risk Coverage - **High complexity without notes**: Steps with many requirements or external integrations but no risk_notes - **Missing edge cases**: Obvious failure modes not acknowledged - **Underestimated steps**: Steps that look simple but have hidden complexity **Fix approach:** Add risk_notes for complex steps. Call out edge cases and potential blockers. ### Schema Compliance Validate against `../discovery/schemas/plan-schema.yaml`: - Field types match schema (arrays vs strings, required vs optional) - Status values are valid enum values - All referenced step IDs in deps actually exist **Fix approach:** Correct type mismatches, fix invalid values, remove dangling dep references. --- ## Reference Schema The plan schema is defined at: ``` agent/skills/discovery/schemas/plan-schema.yaml ``` Key required fields: - **metadata**: `created_at`, `created_by`, `outcomes` - **steps[].required**: `id`, `description`, `context`, `requirements`, `criteria` - **steps[].optional**: `status`, `deps`, `parallel`, `files`, `context_files`, `commands`, `risk_notes` --- ## Exit Conditions Exit **without changes** when: - All required fields are present - Dependencies are correct (no cycles, install steps properly referenced) - Context is sufficient for autonomous execution - Criteria are specific and testable - No schema violations In this case, report: ``` Plan analysis complete. No improvements needed. - Structure: Valid - Dependencies: Correct - Context: Sufficient - Criteria: Testable - Schema: Compliant Ready for execution. ``` --- ## Example Dialogue ``` User: /refine-plan analytics-dashboard.yaml Agent: I've loaded the analytics dashboard plan. It has 6 steps delivering two outcomes. Let me analyze it for improvements. Found 4 improvements: 1. Dependency issues: Steps 1.1, 2.1, 2.2 don't depend on the install step (0.1) 2. Context quality: Step 1.2 has thin context - doesn't explain the caching pattern 3. Criteria quality: Step 2.3 has vague criteria ("error handling works") 4. Risk coverage: Step 2.1 (Chart.js integration) has no risk_notes despite complexity Implementing these changes now. [Writes updated plan file] Updated the plan: - Added "0.1" to deps for steps 1.1, 2.1, 2.2 - Expanded step 1.2 context with reference to cache.ts middleware pattern - Rewrote step 2.3 criteria: "Shows loading skeleton during fetch", "Displays error toast with retry button on API failure" - Added risk_notes to step 2.1: "Chart.js bundle size impact - verify no significant increase to main bundle" Plan validated successfully. Ready for execution. ``` --- ## Boundaries ### What Refine Does - Fixes structural issues (missing fields, malformed data) - Corrects dependency problems - Expands thin context - Improves vague criteria - Adds missing risk notes - Ensures schema compliance ### What Refine Does NOT Do - **Change outcomes**: If the outcomes are wrong, use Discovery - **Restructure the plan**: Refine improves existing steps, doesn't reorganize them - **Add new features**: Refine doesn't expand scope - **Remove steps**: Refine improves steps, doesn't delete them - **Question the approach**: That's what Simulate is for If you find yourself wanting to fundamentally change the plan (new steps, different outcomes, restructured features), suggest returning to Discovery instead. --- ## Common Pitfalls - **Over-refining**: Making changes that don't materially improve the plan. If it's good enough, say so. - **Changing scope**: Refine improves quality, not content. Don't add features or change what the plan delivers. - **Forgetting validation**: Always let the PostToolUse hook validate after writing. If validation fails, fix and write again. - **Missing the install step pattern**: This is the most common dependency issue. Always check if 0.1 exists and if subsequent steps depend on it. - **Vague improvements**: Don't just say "expanded context" - show specifically what changed. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/caseyharalson) — claim your Tome and manage your conversions.