Add reviewing-plans skill + namespace docs/plans by project

[banga87]

Motivation

Working as a full-stack engineer with a monorepo-style setup (parent repo with /frontend-repo and /backend-repo underneath, Claude Code sitting at the parent level), I found that the first pass of writing-plans output often has issues — especially in larger, more complex codebases. Wrong naming conventions, file paths that don't match the actual project structure, vague task instructions, missing dependencies between tasks.

These are small things that slip through the cracks, but they compound during execution. A subagent hits a wrong path, uses the wrong naming form, or has to make a judgment call the plan should have specified — and the "one-shot" execution fails.

My goal is to push AI-driven development toward reliably completing large, complex, long-running projects in one shot. The more time you spend "sharpening the axe" before cutting the tree, the cleaner the execution. Working across backend and frontend projects in a single Claude Code session requires extra diligence, and I found that adding a plan review step before execution did wonders for my own workflow.

Not everyone works this way, but for complex multi-repo or full-stack projects, this step meaningfully reduces execution failures.

What this adds

1. Reviewing-plans skill

A new reviewing-plans skill that slots optionally between writing-plans and executing-plans / subagent-driven-development. It verifies every claim in the plan against the actual codebase before execution begins.

The 3-Example Rule

The core mechanism: for every naming convention, file path pattern, or structural claim in the plan, the reviewer must find 3+ existing examples in the codebase that confirm or contradict it. This catches the subtle convention drift that general review misses.

6 Review Dimensions

1. Pattern Alignment (CRITICAL) — naming conventions, file paths, frontmatter format, config fields
2. Task Atomicity — tasks properly scoped for independent subagent execution
3. Step Granularity — one action per step, no judgment calls required
4. Dependency & Ordering — explicit declarations, correct sequencing
5. Execution Risk — ambiguity, platform compatibility, vague modifications
6. Completeness — structural completeness, TDD structure, code formatting

Design doc cross-referencing

When reviewing a plan, the skill now checks for a design doc in the same project folder. If one exists, it cross-references it when assessing completeness — catching cases where the plan silently dropped or changed requirements from the design.

Resolution Options

After review, the user chooses:

• Surgical updates — targeted edits to the existing plan for minor fixes
• Versioned plan — create -v2.md for significant restructuring

2. Namespaced plan directories

I work on many projects simultaneously — multiple Claude Code sessions running at once across different features. The docs/plans/ folder started filling up fast: designs, plans, and reviews all dated and mixed together. The mental load of sifting through a flat directory of interleaved artifacts from different features got old quickly.

All plan-producing skills now save artifacts to project subdirectories:

Before: docs/plans/2025-11-22-opencode-support-design.md
After: docs/plans/opencode-support/2025-11-22-design.md

• Agent infers the project name from the topic/feature in kebab-case — no extra prompting needed
• Filenames simplified (-plan.md, -design.md, -review.md) since the project folder provides context
• Concrete examples and explicit guardrails added after testing showed agents missed the convention without them
• Backward compatible — execution skills take explicit file paths, so existing flat files continue to work

3. /review-plan command

Added a /review-plan command for easy invocation of the reviewing-plans skill, matching the existing /brainstorm, /write-plan, and /execute-plan commands.

4. README updates

• Added reviewing-plans to the workflow (step 4, marked optional) and skills library
• Documented the docs/plans/<project>/ directory convention

Integration

• writing-plans updated to mention optional review step in execution handoff
• executing-plans updated to list reviewing-plans as optional workflow skill
• All 5 skills referencing docs/plans/ updated with namespaced paths
• Fully optional — simple plans skip directly to execution

Testing

Reviewing-plans skill (TDD for documentation)

Following the writing-skills methodology (RED-GREEN-REFACTOR):

• RED: Created a synthetic plan with ~15 deliberate issues, dispatched a baseline reviewer without the skill. It caught 15 surface-level issues but missed gerund naming conventions, task atomicity violations, description CSO, structural completeness, and platform compatibility.
• GREEN: Wrote the skill targeting those specific gaps. Re-tested — gerund naming and 3-example rule now caught, but task atomicity and structural completeness still missed.
• REFACTOR: Added concrete examples to Task Atomicity dimension, explicit frontmatter/description checks to Pattern Alignment, structural completeness checks to Completeness, and platform compatibility to Execution Risk. Re-tested — all gaps closed, issue count went from 15 (baseline) to 25 (with skill).

Namespaced plan paths

• Grep all skills for docs/plans/ references — no remaining old flat-path patterns
• Tested /brainstorm end-to-end — identified stale plugin cache issue, synced cache, confirmed convention works
• Tested /write-plan saves to docs/plans/<project>/YYYY-MM-DD-plan.md
• Tested /review-plan saves review report alongside plan in same project folder
• Community testing on diverse codebases (looking for feedback)

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new "reviewing-plans" skill (detailed workflow to verify implementation plans against the codebase) and integrates it as an optional pre-execution step. Also updates plan save paths to project-scoped folders and adjusts several planning/execution skill docs and README to reference the new step and paths.

Changes

Cohort / File(s)	Summary
New Plan Review Skill skills/reviewing-plans/SKILL.md	Adds a comprehensive "reviewing plans" skill: when to use it, step-by-step review process, 3-example verification rule, evaluation dimensions, report format, decision outcomes (APPROVED / APPROVED WITH CHANGES / NEEDS REVISION), and saving/versioning instructions.
Executing & Workflow Integration skills/executing-plans/SKILL.md, commands/review-plan.md, README.md	Adds optional superpowers:reviewing-plans reference to pre-execution flow, adds commands/review-plan.md directive to invoke the skill, and updates README workflow ordering and skills list to include reviewing-plans plus related public skills and step reordering.
Plan-writing & Design Save Path Changes skills/writing-plans/SKILL.md, skills/brainstorming/SKILL.md	Changes plan/design save paths to project-scoped directories docs/plans/<project>/..., adds rules to infer/create project directory, prohibits saving directly under docs/plans/, and updates examples and execution handoff messaging.
Minor plan-path updates / examples skills/subagent-driven-development/SKILL.md, skills/requesting-code-review/SKILL.md	Updates example plan file paths used in plan intake and code-review example to the new project-scoped location(s).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix: require worktree setup before subagent-driven-development and executing-plans #382: Also modifies skills/executing-plans/SKILL.md by adding pre-execution requirements; strongly related to the reviewing-plans integration.

Poem

🐰✨ I hop and I check each bright plan in the glade,
Counting three examples, every path I parade.
I cite the proof, score risk, and offer a choice,
Approve, tweak, or return — let the codebase rejoice! 🥕📜

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding a new reviewing-plans skill and reorganizing plan storage into project-namespaced directories.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the motivation, design decisions, implementation details, and testing approach for the reviewing-plans skill and namespaced plan directories.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

skills/writing-plans/SKILL.md (1)

101-111: ⚠️ Potential issue | 🟡 Minor

Fix multi-line quote formatting for the execution prompt.

The opening quote at Line 101 isn’t closed until Line 111, spanning multiple lines and likely rendering oddly. Prefer removing the quotes or using a blockquote.

Proposed fix

-**"Plan complete and saved to `docs/plans/<filename>.md`.**
+**Plan complete and saved to `docs/plans/<filename>.md`.**
@@
-**Which approach?"**
+**Which approach?**

🤖 Fix all issues with AI agents

In `@skills/reviewing-plans/SKILL.md`:
- Around line 68-73: The markdown fences in skills/reviewing-plans/SKILL.md are
missing language identifiers (triggers MD040); update each fenced code block
(e.g., the block containing "Plan says: Create
`src/services/UserAuth.service.ts`" and the larger "## Plan Review: [Plan Name]"
example) to include an appropriate language tag such as text or markdown (e.g.,
replace ``` with ```text or ```markdown) so linting passes, and apply the same
change to all other affected blocks around lines 177-214.
- Line 151: The prose contains the lowercase proper noun "markdown" in the
sentence fragment "frontmatter should be raw YAML, not wrapped in markdown code
fences"; update that occurrence to "Markdown" (capitalize the M) in SKILL.md so
the proper noun is used consistently in the plan's prose.