plan-approval

Plan-Approval Skill

Purpose

Enable user control over AI actions by requiring explicit approval for complex or risky changes, preventing mistakes and ensuring alignment with user intent.

When to Use This Skill

Automatically activates when you mention:

• Creating or reviewing plans
• Approval or confirmation needed
• Proposed changes or approach
• Want to see plan before execution
• Complex or risky operations
• Need user sign-off

The Problem: No User Control

Without plan approval:

• ❌ AI jumps straight to implementation
• ❌ No chance to review approach
• ❌ Mistakes expensive to undo
• ❌ User left out of decision process
• ❌ No learning from rejections

With plan approval:

• ✅ User reviews before execution
• ✅ Can modify or reject approach
• ✅ Prevents costly mistakes
• ✅ User maintains control
• ✅ AI learns from feedback

Core Principles

1. User is Always in Control

Never execute without approval for:

• Database schema changes
• Breaking API changes
• Dependency updates
• Architecture refactors
• File deletions
• Deployment actions

2. Plans are Detailed

Good plans include:

• What will be done (specific files/changes)
• Why this approach (rationale)
• What alternatives were considered
• What risks exist
• What the impact is
• How long it will take

3. Approval is Explicit

Require clear user response:

• ✅ "approve", "yes", "proceed", "looks good"
• ❌ Silence, vague response, "maybe"
• ⚠️ "modify: [changes]" triggers plan revision

4. Learning from Feedback

Track approved/rejected plans:

• Store approved approaches (do more like this)
• Store rejected approaches (avoid in future)
• Learn user preferences over time

When to Require Approval

Always Require Approval

✅ Database changes:

• Schema migrations
• RLS policy changes
• Data migrations
• Index additions

✅ Breaking changes:

• API signature changes
• Function signature changes
• Component prop changes

✅ Architecture changes:

• New dependencies
• Framework changes
• State management approach
• Routing structure

✅ Risky operations:

• File deletions
• Bulk updates
• Production deployments

Optional Approval

⚠️ Complex features (> 5 files affected) ⚠️ Refactoring (multiple components) ⚠️ Performance optimization (cache strategies)

No Approval Needed

❌ Simple changes:

• Bug fixes (< 10 lines)
• Documentation updates
• Code formatting
• Minor UI tweaks

Rule of Thumb: If user might say "wait, not like that!", require approval.

Plan Structure

Minimal Plan Template

# [Feature/Change Name]

## Summary
[1-2 sentence overview]

## What Will Change
- File 1: [what changes]
- File 2: [what changes]
- Database: [migrations if any]
- Dependencies: [new packages if any]

## Why This Approach
[Rationale for chosen approach]

## Risks
- Risk 1: [description + mitigation]
- Risk 2: [description + mitigation]

## Estimated Time
[How long to implement]

---
**Approve to proceed**, or reply with modifications

Comprehensive Plan Template

# [Feature/Change Name]

## Summary
[2-3 sentence overview of the change and its purpose]

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Proposed Approach

### Architecture
[High-level architecture description]

### Implementation Steps
1. **Step 1**: [Description]
   - Files: [list]
   - Changes: [brief description]
   - Risk: [if any]

2. **Step 2**: [Description]
   - Files: [list]
   - Changes: [brief description]
   - Risk: [if any]

[Continue for all steps...]

### Files to Create (3)
1. `path/to/file1.ts` - [Purpose]
2. `path/to/file2.ts` - [Purpose]
3. `path/to/file3.ts` - [Purpose]

### Files to Modify (2)
1. `path/to/existing1.ts` - [What will change]
2. `path/to/existing2.ts` - [What will change]

### Database Changes
**Migration**: `supabase/migrations/xxx_add_feature.sql`
- Add table: `feature_table`
- Add column: `users.feature_flag`
- Add RLS policy: `feature_access_policy`

### Dependencies
**New**:
- package-name@^1.0.0 (Purpose: [why])

**Updates**:
- existing-package: 1.0.0 → 2.0.0 (Reason: [why])

## Alternatives Considered

### Alternative 1: [Name]
**Approach**: [Description]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Why not chosen**: [Reason]

### Alternative 2: [Name]
**Approach**: [Description]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Why not chosen**: [Reason]

## Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk 1] | Medium | High | [How to prevent/handle] |
| [Risk 2] | Low | Medium | [How to prevent/handle] |

## Breaking Changes

⚠️ **API Changes**:
- `oldFunction()` → `newFunction()` signature changed
- Migration path: [How to update]

⚠️ **Database Changes**:
- Table `old_name` renamed to `new_name`
- Migration script: [Path]

## Testing Strategy
- [ ] Unit tests for [components]
- [ ] Integration tests for [flows]
- [ ] Manual testing: [scenarios]

## Rollback Plan
If this fails:
1. [Step to revert]
2. [Step to restore]
3. [Data recovery if needed]

## Estimated Time
- Implementation: [X hours]
- Testing: [Y hours]
- **Total**: [Z hours]

---

## Approval

**Reply with**:
- `approve` - Proceed with this plan
- `reject` - Cancel, don't proceed
- `modify: [your changes]` - Adjust plan first

Approval Workflow

Step 1: Generate Plan

User: "Add Stripe payment integration"

Claude:
"I'll create a plan for Stripe integration first.

[Generates detailed plan using template]

Review the plan above. Reply:
- 'approve' to proceed
- 'reject' to cancel
- 'modify: [changes]' to adjust
"

Step 2: Wait for Explicit Approval

Valid approvals:

• "approve"
• "yes, proceed"
• "looks good"
• "go ahead"
• "lgtm" (looks good to me)

Modifications:

• "modify: use Stripe Checkout instead of Elements"
• "change: store payment methods in Supabase"
• "add: webhook handling"

Rejections:

• "reject"
• "no"
• "cancel"
• "let's do something different"

Step 3: Execute or Revise

If approved:

1. Save plan to .claude/memory/plans/approved/
2. Execute implementation
3. Track progress in dev docs
4. Mark complete when done

If modified:

1. Update plan with user's changes
2. Re-present revised plan
3. Wait for approval again

If rejected:

1. Save to .claude/memory/plans/rejected/ with reason
2. Learn from rejection
3. Don't proceed

Step 4: Track Execution

## Plan Execution Status

**Plan ID**: stripe-integration-2025-01-15
**Status**: In Progress
**Approved**: 2025-01-15 10:00
**Started**: 2025-01-15 10:05

**Progress**:
- [x] Step 1: Install Stripe SDK
- [x] Step 2: Create Stripe client
- [ ] Step 3: Implement checkout flow (IN PROGRESS)
- [ ] Step 4: Add webhook handler
- [ ] Step 5: Test payment flow

**Current**: Implementing checkout flow in app/api/checkout/route.ts
**Next**: Add webhook handler for payment events

Plan Storage

Directory Structure

.claude/memory/plans/
├── proposed/                    # Plans awaiting approval
│   └── stripe-integration-2025-01-15.json
├── approved/                   # Approved plans
│   └── stripe-integration-2025-01-15.json
├── rejected/                   # Rejected plans (learn from these)
│   └── alternative-approach-2025-01-14.json
└── completed/                  # Completed implementations
    └── stripe-integration-2025-01-15.json

Plan File Schema

{
  "plan_id": "stripe-integration-2025-01-15",
  "created": "2025-01-15T10:00:00Z",
  "status": "approved" | "proposed" | "rejected" | "in_progress" | "completed",
  "summary": "Add Stripe payment integration for subscriptions",
  "approved_at": "2025-01-15T10:05:00Z",
  "started_at": "2025-01-15T10:10:00Z",
  "completed_at": null,
  "user_modifications": [
    "Use Stripe Checkout instead of Elements",
    "Store payment methods in Supabase"
  ],
  "files_to_create": [
    "lib/stripe/clie