Planning

Planning Skill

Overview

This skill provides comprehensive planning workflows for features and system changes. It focuses on the research and clarification phase - gathering context, exploring architecture, and asking good questions before spec generation.

When to Use This Skill

Use this skill when:

• In planning/plan mode (auto-trigger if possible)
• User says: "plan this", "research this feature", "help me understand"
• User asks: "what do I need to know before implementing X?"
• Before generating specs with /cmd:generate-spec
• Need to explore codebase patterns and architecture

Core Workflow

1. Research Phase

• Explore codebase for similar existing features
• Identify which domain/area this belongs in
• Locate related types, schemas, services, routes
• Check test patterns in relevant areas
• Review database models (if applicable)
• Use references/research-checklist.md for systematic exploration

2. Context Gathering

• Internal docs: Check .agent/docs/ for relevant patterns
• CLAUDE.md: Review project conventions and rules
• context7 MCP (if available): Fetch external library docs
  • Check for mcp__context7__* tools
  • Use for React, Fastify, Prisma, etc. documentation
  • Fall back to WebFetch/WebSearch if not available
• See references/context-sources.md for detailed guidance

3. Clarification (If Needed)

Ask clarifying questions ONE AT A TIME if implementation approach is unclear:

• Don't use the Question tool
• Use this template:

  **Question**: [Your question]
  **Suggestions**:
  
  1. [Option 1] (recommended - why)
  2. [Option 2]
  3. Other - user specifies
  

• See references/clarification-questions.md for examples and templates

4. Complexity Assessment

• Estimate file count and scope
• Identify cross-cutting concerns
• Assess if new patterns needed or extending existing
• Determine context requirements for implementation
• Flag if complexity suggests breaking into smaller features
• See references/complexity-assessment.md for detailed rubric

5. Handoff to Spec Generation

Prepare clear summary for /cmd:generate-spec:

• What was found during research
• Existing patterns to follow
• Recommended architecture approach
• Initial complexity estimate
• Unresolved questions (if any)
• Suggest: "Ready to generate spec with /cmd:generate-spec?"

Key Principles

Do

• ✅ Research deeply - explore codebase thoroughly
• ✅ Ask questions conversationally (text-based, ONE AT A TIME)
• ✅ Document findings clearly
• ✅ Leverage context7 MCP when available for external docs
• ✅ Check .agent/docs/ for internal patterns
• ✅ Provide architecture recommendations with rationale
• ✅ Prepare handoff context for spec generation

Don't

• ❌ Use AskUserQuestion tool (breaks exploratory flow)
• ❌ Create specs or files (that's /cmd:generate-spec's job)
• ❌ Ask multiple questions at once
• ❌ Skip research phase
• ❌ Make assumptions without checking codebase first

Complementary to Slash Commands

This skill complements existing spec generation:

User request → Planning skill (research) → /cmd:generate-spec (spec creation)

• Planning skill: Research, clarification, architecture exploration
• /cmd:generate-spec: Spec writing, file creation, index updates
• /generate-prd: PRD creation for larger features
• /generate-feature: Alternative spec format

Level of Involvement

Moderate - Balance depth with efficiency:

• Research deeply: Explore codebase, find patterns, identify constraints
• Ask strategically: ONE question at a time with context-based suggestions
• Document findings: Summarize architecture, existing patterns, complexity
• Prepare handoff: Create clear context for spec generation
• Don't overstep: Leave spec writing and file creation to slash commands

References

See references/ directory for detailed guidance:

• research-checklist.md - Systematic codebase exploration
• clarification-questions.md - Question templates and examples
• complexity-assessment.md - Complexity rubric and indicators
• context-sources.md - How to leverage context7, internal docs, codebase

Example Usage

User: "Plan adding user notifications feature"

Planning skill workflow:
1. Research: Find existing notification patterns (grep for "notification", "alert", etc.)
2. Check: `.agent/docs/` for notification architecture (if exists)
3. Context7: Fetch WebSocket or push notification docs (if needed)
4. Ask: "What type of notifications? In-app, email, push, or all three?"
   Suggestions:
   1. In-app only (recommended - simpler, use WebSocket pattern)
   2. Email integration (adds complexity, need mail service)
   3. Other - user specifies
5. Wait for answer, continue clarification as needed
6. Assess: Initial complexity ~5-6/10 (multiple files, WebSocket integration)
7. Output: "Found WebSocket handler pattern in X, session events in Y.
   Recommend: Extend existing WebSocket system, add Notification model,
   create UI toast component. Estimated 5-6/10 complexity."
8. Suggest: "Ready to generate spec with /cmd:generate-spec?"

Integration Notes

• context7 MCP: Optional but recommended for external docs
  • Install: https://context7.com/
  • Check availability before use
  • Graceful fallback to WebFetch/WebSearch
• Permission mode: Works best in plan mode (read-only exploration)
• Output: Text summary, not files (spec generation creates files)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.