name: pre-project-planning-assistant
description: Guides users through pre-project planning phase. Auto-activates when users ask about starting new projects, planning architecture, choosing tech stacks, or creating project plans. Provides structured guidance through concept → architecture → tech decisions → timeline phases.
allowed-tools: Read, Grep

Pre-Project Planning Assistant Skill

Purpose: Guide users through structured pre-project planning to reduce rework, make informed architectural decisions, and set up projects for success from day one.

For: Developers planning new projects who need systematic guidance before writing code.

When This Skill Auto-Activates

This skill automatically activates when you ask:
- "Help me plan a new project"
- "What should I consider before starting [project type]?"
- "Create a project plan for [idea]"
- "I'm starting a new [app/website/API/service]"
- "How do I plan a [type] project?"
- "What tech stack should I use for [requirements]?"
- "Help me architect [project description]"
- "Where do I begin with [project idea]?"

What This Skill Does

1. Structured Planning Guidance

Guides you through 4 planning phases systematically:

Phase 1: Concept Clarification
- What problem are you solving?
- Who are the target users?
- What are the core features vs nice-to-haves?
- What's the success criteria?

Phase 2: Architecture Design
- What's the high-level architecture? (monolith, microservices, serverless, etc.)
- What are the major components?
- How do components interact?
- What are the data flows?

Phase 3: Tech Stack Selection
- What constraints exist? (team skills, budget, timeline, hosting)
- What technologies fit the requirements?
- Why choose these over alternatives?
- What are the trade-offs?

Phase 4: Timeline & Milestones
- What's the MVP (minimum viable product)?
- What are the development phases?
- What are realistic timelines?
- What are the dependencies?

2. References Planning Documentation

Points you to the comprehensive planning guide:
- 03_pre-project-planning/01_must-have/01_planning-guide.md (detailed methodology)
- templates/project-plan-template.md (structured template)

3. Coordinates with project-planner Agent

For complex decisions requiring deep multi-perspective analysis:
- Suggests when to use @project-planner agent
- Explains how agent provides 6-perspective coordinated analysis
- Helps you get maximum value from agent invocation

Pattern:

Skill (quick guidance) → Agent (deep analysis)

Simple projects: Skill handles everything
Complex projects: Skill guides → Agent analyzes → Skill synthesizes

4. Prevents Common Mistakes

Proactively warns about anti-patterns:
- Premature optimization - Don't architect for scale you don't need
- Tech stack overload - Don't use 10 technologies when 3 will do
- Unclear requirements - Don't start coding without user stories
- No MVP defined - Don't build everything at once
- Ignoring constraints - Don't ignore team skills, budget, timeline

Example Interactions

Example 1: Simple Web App

User Query:

"Help me plan a task management web app"

Confidence: 🟢 High (0.90)
- Clear project type (web app, task management)
- Standard architectural patterns exist
- Well-understood problem domain

Skill Response:

I'll guide you through planning your task management web app.

Phase 1: Concept Clarification
Let me ask a few questions to understand your vision:

1. Who are your target users?
   - Personal use, teams, enterprises?
   - Technical background of users?

2. What are the 3 core features users must have?
   - Task creation/editing?
   - Collaboration features?
   - Notifications/reminders?

3. What's your success criteria?
   - Number of users?
   - User retention?
   - Revenue goals?

Once you answer these, I'll help with architecture and tech stack decisions.

Resources:
- Detailed planning guide: 03_pre-project-planning/01_must-have/01_planning-guide.md
- Project plan template: templates/project-plan-template.md

Why This Matters:
- Clarifying questions prevent building wrong product (most common failure mode)
- Target user identification drives all tech decisions (personal → simple, enterprise → complex)
- Core features vs nice-to-haves prevent scope creep and endless development
- Quick win: Answer 3 questions now, get concrete architecture recommendations in < 5 min

Next Step: After answering, I'll suggest tech stack based on your constraints

Example 2: Complex System Requiring Agent

User Query:

"I'm building a real-time multiplayer game with chat, matchmaking, and leaderboards"

Confidence: 🟡 Medium (0.65)
- High complexity project (multiple subsystems)
- Architectural decisions require trade-off analysis
- Agent invocation recommended for depth

Skill Response:

This is a complex project with several architectural decisions. I recommend
using the @project-planner agent for deep multi-perspective analysis.

Why use the agent for this project?
- Multiple technologies needed (WebSockets, game servers, databases)
- Performance critical (real-time requirements)
- Complex state synchronization
- Multiple architectural approaches possible

I can help you prepare questions for the agent:

1. What's your experience level with real-time systems?
2. What's your budget for hosting?
3. How many concurrent users do you expect?
4. What platforms? (web, mobile, desktop)

With this context, the @project-planner agent can provide:
- 🧠 Psychological: User engagement patterns for game retention
- 📚 Educator: Learning path for technologies you'll need
- 💻 Engineering: Architecture recommendations (peer-to-peer vs server-authoritative)
- 🎨 UX Designer: Matchmaking flow and chat UX patterns
- 🔒 Security: Cheat prevention and data validation strategies
- 💰 Business: Cost analysis for different hosting approaches

Should I prepare a detailed prompt for the @project-planner agent?

Why This Matters:
- Complex projects = high failure risk without proper planning (60-70% fail)
- Agent provides 6-perspective analysis → Catches blind spots you'd miss alone
- Preparing context questions maximizes agent value (focused analysis vs generic advice)
- Quick win: Answer 4 prep questions, then agent delivers comprehensive plan

Next Step: After agent analysis, I'll help synthesize recommendations into actionable plan

Example 3: Tech Stack Decision

User Query:

"What tech stack should I use for a REST API with authentication?"

Confidence: 🟢 High (0.82)
- Focused tech decision (REST API + auth)
- 3 common patterns with clear trade-offs
- Constraint-based recommendation possible

Skill Response:

Let me help you choose a tech stack by understanding your constraints:

Questions to narrow down options:
1. What's your current expertise? (Python, Node.js, Go, etc.)
2. What's your deployment target? (AWS, Vercel, self-hosted)
3. How many requests per second do you expect?
4. Do you have database preferences?

Common patterns for REST API + Auth:

Option 1: Node.js + Express + JWT + PostgreSQL
- ✅ Large ecosystem, good for teams familiar with JavaScript
- ✅ Fast development with npm packages
- ❌ Not ideal for CPU-intensive tasks
- Best for: Quick MVP, JavaScript teams

Option 2: Python + FastAPI + JWT + PostgreSQL
- ✅ Excellent for data-heavy APIs
- ✅ Strong typing with Pydantic
- ❌ Slower than Go for high concurrency
- Best for: Data processing, ML integration

Option 3: Go + Gin + JWT + PostgreSQL
- ✅ Excellent performance and concurrency
- ✅ Simple deployment (single binary)
- ❌ Smaller ecosystem than Node/Python
- Best for: High-performance, microservices

Based on your answers, I can recommend the best fit.

Deep dive: See 03_pre-project-planning/01_must-have/01_planning-guide.md

Why This Matters:
- Wrong tech stack = months of pain (migration is expensive)
- Constraint-based selection prevents "shiny technology syndrome"
- Trade-off transparency helps make informed choices (not hype-driven)
- Quick win: Answer 4 questions, get tailored recommendation in < 2 min

Next Step: After choosing stack, ask "What's the MVP for this API?"

Integration with Planning Documentation

This skill complements (doesn't replace) comprehensive documentation:

Use the Skill when:
- Quick planning guidance needed
- Interactive Q&A style helpful
- Want to validate approach quickly
- Starting from scratch (no clear direction)

Read planning-guide.md when:
- Need comprehensive methodology
- Want to understand WHY behind recommendations
- Building complex systems
- Planning for team/enterprise projects

Use project-plan-template.md when:
- Ready to document your plan
- Need structured format for stakeholders
- Creating project specification document

Use @project-planner agent when:
- Complex architectural decisions
- Multiple valid approaches exist
- Need multi-perspective analysis
- High-stakes project (significant time/budget)

Token Efficiency

Without Skill (Manual Exploration):
1. User asks: "How do I plan a new project?" (20 tokens)
2. Claude explores planning docs: Read files, search patterns (400 tokens)
3. Claude synthesizes guidance (300 tokens)
4. Follow-up questions repeat exploration (200 tokens each)
Total: ~1,100 tokens per planning session

With Skill (Structured Knowledge):
1. Skill auto-activates on question (50 tokens)
2. Provides structured guidance from expertise (250 tokens)
3. Follow-ups use skill context (100 tokens each)
Total: ~400 tokens per planning session

Savings: 700 tokens per project (64% reduction) ⚠️ projected

Frequency:
- New projects: Varies by user (1-10 per year)
- 5 projects/year: 3,500 tokens saved/year
- Teams planning together: Higher impact

Common Planning Workflows

Workflow 1: Solo Developer, Simple Project

You: "Plan a blog website"
Skill: Asks 3-4 clarifying questions
You: Answers questions
Skill: Recommends simple stack (Next.js + MDX or WordPress)
You: "How do I structure this?"
Skill: Points to project-plan-template.md
You: Fills out template, starts coding

Time: 15-20 minutes
Outcome: Clear plan, appropriate tech choices

Workflow 2: Team Project, Medium Complexity

You: "Plan a SaaS application for team collaboration"
Skill: Asks about users, features, constraints
You: Provides context
Skill: "This needs deeper analysis - use @project-planner"
You: "@project-planner [detailed prompt from skill]"
Agent: Provides 6-perspective analysis (1,500+ tokens)
You: Reviews recommendations with team
Skill: "Need help documenting plan?"
You: "Yes"
Skill: Guides through project-plan-template.md

Time: 1-2 hours (with team discussion)
Outcome: Comprehensive plan, stakeholder buy-in

Workflow 3: Validating Existing Idea

You: "I'm thinking MERN stack for e-commerce site with 10k users"
Skill: "Let me validate this against your requirements"
Skill: Asks about payment processing, inventory, performance needs
You: Provides details
Skill: "MERN works, but consider these trade-offs:
       - MongoDB: Good for product catalogs, but payment data needs ACID
       - Recommend: PostgreSQL for transactions, MongoDB for products
       - Add Redis for cart sessions (performance)
       See why: 03_pre-project-planning/01_must-have/01_planning-guide.md#tech-stack"
You: Adjusts plan based on feedback

Time: 10-15 minutes
Outcome: Validated plan, avoided pitfalls

Best Practices

DO Use This Skill For:

• ✅ Starting new projects from scratch
• ✅ Validating tech stack choices
• ✅ Quick architecture sanity checks
• ✅ Understanding planning methodology
• ✅ Learning what questions to ask

DON'T Use This Skill For:

• ❌ Detailed implementation planning (use project-planner agent)
• ❌ Code generation (that's later, after planning)
• ❌ Debugging existing projects (use other skills)
• ❌ Marketing/business strategy (outside scope)

When to Escalate to @project-planner Agent

Use the agent when ANY of these apply:

Complexity Indicators:
- 3+ major components with interactions
- Multiple technology choices with trade-offs
- Performance/scale requirements unclear
- Team has mixed skill levels
- Budget/timeline constraints tight

Decision Quality Needs:
- High stakes (significant time/money investment)
- Multiple stakeholders need alignment
- Architectural patterns unclear
- Need justification for technology choices
- Want to explore alternatives systematically

Learning Goals:
- Want deep understanding of trade-offs
- Building in unfamiliar domain
- Teaching opportunity for team
- Creating documentation for stakeholders

Skill will suggest agent proactively when appropriate.

Integration with Other Skills

Coordinates with:

global-setup-assistant - After planning, guides machine setup

Plan project → Choose tech stack → Setup environment

project-onboarding-assistant - After planning, guides project setup

Plan project → Create CLAUDE.md → Configure .claude/

workflow-analyzer - After 10+ projects, suggests planning improvements

"I notice you always choose X stack - consider Y for Z use case"

Natural progression:

pre-project-planning-assistant (plan) →
global-setup-assistant (machine setup) →
project-onboarding-assistant (project setup) →
[build project] →
workflow-analyzer (improve process)

Helpful Resources

Within Template:
- 03_pre-project-planning/01_must-have/01_planning-guide.md - Comprehensive methodology
- templates/project-plan-template.md - Structured documentation template
- .claude/agents/project-planner.md - Deep multi-perspective analysis
- docs/01-fundamentals/05_anti-patterns.md - Common planning mistakes

External:
- Architecture decision records (ADRs) - Document key decisions
- C4 model diagrams - Visualize architecture
- User story mapping - Define features from user perspective

FAQ

Q: Should I always fill out the project-plan-template.md?

A: For solo projects, you can skip it if the plan is clear in your head. For team projects or future reference, documenting is valuable. The template takes 20-30 minutes but saves hours of alignment later.

Q: How detailed should my plan be before coding?

A: Enough to answer: (1) What problem am I solving? (2) Who's the user? (3) What's the MVP? (4) What tech am I using and why? Don't over-plan - you'll learn more by building.

Q: What if my project changes after I start?

A: Normal! Plans are guides, not contracts. Update your project plan when direction shifts significantly. The planning process teaches you what questions to ask, even if answers change.

Q: Should I use the @project-planner agent for every project?

A: No. Simple projects (CRUD apps, static sites, scripts) don't need deep analysis. Use the agent when complexity is high, stakes are significant, or you're uncertain about approach.

Q: Can this skill help me learn new technologies?

A: Yes! When choosing tech, I can suggest learning paths and resources. But for systematic learning guidance, the planning-guide.md has detailed methodology.

Version History

• v3.4.0 (2025-12-14): Initial release - Complete setup assistance coverage
• Guides through 4 planning phases
• Coordinates with @project-planner agent
• Prevents common anti-patterns
• Token savings: 64% per project (projected)

Remember: Good planning prevents rework. Spend 30 minutes planning to save 30 hours debugging poorly chosen architecture.