feat: add refining-plan skill for iterative plan pressure-testing#622
Closed
feat: add refining-plan skill for iterative plan pressure-testing#622
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Plan file is now auto-detected from conversation context or most recent file in docs/plans/ — only asks user as last resort. Max iterations defaults to 5 without prompting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Skill: refine-plan → refining-plan (matches gerund convention) - Directory: skills/refine-plan/ → skills/refining-plan/ - Command: commands/refine-plan.md → commands/refining-plan.md - Roles: simulator → plan-simulator, fixer → plan-fixer - Prompt files: simulator-prompt.md → plan-simulator-prompt.md, etc. - Remove novel "Context Detection" section (no other skill has this) - Remove novel "never ask user" red flags (no other skill has these) - Update all cross-references in writing-plans Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a new refining-plans skill with simulator and fixer subagent prompts, a refine-plans command, and updates the writing-plans skill to include a “Refine first” execution option plus clarified post-save execution workflows. Changes
Sequence DiagramsequenceDiagram
actor User
participant WritingPlan as Writing-Plans Skill
participant RefineCmd as Refine-Plans Command
participant RefineSkill as Refining-Plans Skill
participant Simulator as Plan Simulator
participant Fixer as Plan Fixer
participant Report as Refinement Report
User->>WritingPlan: Request plan execution
WritingPlan->>WritingPlan: Select execution option
alt Refine first
WritingPlan->>RefineCmd: Invoke refine-plans
RefineCmd->>RefineSkill: Start refining workflow
RefineSkill->>Simulator: Phase 1: detect domain & simulate
Simulator->>Simulator: Phase 2: simulate across lenses, produce findings
Simulator-->>Report: Emit findings (Critical/Important/Minor)
RefineSkill->>Fixer: Dispatch targeted fixes with findings
Fixer->>Fixer: Apply minimal fixes, document changes
Fixer-->>Report: Return FIXED/Skipped entries
RefineSkill->>RefineSkill: Evaluate convergence / escalate if needed
RefineSkill-->>Report: Phase 3: final report & handoff
Report-->>WritingPlan: Deliver refined plan
WritingPlan->>User: Proceed with execution (refined)
else Subagent-Driven (skip refinement)
WritingPlan->>User: Spawn fresh subagent per task (no refinement)
else Parallel Session (skip refinement)
WritingPlan->>User: Batch execution in separate session with checkpoints
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
skills/refining-plan/plan-fixer-prompt.md (1)
46-52: Preserve severity + requirement in fixer report for round-to-round traceability.Current
changes/skippedentries only keep concern text. Addingseverityandrequirementfields makes audits and escalation checks more reliable.Proposed report-format refinement
changes: - - finding: [original concern] + - severity: [critical|important] + requirement: [exact text from plan] + finding: [original concern] action: [what was changed] location: [which section] skipped: - - finding: [concern] + - severity: [critical|important|minor] + requirement: [exact text from plan] + finding: [concern] reason: [why skipped — e.g., "minor severity", "conflicts with plan intent"]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/refining-plan/plan-fixer-prompt.md` around lines 46 - 52, Update the report template under the YAML blocks "changes" and "skipped" to include severity and requirement fields for each entry; specifically augment each "finding" object (used in the changes list with keys finding/action/location) to also include "severity" and "requirement", and do the same for skipped entries (keys finding/reason) so they become finding/reason/severity/requirement — modify the plan-fixer prompt template where the "changes:" and "skipped:" examples are defined to add these fields and ensure any code that renders or validates these entries expects and preserves "severity" and "requirement".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/refining-plan/plan-simulator-prompt.md`:
- Around line 5-72: The opening fenced code block that contains "Task tool
(general-purpose):" is missing a language identifier (MD040); update the opening
``` to ```text (and keep the closing ``` unchanged) so the block is explicitly
marked as text—locate the triple-backtick fence that wraps the plan prompt and
add the language tag to satisfy markdownlint.
In `@skills/refining-plan/SKILL.md`:
- Around line 148-158: The listed execution options in the refining-plan SKILL
("Subagent-Driven (this session)", "Parallel Session (separate)", "Refine
again") are numbered differently than the mapping used in the writing-plans
skill where option 1 is “Refine first”; update the numbering/order in this
SKILL.md so it matches the sequence in skills/writing-plans/SKILL.md (make
“Refine again” the first option, then the batch/parallel option, then
subagent-driven), and ensure the REQUIRED SUB-SKILL lines
(superpowers:refining/plans vs superpowers:executing-plans vs
superpowers:subagent-driven-development) are reordered to match each option
label so the option numbers and required sub-skill mappings are consistent
across both skills.
- Around line 133-144: The fenced code block starting at the "## Plan Refinement
Complete" header lacks a language tag (MD040); update the opening fence from ```
to ```markdown so the block is explicitly marked as Markdown (i.e., change the
fenced block that contains "**Plan:** {plan_path}" etc. to start with
```markdown) and keep the closing ``` as-is to satisfy the linter.
---
Nitpick comments:
In `@skills/refining-plan/plan-fixer-prompt.md`:
- Around line 46-52: Update the report template under the YAML blocks "changes"
and "skipped" to include severity and requirement fields for each entry;
specifically augment each "finding" object (used in the changes list with keys
finding/action/location) to also include "severity" and "requirement", and do
the same for skipped entries (keys finding/reason) so they become
finding/reason/severity/requirement — modify the plan-fixer prompt template
where the "changes:" and "skipped:" examples are defined to add these fields and
ensure any code that renders or validates these entries expects and preserves
"severity" and "requirement".
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 0c028e54-01a2-4c68-93e0-843877baca19
📒 Files selected for processing (5)
commands/refining-plan.mdskills/refining-plan/SKILL.mdskills/refining-plan/plan-fixer-prompt.mdskills/refining-plan/plan-simulator-prompt.mdskills/writing-plans/SKILL.md
- Add language tags to fenced code blocks (MD040) - Add severity/requirement fields to fixer report format - Rename command to refine-plan.md (matches brainstorm/write-plan/execute-plan convention) - Trim SKILL.md from 807 to 570 words (merge checklist into process, remove redundant sections) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
TDD REFACTOR: Both baseline and skill-guided tests identified that "critical count unchanged → CONVERGED" is wrong — if criticals persist because fixer failed, that's ESCALATE, not CONVERGED. Fixed convergence rules: unchanged criticals now escalate to user. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/refining-plan/plan-fixer-prompt.md`:
- Around line 13-21: The fixer prompt in
skills/refining-plan/plan-fixer-prompt.md is missing the original snapshot
required by Phase 2 in skills/refining-plan/SKILL.md; add a clearly labeled
"Original Snapshot" section (e.g., "## Original Snapshot" with a placeholder
like {original_snapshot} or {snapshot}) above or near the "Read the plan file
now." block so the fixer receives the original snapshot input as specified by
Phase 2, ensuring the placeholder name matches the workflow's expected variable.
- Around line 46-56: The fixer report schema in
skills/refining-plan/plan-fixer-prompt.md uses fields "finding" and "action"
that must be renamed to match the simulator's finding schema ("concern" and
"recommendation") to avoid brittle round-trip parsing; update the "changes:" and
"skipped:" entries to replace finding→concern and action→recommendation
(preserve other keys: severity, requirement, location, reason) and ensure any
consumers/serializers that reference those keys are updated accordingly to use
"concern" and "recommendation" consistently to align with
skills/refining-plan/plan-simulator-prompt.md.
In `@skills/refining-plan/SKILL.md`:
- Around line 81-83: Update the escalation rule text so it requires the same
critical issue to persist rather than just an unchanged critical count: replace
the current line "Critical count unchanged (round 2+) or same concern persists
(round 3+) → ESCALATE" with a conditional that explicitly checks for the same
critical persisting across rounds (e.g., "Same critical(s) persist across rounds
(round 2+) → ESCALATE"); keep the "Drift detection: plan changed direction →
ESCALATE" rule unchanged. Ensure the wording mentions that unchanged counts
alone do not trigger escalation unless at least one identical critical (by
description/id) remains.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: cac45af0-431d-458e-a5a0-bd6bffaa6b2b
📒 Files selected for processing (4)
commands/refine-plan.mdskills/refining-plan/SKILL.mdskills/refining-plan/plan-fixer-prompt.mdskills/refining-plan/plan-simulator-prompt.md
✅ Files skipped from review due to trivial changes (1)
- commands/refine-plan.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/refining-plan/plan-simulator-prompt.md
…ention Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…d alignment, escalation rule Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
skills/refining-plans/SKILL.md (1)
104-113: Consider softening “stable” wording in the execution prompt.“Plan refined and stable” conflicts slightly with offering “Refine again.” A neutral phrase like “Plan refinement pass complete” would reduce ambiguity.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/refining-plans/SKILL.md` around lines 104 - 113, Replace the header phrase "Plan refined and stable. Three execution options:" with a neutral wording such as "Plan refinement pass complete. Three execution options:" (or similar) in the SKILL.md section that lists the three execution options (the heading text and any identical occurrences), so it no longer implies finality while keeping the three options and required sub-skill lines (superpowers:subagent-driven-development and superpowers:executing-plans) unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@skills/refining-plans/SKILL.md`:
- Around line 104-113: Replace the header phrase "Plan refined and stable. Three
execution options:" with a neutral wording such as "Plan refinement pass
complete. Three execution options:" (or similar) in the SKILL.md section that
lists the three execution options (the heading text and any identical
occurrences), so it no longer implies finality while keeping the three options
and required sub-skill lines (superpowers:subagent-driven-development and
superpowers:executing-plans) unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 2820accc-8212-46f1-89e3-2e63416d5b27
📒 Files selected for processing (5)
commands/refine-plans.mdskills/refining-plans/SKILL.mdskills/refining-plans/plan-fixer-prompt.mdskills/refining-plans/plan-simulator-prompt.mdskills/writing-plans/SKILL.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/refining-plans/plan-fixer-prompt.md`:
- Around line 13-17: The prompt currently instructs the fixer to read/write a
filesystem path ({plan_path}) which contradicts the subagent contract; update
the "Plan File" section in plan-fixer-prompt.md to accept the full plan text as
an injected variable (e.g., {plan_text}) instead of a file path and remove any
wording that implies file I/O or direct filesystem access; also change any
instructions that tell the fixer to write back to {plan_path} so the fixer
instead returns the modified plan text as its output (or a clearly labeled
{fixed_plan} variable) for the controller to persist.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 1ba44f04-fed2-41da-9789-218ca83f2c48
📒 Files selected for processing (1)
skills/refining-plans/plan-fixer-prompt.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Owner
|
Thanks for this! The plan pressure-testing concept is solid. v5.0.0 addressed this with built-in plan review loops — after each chunk of a plan is written, a reviewer subagent checks it for completeness, spec alignment, and task decomposition quality. Closing as the idea landed in a different form. — Claude (claude-opus-4-6, Claude Code 2.1.71, session 64908a66-5c98-4c79-b0f7-1aa7eac2dcb0) |
Author
|
Awesome! .. looking forward to v5.0.0 |
5 tasks
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
refining-planskill that iteratively pressure-tests implementation plans before execution (simulate → fix → converge loop)New Files
skills/refining-plan/SKILL.md— Main skill with checklist, flowcharts, and convergence rulesskills/refining-plan/plan-simulator-prompt.md— Prompt template for simulation subagentskills/refining-plan/plan-fixer-prompt.md— Prompt template for fixer subagentcommands/refining-plan.md—/refining-plancommand entry pointModified Files
skills/writing-plans/SKILL.md— Updated plan header template and execution handoff to offer refinement as option 1Design
The skill follows a simulate → evaluate → fix → check convergence loop (max 5 iterations). It detects the plan's domain to generate contextual role profiles for subagents. Convergence is checked via diminishing returns, recurring criticals, and drift detection. The controller provides full plan text to subagents (no file reading overhead).
Test plan
/refining-planloads skill and announces usage/writing-plansnow shows refine-plan as option 1 in handoff🤖 Generated with Claude Code