Writing Plans Skill

Name: writing-plans
Rating: 92
Author: BaxterCooper

Core Principle: Exact code in plan, not descriptions of code.

Plan Structure

Every plan MUST follow this format:

Header (Required)

markdown

# Feature: [Name]

> Execute with: `orchestration` skill → `executor` subagent

**Goal**: [Single sentence describing what will be built]

**Architecture**: [2-3 sentences on how it fits into existing system]

**Stack**: [Technologies/frameworks involved]

Task Format (Required)

Each task MUST include ALL of:

1. File References (Exact Paths)

markdown

## Task N: [Descriptive Name]

**Files**:
- Create: `src/components/LoginForm.tsx`
- Modify: `src/pages/auth.tsx`
- Test: `tests/LoginForm.test.tsx`

2. Steps with Complete Code

markdown

**Steps**:

1. Write failing test:
   ```typescript
   import { render, screen } from '@testing-library/react';
   import { LoginForm } from '../src/components/LoginForm';

   test('renders email input', () => {
     render(<LoginForm />);
     expect(screen.getByLabelText('Email')).toBeInTheDocument();
   });

•

Run test:

bash

npm test -- LoginForm.test.tsx

Expected output:

code

FAIL  tests/LoginForm.test.tsx
✕ renders email input
Cannot find module '../src/components/LoginForm'

•

Implement:

typescript

export function LoginForm() {
  return (
    <form>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" />
    </form>
  );
}

•

Run test:

bash

npm test -- LoginForm.test.tsx

Expected output:

code

PASS  tests/LoginForm.test.tsx
✓ renders email input (42ms)

•

Commit:

bash

git add src/components/LoginForm.tsx tests/LoginForm.test.tsx
git commit -m "feat(auth): add LoginForm component with email input"

code


---

## Forbidden Language

These phrases are NOT ALLOWED in plans:

| Forbidden | Why | Write Instead |
|-----------|-----|---------------|
| "Add validation" | Vague | Show exact validation code |
| "Update the file" | Vague | Show exact changes |
| "Handle errors" | Vague | Show error handling code |
| "Should pass" | Uncertain | Show exact expected output |
| "Similar to X" | Vague | Show actual code |
| "As needed" | Vague | Specify exactly what's needed |
| "etc." | Vague | List all items |

---

## Verification Checklist

Before finalizing a plan, verify:

- [ ] Every file has exact path
- [ ] Every code block is complete (not `// ...`)
- [ ] Every test shows expected failure message
- [ ] Every test shows expected pass message
- [ ] Every command shows expected output
- [ ] No forbidden language used

---

## Example: Good vs Bad

### Bad Plan Task
```markdown
## Task 1: Add Login Form

Create a login form component with email and password fields.
Add validation and error handling as needed.
Write tests for the component.

Good Plan Task

markdown

## Task 1: Add Login Form

**Files**:
- Create: `src/components/LoginForm.tsx`
- Test: `tests/LoginForm.test.tsx`

**Steps**:

1. Write failing test:
   ```typescript
   import { render, screen, fireEvent } from '@testing-library/react';
   import { LoginForm } from '../src/components/LoginForm';

   test('shows error when email is empty', () => {
     render(<LoginForm onSubmit={jest.fn()} />);
     fireEvent.click(screen.getByRole('button', { name: 'Login' }));
     expect(screen.getByText('Email is required')).toBeInTheDocument();
   });

•
Run test:
bash
```
npm test -- LoginForm.test.tsx
```
Expected: FAIL - "Cannot find module"

[... continue with complete implementation ...]

code


---

## Integration with Orchestration

Plans created with this skill feed directly into:

| Downstream | How |
|------------|-----|
| `orchestration` | Tasks already decomposed |
| `executor` | Exact code provided |
| `tdd` | Tests specified first |
| `verification` | Expected output defined |

Chain: `writing-plans` → `orchestration` → `executor` → `verification`

---

## File Location

Save plans to: `docs/plans/YYYY-MM-DD-<feature-name>.md`

Example: `docs/plans/2025-01-20-login-form.md`