Architecting Solutions
Analyzes requirements and creates detailed PRD documents for software implementation.
Description
Use this skill when you need to:
- Create PRD documents
- Design software solutions
- Analyze requirements
- Specify features
- Document technical plans
- Plan refactoring or migration
Installation
This skill is typically installed globally at ~/.claude/skills/architecting-solutions/.
How It Works
The skill guides Claude through a structured workflow:
- Clarify requirements - Ask targeted questions to understand the problem
- Analyze context - Review existing codebase for patterns and constraints
- Design solution - Propose architecture with trade-offs considered
- Generate PRD - Output markdown PRD to
{PROJECT_ROOT}/docs/ directory
IMPORTANT: Always write PRD to the project's docs/ folder, never to plan files or hidden locations.
Workflow
Copy this checklist and track progress:
Requirements Analysis:
- [ ] Step 1: Clarify user intent and success criteria
- [ ] Step 2: Identify constraints (tech stack, timeline, resources)
- [ ] Step 3: Analyze existing codebase patterns
- [ ] Step 4: Research best practices (if needed)
- [ ] Step 5: Design solution architecture
- [ ] Step 6: Generate PRD document (must be in {PROJECT_ROOT}/docs/)
- [ ] Step 7: Validate with user
Step 1: Clarify Requirements
Ask these questions to understand the problem:
Core Understanding
- Problem Statement: What problem are we solving? What is the current pain point?
- Success Criteria: How do we know this is successful? Be specific.
- Target Users: Who will use this feature? What are their goals?
For Refactoring/Migration:
- Why Refactor?: What's wrong with current implementation? Be specific.
- Breaking Changes: What will break? What needs migration?
- Rollback Plan: How do we revert if something goes wrong?
Step 2: Identify Constraints
- Technical Constraints: Existing tech stack, architecture patterns, dependencies
- Time Constraints: Any deadlines or phases?
- Resource Constraints: Team size, expertise availability
- Business Constraints: Budget, external dependencies, third-party APIs
Step 3: Analyze Existing Codebase
grep -r "related_keyword" packages/ --include="*.ts" --include="*.tsx"
find packages/ -type d -name "*keyword*"
ls -la packages/kit/src/views/similar-feature/
Critical for Refactoring:
- Find ALL consumers of the code being changed
- Identify ALL state/data flows
- Trace ALL entry points and exit points
- Look for existing mechanisms that might solve the problem already
grep -r "useFeatureContext" packages/ --include="*.ts" --include="*.tsx"
grep -r "refreshSignalRef" packages/ --include="*.ts" --include="*.tsx"
CRITICAL: Before proposing a refactoring, ask:
- Is there an existing mechanism that can be extended?
- What's the simplest possible solution?
- Can we solve this with minimal changes?
- Does my solution actually connect the dots? (e.g., empty callbacks won't work)
Look for:
- Architectural patterns: How are similar features implemented?
- State management: What state solution is used? (Jotai, Redux, Context, Refs)
- Component patterns: How are components organized?
- API patterns: How are API calls structured?
- Type definitions: Where are types defined?
Step 4: Research Best Practices
For unfamiliar domains, search for best practices.
Step 5: Design Solution Architecture
CRITICAL: Consider Multiple Solutions
Before settling on a solution, ALWAYS present multiple options:
- Minimal Change Solution - What's the absolute smallest change that could work?
- Medium Effort Solution - Balanced approach with some refactoring
- Comprehensive Solution - Full architectural overhaul
Example:
Problem: Data doesn't refresh after operation
Option 1 (Minimal): Hook into existing pending request count decrease
- Changes: 1-2 files
- Risk: Low
- Selected: ✓
Option 2 (Medium): Add refresh callback through existing shared context
- Changes: 3-5 files
- Risk: Medium
Option 3 (Comprehensive): Migrate to a centralized state-store pattern
- Changes: 10+ files, new atoms/actions
- Risk: High
- Time: 2-3 days
Ask user BEFORE writing PRD:
- Which option do you prefer?
- Are you open to larger refactoring?
- What's your tolerance for change?
Architecture Design Principles
- Simplicity First: Choose the simplest solution that meets requirements
- Progressive Enhancement: Start with MVP, extend iteratively
- Separation of Concerns: UI, logic, and data should be separated
- Reusability: Design components that can be reused
- Testability: Design for easy testing
Document Trade-offs
For each major decision, document:
| Option |
Pros |
Cons |
Selected |
| Approach A |
Pro1, Pro2 |
Con1 |
✓ |
| Approach B |
Pro1 |
Con1, Con2 |
|
Step 6: Generate PRD Document
IMPORTANT: Always write PRD to the project's docs/ directory, never to plan files or hidden locations.
Output location: {PROJECT_ROOT}/docs/{feature-name}-prd.md
Example:
- If project root is
/Users/user/my-project/, write to /Users/user/my-project/docs/feature-name-prd.md
- Use kebab-case for filename:
data-refresh-logic-refactoring-prd.md
Step 7: Validate with User
Before finalizing:
- Review success criteria - Do they align with user goals?
- Check constraints - Are all constraints addressed?
- Verify completeness - Can another agent implement from this PRD?
- Confirm with user - Get explicit approval before finalizing
PRD Quality Checklist
Content Quality
Implementation Readiness
Agent-Friendliness
Root Cause Analysis Checklist (CRITICAL)
For bugs and refresh issues, ALWAYS verify:
Common Root Cause Mistakes:
- Assuming hooks share state (they don't - each instance is independent)
- Empty callback implementations that do nothing
- Not tracing the full call chain from trigger to effect
- Not understanding when events fire (e.g.,
revalidateOnFocus requires actual focus change)
Migration Scope Completeness
State/Data Flow Validation
React/Hook Rules Compliance
Provider Pattern Completeness
Auto-mount/System Integration
Backward Compatibility
Code Examples
Common Anti-Patterns to Avoid
| Anti-Pattern |
Better Approach |
| "Optimize the code" |
"Reduce render time from 100ms to 16ms by memoizing expensive calculations" |
| "Make it faster" |
"Implement caching to reduce API calls from 5 to 1 per session" |
| "Clean up the code" |
"Extract duplicate logic into shared utility functions" |
| "Fix the bug" |
"Handle null case in getUserById when user doesn't exist" |
| "Refactor the state layer" |
"Migrate from Context+Ref to a centralized store: " |
| Over-engineering |
Start with simplest solution, extend only if needed |
Over-Engineering Warning (Critical Lesson)
The Problem with Jumping to Complex Solutions
Real Case Study:
- PRD Proposed: Full shared state-store migration (10+ files, 2-3 days)
- Actual Solution: Hook into existing pending request count decrease (1-2 files, 1 hour)
- Lesson: Always look for the simplest solution first
Signs You Might Be Over-Engineering
- ❌ Proposing new patterns when existing ones could work
- ❌ Creating new state management before exhausting current options
- ❌ Multiple new files when one file change could suffice
- ❌ "Best practice" justification without considering practicality
Questions to Ask Before Writing PRD
- Is there an existing mechanism that does 80% of what we need?
- Can we extend/modify existing code instead of creating new patterns?
- What's the absolute minimum change to solve THIS problem?
- Does the user actually want a major refactor?
- Does my solution's callback actually do something? (Empty callbacks are bugs!)
- Have I traced the complete call chain? (Trigger → ... → Effect)
When Comprehensive Solutions ARE Appropriate
- Current architecture is fundamentally broken
- Technical debt is blocking all new features
- Team has explicitly decided to modernize
- Problem will recur if not properly addressed
Key: Comprehensive solutions should be a CHOICE, not the DEFAULT.
Patterns for Common Scenarios
New Feature Implementation
1. Read similar feature implementations
2. Identify reusable patterns
3. Design component hierarchy
4. Define state management approach
5. Specify API integration points
6. List all new files to create
7. List all existing files to modify
Refactoring Existing Code
1. Analyze current implementation
2. Find ALL consumers (grep -r imports)
3. Identify pain points and technical debt
4. PROPOSE MULTIPLE SOLUTIONS (minimal → comprehensive)
5. GET USER APPROVAL on approach
6. Plan migration strategy (phased vs big-bang)
7. Define rollback approach
8. List migration checklist
# CRITICAL: Start with the simplest solution!
# Only propose comprehensive refactoring if user explicitly wants it.
Bug Fix Investigation
1. Understand expected vs actual behavior
2. Locate root cause in code
3. Identify affected areas
4. Design fix approach
5. Specify testing for regression prevention
Reference Materials
- PRD Template: Look at existing PRDs in the project's
docs/ folder
- Similar Implementations: Reference similar features/modules in the codebase
Tips for Effective PRDs
- Be Specific: "Improve performance" → "Reduce API response time from 2s to 500ms"
- Show Context: Explain why a decision was made, not just what was decided
- Include Examples: Show code snippets for complex patterns
- Think About Edge Cases: What happens when API fails? User has no data?
- Consider Migration: For refactoring, how do we move from A to B safely?
