Architectural Planning

Architectural Planning Methodology

This skill enables creating comprehensive technical plans for features and changes by discovering and following project architectural patterns.

Leverages: [codebase-analysis] skill for project discovery and pattern recognition.

Planning Philosophy

Integration Over Innovation

• Design solutions that fit naturally into existing architecture
• Respect established boundaries and responsibilities
• Follow discovered organizational patterns
• Use existing libraries and approaches

Clarity and Actionability

• Create plans others can execute without clarification
• Break work into atomic, testable steps
• Identify dependencies and risks explicitly
• Provide clear success criteria

Planning Workflow

Phase 1: Architectural Discovery

Using [codebase-analysis] methodology:

1. Understand overall architecture (layered, microservices, modular, etc.)
2. Identify existing components and their responsibilities
3. Map dependencies and integration points
4. Learn architectural boundaries and conventions
5. Find similar features as reference examples

Phase 1.5: Deep Reasoning (If Complex)

After architectural discovery, evaluate if systematic thinking is needed for complex decisions.

Quick assessment:

• 3+ approaches AND 5+ dimensions AND unclear path → Sequential Thinking
• Otherwise → Direct analysis, proceed to Phase 2

After decision: Consider using Memory MCP to record architectural decisions and rationale for future reference.

Detailed guidance: See ../shared/mcp-decision-guide.md for:

• Sequential Thinking decision criteria and usage
• Memory MCP usage patterns
• Decision flow examples

Phase 2: Solution Design

Design within discovered constraints:

1. Identify which existing components are affected
2. Determine if new components are needed
3. Choose integration points that match existing patterns
4. Plan data flows following project conventions
5. Design APIs consistent with current style

Phase 3: Implementation Planning

Create actionable steps:

1. Order tasks by dependency and logical progression
2. Specify exact files to modify or create
3. Reference existing code as implementation examples
4. Identify potential conflicts or breaking changes
5. Plan validation and testing approach

Plan Structure Guidelines

Essential Elements

Context Section:

• Discovered architecture pattern
• Technology stack
• Similar existing features
• Integration points

Approach Section:

• High-level solution
• Why it fits the architecture
• New vs existing components
• Pattern references

Implementation Section:

• Atomic, ordered steps
• File paths (create/modify)
• Code examples from codebase
• Rationale for each step

Risk Section:

• Dependencies (internal/external)
• Potential issues and mitigations
• Breaking changes and migrations
• Performance impact

Validation Section:

• Testing strategy
• Success criteria
• Manual verification steps

Planning Best Practices

Reference Real Examples

✅ "Following the UserService pattern in services/user.service.ts,
   OrderService will inject repositories via constructor and
   use the same error handling approach."

❌ "Create OrderService using dependency injection."

Be Specific About Locations

✅ "Create auth/middleware/jwt-validator.ts following the
   pattern from auth/middleware/session-validator.ts"

❌ "Add JWT validation middleware"

Quantify When Possible

✅ "Affects 3 API endpoints and 2 background jobs.
   Estimated: 2-3 hours implementation + 1 hour testing."

❌ "This will take some time to implement."

Identify Patterns, Not Just Tasks

✅ "Implement using the Command pattern like existing
   payment/commands/ProcessPayment.java uses"

❌ "Implement the feature"

Common Architectural Patterns

Layered Architecture

Plan should respect layers:
- API/Presentation → UseCase/Application → Infrastructure → Domain
- Dependencies flow inward
- Each layer uses only the layer below

Microservices

Plan should consider:
- Service boundaries
- Inter-service communication patterns
- Data consistency approaches
- Shared libraries vs duplication

Hexagonal/Clean Architecture

Plan should:
- Keep business logic in core
- Adapt external dependencies at boundaries
- Use dependency inversion
- Preserve testability

Event-Driven

Plan should:
- Identify events to publish/consume
- Follow existing event schemas
- Use project's message infrastructure
- Consider eventual consistency

Anti-Patterns to Avoid

❌ Generic Plans:

• "Add authentication" without specifying how it integrates

✅ Context-Specific Plans:

• "Extend existing OAuth2 middleware in auth/oauth2.go to support refresh tokens, following the pattern from auth/session.go"

❌ Technology Mismatch:

• Recommending GraphQL when project uses REST

✅ Technology Alignment:

• "Add REST endpoint to api/v1/orders.ts following OpenAPI spec pattern from api/v1/users.ts"

❌ Ignoring Existing Solutions:

• Creating new pagination when project has existing implementation

✅ Leverage Existing:

• "Use existing utils/pagination.ts helper, same as services/user-service.ts uses"

Quality Checklist

Before finalizing plan:

• Have I identified the architectural pattern?
• Does the solution fit naturally into existing structure?
• Are all steps grounded in discovered conventions?
• Have I referenced specific existing code as examples?
• Are integration points clearly identified?
• Is each step atomic and testable?
• Have I considered risks and provided mitigations?
• Will someone unfamiliar with my thinking understand this plan?

Plan Templates

For detailed templates and architecture-specific examples, see:

• templates.md - Full plan template and common scenarios

Remember: A great plan reads like it was written by someone deeply familiar with the codebase. Use the [codebase-analysis] skill to become that familiar before planning.