Architecting Solutions

Architecting Solutions

Analyzes requirements and creates technical solution documents for software implementation.

Description

Use this skill when you need to:

• Create non-PRD solution briefs or technical design documents
• Design software solutions
• Analyze requirements
• Specify features
• Document technical plans
• Plan refactoring or migration

Installation

Install through apb skills add ./skills/architecting-solutions --scope global --target all --link when possible.

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 solution doc - Output a markdown solution brief or technical design to {PROJECT_ROOT}/docs/

IMPORTANT: Use prd-planner when the user asks for a PRD. This skill writes non-PRD architecture and solution artifacts to the project's docs/ folder.

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 solution 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" src/ --include="*.ts" --include="*.tsx"

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

# Check existing patterns
find src -maxdepth 4 -type d -name '*similar*'

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 "existing-interface" src/ --include="*.ts" --include="*.tsx"
grep -r "related-event" src/ --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 solution and ownership boundaries does this repository already use?
• 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 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 the solution document:

• 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 each major decision, document:

Step 6: Generate Solution Document

IMPORTANT: Always write the solution document to the project's docs/ directory, never to plan files or hidden locations. Use prd-planner instead when the requested artifact is a PRD.

Output location: {PROJECT_ROOT}/docs/{feature-name}-solution.md

Example:

• If project root is /Users/user/my-project/, write to /Users/user/my-project/docs/feature-name-solution.md
• Use kebab-case for filename: data-refresh-logic-refactoring-solution.md

Step 7: Validate with User

Before finalizing:

1. Review success criteria - Do they align with user goals?
2. Check constraints - Are all constraints addressed?
3. Verify completeness - Can another agent implement from this solution document?
4. Confirm with user - Get explicit approval before finalizing

Solution Quality Checklist

Content Quality

• [ ] Problem statement is clear and specific
• [ ] Success criteria are measurable
• [ ] Functional requirements are unambiguous
• [ ] Non-functional requirements are specified
• [ ] Constraints are documented
• [ ] Trade-offs are explained

Implementation Readiness

• [ ] Architecture is clearly defined
• [ ] File structure is specified
• [ ] API contracts are defined (if applicable)
• [ ] Data models are specified
• [ ] Edge cases are considered
• [ ] Testing approach is outlined

Agent-Friendliness

• [ ] Another agent can implement without clarification
• [ ] Code examples are provided where helpful
• [ ] File paths use forward slashes
• [ ] Existing code references are accurate

Root Cause Analysis Checklist (CRITICAL)

For bugs, state, refresh, or lifecycle issues, verify:

• [ ] Existing mechanism - Does a working solution already exist elsewhere?
• [ ] Causal gap - Why does the existing solution not apply here: timing, scope, ownership, or missing wiring?
• [ ] State ownership - Which instance or service owns each state transition?
• [ ] Complete event chain - Trace trigger → handler → state change → observable effect.
• [ ] Implemented boundaries - Confirm each callback, adapter, queue, or registration point performs real work.
• [ ] Timing semantics - Identify intervals, retries, focus/lifecycle events, and cancellation behavior.

Common mistakes include assuming separate instances share state, leaving inert callbacks, checking only the first link in a chain, and confusing an event's registration with proof that it fired.

Migration Scope Completeness

• [ ] ALL existing state is accounted for: List every piece of state being migrated