Plan Refine (Iterative Convergence)
Automates the "Iterative Convergence" pattern for architectural planning (inspired by automated_plan_reviser_pro).
Purpose
To taking a raw, potentially "wild" implementation plan and refining it through multiple rounds of adversarial critique and rewriting, converging on a stable, secure, and robust specification.
Philosophy: 5 rounds of automated critique = 1 round of expensive human review.
When to Use This Skill
Trigger phrases:
- "refine the plan"
- "optimize implementation plan"
- "run APR"
- "architectural review"
- "check for convexity"
Use when:
- You have written a draft
implementation_plan.mdor similar. - You are about to start a complex P0/P1 feature.
- You want to ensure edge cases and security flaws are caught before coding.
Workflow
1. Draft Initial Plan
Create your best-effort plan in a markdown file (e.g., implementation_plan.md).
Ensure it covers:
- Context/Goal
- Proposed Changes
- Verification Plan
2. Run Refinement Loop
Navigate to the directory containing your plan and run the refinement script.
/home/fengning/agent-skills/plan-refine/scripts/refine_plan.py implementation_plan.md --rounds 3
(Default is 3 rounds. Use 5-10 for critical security features).
3. Review Convergence
The script will output:
implementation_plan_r1_critique.mdimplementation_plan_r1.md- ...
implementation_plan_r3.md(Final)
Compare the original and final plan:
diff implementation_plan.md .apr_rounds/implementation_plan_r3.md
4. Adopt and Commit
If the refined plan is better (it usually is), overwrite your original plan:
cp .apr_rounds/implementation_plan_r3.md implementation_plan.md
Then commit the plan to git to lock in the architecture.
Integration Points
With Beads
- Use this skill before breaking down a Beads epic into tasks.
- Attach the final plan to the Beads issue (or reference the commit).
With cc-glm
- This skill uses
cc-glmconfiguration (Claude 3.5 Sonnet/Opus) to perform the critique, ensuring high-reasoning capability.
Examples
Standard Usage:
User: "Refine the plan for the auth system."
Agent:
1. Locates implementation_plan.md
2. Runs: refine_plan.py implementation_plan.md --rounds 5
3. Reports: "Refinement complete. Major security flaw found in Round 1 (token storage). Fixed in Round 2. Converged in Round 4."
4. Updates implementation_plan.md