Project Planning Skill

Generate four essential planning documents to guide AI-assisted development. These documents maintain context coherence across coding sessions and prevent architectural drift.

When to Use This Skill

• User describes a project concept and asks for planning documents
• Files in

  docs/planning/

  show "Awaiting Generation" status
• User invokes

  /plan

  command with project description
• Starting development on a new feature requiring architectural decisions

Output Documents

docs/planning/project-vision.md

docs/planning/tech-spec.md

docs/planning/roadmap.md

docs/planning/adr/adr-001-*.md

Generation Process

Step 1: Gather Project Context

Before generating, collect:

1. Project description from user input
2. Technical constraints from

   pyproject.toml

   and existing code
3. Cookiecutter choices reflected in project structure

Step 2: Generate Documents in Order

Generate documents sequentially, as later documents reference earlier ones:

1. Project Vision & Scope - Establishes what we're building and why
2. Architecture Decision Record - Key technical choices based on PVS
3. Technical Implementation Spec - Detailed how-to based on ADRs
4. Development Roadmap - Implementation plan based on all above

Step 3: Expert Review via Consensus

After generating each document, use the zen-mcp-server consensus tool to get expert review:

Use mcp__zen__consensus with gemini-3-pro-preview to review:

"Review this [document type] for sufficiency to begin development.

Evaluate:
1. SPECIFICITY: Are requirements concrete enough to implement?
2. COMPLETENESS: Are all critical sections filled with project-specific content?
3. FEASIBILITY: Are timelines and technical choices realistic?
4. CLARITY: Can a developer understand what to build from this?
5. GAPS: What critical information is missing?

Respond with:
- READY: Document is sufficient to begin work
- NEEDS REVISION: [List specific improvements required]

Document content:
[paste document content]"

Review each document in order:

1. PVS → Must be READY before generating ADR
2. ADR → Must be READY before generating Tech Spec
3. Tech Spec → Must be READY before generating Roadmap
4. Roadmap → Must be READY before completing

If any document NEEDS REVISION, incorporate feedback and re-review before proceeding.

Step 4: Validate and Cross-Reference

After all documents pass review:

• Ensure documents reference each other correctly
• Verify technical choices are consistent across documents
• Flag any assumptions needing user validation
• Run validation script if available

Document Generation Guidelines

All Documents

• Be specific: Use concrete technologies, versions, and measurable criteria
• No boilerplate: Every section must contain project-specific information
• Under 1000 words: Dense information, minimal prose
• Markdown format: Use headers, bullets, tables for structure
• Include TL;DR: 2-3 sentence summary at top of each document

Project Vision & Scope (PVS)

Use template:

templates/pvs-template.md

Focus on:

• Problem being solved and user impact
• Core capabilities (3-5 max for MVP)
• Explicit scope boundaries (in vs out)
• Measurable success metrics

Architecture Decision Record (ADR)

Use template:

templates/adr-template.md

Create ADR for:

• Database/storage choice
• Authentication strategy
• API design approach
• Key framework decisions
• Any choice expensive to reverse

Format:

adr-001-{decision-slug}.md

Technical Implementation Spec

Use template:

templates/tech-spec-template.md

Include:

• Complete tech stack with versions
• Component architecture diagram (ASCII)
• Data model with schemas
• API endpoints specification
• Security requirements
• Error handling approach

Development Roadmap

Use template:

templates/roadmap-template.md

Structure as:

• Phase 0: Foundation (environment, CI/CD)
• Phase 1: MVP Core (essential features)
• Phase 2: Enhancement (additional features)
• Phase 3: Polish (testing, documentation)

Each phase needs:

• Clear deliverables
• Success criteria (testable)
• Estimated duration
• Dependencies

Pre-Filling from Project Context

When generating, incorporate known information:

# From pyproject.toml / cookiecutter context
python_version = "3.12"
project_name = "Fragrance Rater"
project_slug = "fragrance_rater"
cli_framework = "Click"
containerization = "Docker"

Quality Checklist

Before completing generation:

• All four documents created in

  docs/planning/

• Each document has TL;DR section
• No "[TODO]" or "[TBD]" placeholders remain
• Documents cross-reference each other
• Technical choices are consistent
• Success criteria are measurable
• Scope boundaries are explicit
• At least one ADR created

Templates Reference

Templates are in

templates/

• pvs-template.md

  - Project Vision & Scope structure

• adr-template.md

  - Architecture Decision Record structure

• tech-spec-template.md

  - Technical Spec structure

• roadmap-template.md

  - Development Roadmap structure

Detailed Guidance

For comprehensive documentation on each document type, see

reference/

• reference/document-guide.md

  - Full guidance for all document types

• reference/prompting-patterns.md

  - How to use documents during development

After Generation

Instruct user to:

1. Review each document for accuracy
2. Validate assumptions marked with

   [ ]

3. Adjust timelines in roadmap if needed
4. Commit documents to version control
5. Reference documents in future development sessions

Example Usage

When user says: "I want to build a CLI tool for managing personal finances..."

Generation Flow with Consensus Review

1. Generate PVS

   • Read

     templates/pvs-template.md

   • Generate

     docs/planning/project-vision.md

     with finance CLI specifics
   • Review:

     mcp__zen__consensus

     with gemini-3-pro-preview → READY or revise

2. Generate ADR

   • Read

     templates/adr-template.md

   • Generate

     docs/planning/adr/adr-001-database-choice.md

     for SQLite decision
   • Review:

     mcp__zen__consensus

     with gemini-3-pro-preview → READY or revise

3. Generate Tech Spec

   • Read

     templates/tech-spec-template.md

   • Generate

     docs/planning/tech-spec.md

     with Python/Click/SQLite stack
   • Review:

     mcp__zen__consensus

     with gemini-3-pro-preview → READY or revise

4. Generate Roadmap

   • Read

     templates/roadmap-template.md

   • Generate

     docs/planning/roadmap.md

     with phased implementation
   • Review:

     mcp__zen__consensus

     with gemini-3-pro-preview → READY or revise

5. Final Validation

   • Run

     scripts/validate-planning-docs.py

   • Summarize what was created and review outcomes
   • List next steps for beginning development

Consensus Review Prompt Template

mcp__zen__consensus with gemini-3-pro-preview:

Review this Project Vision & Scope document for Fragrance Rater.

EVALUATION CRITERIA:
1. SPECIFICITY - Can a developer implement from these requirements?
2. COMPLETENESS - All sections filled with project-specific content?
3. FEASIBILITY - Realistic scope for the described constraints?
4. CLARITY - Unambiguous success criteria and scope boundaries?
5. GAPS - Any critical missing information?

RESPOND:
- READY: Sufficient to proceed to next document
- NEEDS REVISION: [Specific improvements with examples]

DOCUMENT:
[Full document content here]

MCP Server Requirement

This skill requires the zen-mcp-server for consensus review. If not available, skip Step 3 and proceed with manual review.

Configuration: Ensure

mcp__zen__consensus