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:

1. Clarify requirements - Ask targeted questions to understand the problem
2. Analyze context - Review existing codebase for patterns and constraints
3. Design solution - Propose architecture with trade-offs considered
4. 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

# Find similar patterns in the codebase
grep -r "related_keyword" packages/ --include="*.ts" --include="*.tsx"

# Find relevant directory structures
find packages/ -type d -name "*keyword*"

# Check existing patterns
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

# Find all imports/usages of a module
grep -r "useBorrowContext" packages/ --include="*.ts" --include="*.tsx"
grep -r "borrowRefreshReservesRef" packages/ --include="*.ts" --include="*.tsx"

CRITICAL: Before proposing a refactoring, ask:

1. Is there an existing mechanism that can be extended?
2. What's the simplest possible solution?
3. Can we solve this with minimal changes?
4. 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:

1. Minimal Change Solution - What's the absolute smallest change that could work?
2. Medium Effort Solution - Balanced approach with some refactoring
3. Comprehensive Solution - Full architectural overhaul

Example:

Problem: Data doesn't refresh after operation

Option 1 (Minimal): Hook into existing pendingTx count decrease
  - Changes: 1-2 files
  - Risk: Low
  - Selected: ✓

Option 2 (Medium): Add refresh callback through existing context
  - Changes: 3-5 files
  - Risk: Medium

Option 3 (Comprehensive): Migrate to Jotai Context 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

1. Simplicity First: Choose the simplest solution that meets requirements
2. Progressive Enhancement: Start with MVP, extend iteratively
3. Separation of Concerns: UI, logic, and data should be separated
4. Reusability: Design components that can be reused
5. Testability: Design for easy testing

Document Trade-offs

For e

...