writing-plans

name	writing-plans
description	Use after brainstorming, before implementation. Breaks work into discrete, actionable tasks with clear verification points.

Writing Plans

Core Principle

After brainstorming and getting user approval, break the work into a detailed, step-by-step plan BEFORE coding.

When to Use This Skill

• After completing brainstorming skill and getting user approval
• User explicitly asks for an implementation plan
• Task has 3+ distinct steps
• Work involves multiple files or systems
• Dependencies between tasks exist

The Iron Law

NEVER start implementation without a written plan for non-trivial work.

A plan:

• Forces you to think through the full scope
• Identifies dependencies and potential issues early
• Gives the user visibility into your approach
• Provides checkpoints to verify progress
• Prevents "I forgot to do X" mistakes

Plan Writing Protocol

Step 1: Announce the Planning Phase

Template:

Great! Now let me create a detailed implementation plan.

I'm using the writing-plans skill to break this down into discrete tasks.

Step 2: Break Down into Tasks

Each task should be:

• Discrete: Can be completed independently
• Actionable: Clear what to do
• Verifiable: Clear how to verify it's done
• Appropriately sized: 5-30 minutes of work

Task Format:

## Task [Number]: [Clear, action-oriented name]

**Purpose**: What this accomplishes
**Actions**:
- [Specific step 1]
- [Specific step 2]
**Files affected**: [List of files]
**Verification**: How to confirm this works
**Dependencies**: Requires Task X to be completed first

Step 3: Identify Dependencies

Make dependencies explicit:

Task 2 depends on Task 1 (needs database schema)
Task 5 depends on Tasks 2, 3, 4 (needs all API endpoints)

This prevents:

• Starting tasks out of order
• Discovering blocking issues mid-implementation
• Inefficient back-and-forth

Step 4: Add Verification Checkpoints

For each task, specify:

• How to verify: What test/check confirms success
• Expected outcome: What should happen
• Rollback: How to undo if it fails

Example:

**Verification**:
- Run `php artisan test --filter=AuthenticationTest`
- Expected: All tests pass
- If fails: Rollback migration with `php artisan migrate:rollback`

Step 5: Create TodoWrite Entries

MANDATORY: Convert plan to TodoWrite todos

Never work through plans mentally. Always create explicit todos:

I'm creating todos for each task in the plan.

Each plan task becomes ONE todo item:

• Use the task name as the content
• Provide activeForm (present continuous)
• Start with status: pending

Step 6: Estimate Complexity

For each task, indicate:

• Simple: Straightforward, low risk
• Moderate: Some complexity, medium risk
• Complex: High complexity, needs extra care

This helps users understand time investment.

Step 7: Get User Approval

Template:

Here's my implementation plan with [X] tasks.

Does this plan make sense? Any tasks I should add, remove, or change?

Wait for approval before moving to executing-plans skill.

Plan Template

# Implementation Plan: [Feature Name]

## Overview
**Goal**: [What we're building]
**Approach**: [Brief summary of chosen approach from brainstorming]
**Estimated tasks**: [Number]
**Estimated time**: [Rough estimate]

## Prerequisites
- [ ] [Prerequisite 1]
- [ ] [Prerequisite 2]

## Tasks

### Task 1: [Name]
**Purpose**: [What this accomplishes]
**Complexity**: Simple/Moderate/Complex
**Actions**:
1. [Specific step]
2. [Specific step]
**Files affected**:
- `path/to/file1.php`
- `path/to/file2.php`
**Verification**: [How to verify]
**Dependencies**: None

### Task 2: [Name]
**Purpose**: [What this accomplishes]
**Complexity**: Simple/Moderate/Complex
**Actions**:
1. [Specific step]
2. [Specific step]
**Files affected**:
- `path/to/file3.php`
**Verification**: [How to verify]
**Dependencies**: Task 1

[Continue for all tasks...]

## Risk Assessment
**Potential issues**:
- [Risk 1]: [Mitigation]
- [Risk 2]: [Mitigation]

## Rollback Plan
If something goes wrong:
1. [Rollback step 1]
2. [Rollback step 2]

## Success Criteria
When complete, we should have:
- [ ] [Criteria 1]
- [ ] [Criteria 2]
 [ ] All tests passing
 [ ] Documentation updated

Red Flags (Plan is Inadequate)

• ❌ Vague tasks: "Set up authentication" → Too broad
• ❌ No verification: Can't tell if task succeeded
• ❌ Missing dependencies: Tasks in wrong order
• ❌ No file paths: Unclear what needs changing
• ❌ No rollback: Can't undo if it fails
• ❌ Only 1-2 tasks: Probably not detailed enough

Common Rationalizations to Reject

• ❌ "I'll figure it out as I go" → Plan first, code second
• ❌ "The plan is in my head" → Write it down
• ❌ "Plans take too long" → Planning SAVES time
• ❌ "I'll just start and see what happens" → Recipe for failure
• ❌ "It's a simple feature" → Simple features still need plans

Integration with Other Skills

Before writing-plans: Use brainstorming skill After writing-plans: Use executing-plans skill During execution: Use database-backup skill for database tasks After completion: Use code-review and verification-before-completion skills

Examples

Example 1: Add User Authentication

# Implementation Plan: User Authentication with Laravel Sanctum

## Overview
**Goal**: Add token-based authentication to API
**Approach**: Laravel Sanctum with email/password login
**Estimated tasks**: 6
**Estimated time**: 60-90 minutes

## Prerequisites
- [ ] Laravel project is set up
- [ ] Database is configured and backed up
- [ ] Paratest is installed

## Tasks

### Task 1: Install and Configure Sanctum
**Purpose**: Add Sanctum package to project
**Complexity**: Simple
**Actions**:
1. Run `composer require laravel/sanctum`
2. Publish configuration: `php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"`
3. Run migration: `php artisan migrate` (with backup!)
4. Add Sanctum middleware to `app/Http/Kernel.php`
**Files affected**:
- `composer.json`
- `config/sanctum.php`
- `app/Http/Kernel.php`
**Verification**:
- `php artisan route:list` shows Sanctum routes
- No errors during migration
**Dependencies**: None

### Task 2: Create Authentication Controller
**Purpose**: Handle login/logout/register endpoints
**Complexity**: Moderate
**Actions**:
1. Create `app/Http/Controllers/AuthController.php`
2. Implement `register()` method with validation
 Implement  method with token generation
 Implement  method with token revocation
:
  (new)
: Controller file exists with all methods
: Task 1


: Expose authentication endpoints
: Simple
:
 Add routes to :
 POST /register
 POST /login
 POST /logout (protected)
:
 
:  shows new routes
: Task 2


: Ensure auth works correctly
: Moderate
:
 Create 
 Test registration with valid data
 Test registration with invalid data
 Test login with correct credentials
 Test login with wrong credentials
 Test logout functionality
 Test protected route access
:
  (new)
: Tests exist (don't run yet)
: Task 3


: Verify implementation works
: Simple
:
 Use database-backup skill (MANDATORY)
 Run 
 Verify all tests pass
: None
: All authentication tests pass
: Task 4, database-backup skill


: Document new endpoints
: Simple
:
 Add PHPDoc comments to AuthController methods
 Generate OpenAPI docs: 
 Verify endpoints appear in 
:
 
 API documentation (auto-generated)
: Can see auth endpoints in API docs
: Task 5


:
 : Ensure database is backed up (Task 1)
 : Common issue is missing .env.testing config
 : Check Sanctum middleware is in Kernel.php


If something goes wrong:
 Rollback database: 
 Remove Sanctum package: 
 Restore from backup if needed
 Delete created files


When complete, we should have:
 [ ] Users can register via POST /register
 [ ] Users can login and receive token via POST /login
 [ ] Users can logout via POST /logout
 [ ] Protected routes require valid token
 [ ] All authentication tests pass
 [ ] API documentation includes auth endpoints

Example 2: Add Database Activity Logging

# Implementation Plan: User Activity Logging

## Overview
**Goal**: Track user actions in activity_logs table
**Approach**: Database table with observer pattern
**Estimated tasks**: 5
**Estimated time**: 45-60 minutes

## Prerequisites
- [ ] Database is backed up (MANDATORY)
- [ ] User model exists

## Tasks

### Task 1: Create Migration for Activity Logs
**Purpose**: Add activity_logs table
**Complexity**: Simple
**Actions**:
1. Backup database (MANDATORY - use database-backup skill)
2. Create migration: `php artisan make:migration create_activity_logs_table`
3. Add columns: id, user_id, action, description, ip_address, user_agent, timestamps
4. Add indexes on user_id and created_at
5. Run migration: `php artisan migrate`
**Files affected**:
- `database/migrations/[timestamp]_create_activity_logs_table.php` (new)
**Verification**:
- Table exists: `php artisan db:show --table=activity_logs`
- Has correct columns and indexes
**Dependencies**: None (but requires database-backup skill FIRST)

### Task 2: Create ActivityLog Model
**Purpose**: Eloquent model for activity_logs
**Complexity**: Simple
**Actions**:
1. Create `app/Models/ActivityLog.php`
2. Define fillable fields
3. Add relationship to User model
4. Add cast for created_at (immutable)
**Files affected**:
- `app/Models/ActivityLog.php` (new)
**Verification**: Model file exists with proper structure
**Dependencies**: Task 1

### Task 3: Create Activity Logger Service
**Purpose**: Centralized logging logic
**Complexity**: Moderate
:
 Create 
 Implement  method that captures:
 User ID (from auth)
 Action name
 Description
 IP address (from request)
 User agent (from request)
 Add helper function for easy access
:
  (new)
: Service class exists with log() method
: Task 2


: Log authentication events
: Simple
:
 Update 
 Log "user.registered" on registration
 Log "user.loggedout" on logout
:
 
: Code review - logging calls added
: Task 3


: Ensure logging works
: Moderate
:
 Create 
 Test that registration creates log entry
 Test that login creates log entry
 Test that logout creates log entry
 Test that log contains correct data (IP, user agent)
 Backup database (MANDATORY)
 Run tests: 
:
  (new)
: All activity log tests pass
: Task 4, database-backup skill


:
 : Database backup ensures we can rollback
 : Add cleanup task (30 days retention)
 : Indexes on userat mitigate this


If something goes wrong:
 Rollback migration: 
 Remove logging calls from AuthController
 Delete ActivityLogger service
 Delete ActivityLog model


When complete, we should have:
 [ ] activityid, action, IP, user agent, timestamp
 [ ] All tests pass
 [ ] No performance degradation

Authority

This skill is based on:

• Software engineering best practice: Design before implementation
• Agile methodology: Break work into small, verifiable increments
• Empirical evidence: Planned work is 3-5x more likely to succeed
• Professional experience: Plans prevent forgotten requirements

Social Proof: Professional developers ALWAYS plan before coding. No exceptions.

Your Commitment

Before using this skill, confirm:

• I will ALWAYS create a written plan for non-trivial work
• I will BREAK DOWN work into discrete, verifiable tasks
• I will CREATE TodoWrite entries for all tasks
• I will GET USER APPROVAL before executing the plan

---

Bottom Line: Plans don't take extra time - they reveal the time required. Write the plan, then execute it systematically.