Plan Generation

Guide for generating high-quality plans from meta-prompt templates.

When to Use

• Generating plans from /chore, /bug, /feature templates
• Reviewing generated plans for completeness
• Ensuring plans follow team standards
• Improving plan quality and specificity

Plan Generation Process

Step 1: Understand the Request

Parse the high-level description:

Input: "Add user authentication with OAuth"

Extract:
- Domain: Authentication
- Scope: User-facing, OAuth protocol
- Complexity: Medium-high (external integration)

Step 2: Activate Reasoning

Use extended thinking for complex planning:

THINK HARD about:
- What files need to change?
- What are the dependencies?
- What could go wrong?
- How will we verify success?

Step 3: Explore the Codebase

Gather context before planning:

• Read README for project structure
• Identify relevant existing patterns
• Find test examples to follow
• Locate configuration files

Step 4: Fill the Template

Complete every section with specifics:

## Relevant Files
- src/auth/OAuthProvider.ts (create)
- src/auth/index.ts (modify - add export)
- src/config/oauth.ts (create)
- tests/auth/oauth.test.ts (create)

Step 5: Validate Plan Quality

Check against quality criteria before finalizing.

Quality Criteria

Every plan should meet these standards:

Specificity

Bad: "Update the component" Good: "Update UserProfile.tsx to add loading state on line 45"

Actionability

Bad: "Handle errors appropriately" Good: "Add try/catch in fetchUser(), log errors with console.error, show ErrorBoundary"

Completeness

All template sections filled:

• Description explains what and why
• Relevant Files lists all files to touch
• Tasks are numbered and specific
• Validation Commands are executable
• Notes capture edge cases

Testability

Every plan must include validation:

## Validation Commands

- Run `npm test -- auth` to verify unit tests pass
- Run `npm run e2e -- oauth` to verify integration
- Manual: Complete OAuth flow in browser

Plan Types and Focus Areas

Chore Plans

Focus on:

• Clear scope boundaries
• Idempotent operations
• Low-risk execution
• Quick validation

Bug Plans

Focus on:

• Root cause analysis
• Reproduction steps
• Regression prevention
• Before/after verification

Feature Plans

Focus on:

• User story alignment
• Implementation phases
• Testing strategy
• Acceptance criteria

Common Issues and Fixes

Vague Tasks

Problem: "Implement the feature" Fix: Break into specific sub-tasks with file references

## Step by Step Tasks
1. Create AuthContext in src/contexts/AuthContext.tsx
2. Add useAuth hook in src/hooks/useAuth.ts
3. Wrap App component with AuthProvider in src/App.tsx
4. Add login route in src/routes/index.tsx

Missing Files

Problem: Plan doesn't mention test files Fix: Always include test file creation/modification

## Relevant Files
- src/components/Login.tsx (create)
- src/components/Login.test.tsx (create) # Tests!

Unclear Validation

Problem: "Make sure it works" Fix: Specific commands with expected outcomes

## Validation Commands
- Run `npm test` - expect 0 failures
- Run `npm run build` - expect successful build
- Run `npm run lint` - expect 0 errors

Scope Creep

Problem: Plan addresses more than requested Fix: Stay focused on original request, note related work in Notes

## Notes
- Related: Login form could use accessibility improvements (separate chore)
- Related: Password reset flow needs similar OAuth option (separate feature)

Extended Thinking Triggers

Use these phrases to activate deeper reasoning:

Output Guidelines

Naming Convention

specs/[type]-[descriptive-name].md

Examples:
- specs/chore-update-dependencies.md
- specs/bug-fix-login-race-condition.md
- specs/feature-oauth-authentication.md

File Location

Always write plans to specs/ directory (or project-specific equivalent).

Format Consistency

Match the template's Plan Format exactly - don't add or remove sections.

Related Memory Files

• @template-engineering.md - How templates work
• @meta-prompt-patterns.md - Prompt hierarchy
• @plan-format-guide.md - Standard plan structures
• @fresh-agent-rationale.md - Why plan then implement separately

Version History

• v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101