plan-approval

What this skill does

# 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

```markdown
# [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

```markdown
# [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

```markdown
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

```markdown
## 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

```json
{
  "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/cli