app-planner

name	app-planner
description	Guides you through comprehensive iOS/Swift app planning and analysis. Use for new apps (concept to architecture) or existing apps (audit current state, plan improvements, evaluate tech stack). Covers product planning, technical decisions, UI/UX design, and distribution strategy. Use when this capability is needed.
metadata	{"author":"flight505"}

App Planner Skill

Comprehensive guide for planning iOS/Swift applications and analyzing existing apps, covering product, technical, UI/UX, and distribution considerations.

When This Skill Activates

Use this skill when the user:

For New Apps:

• Wants to plan a new iOS/Swift app from scratch
• Asks about app planning, architecture planning, or project setup
• Needs help defining features, requirements, or technical stack
• Wants to create a comprehensive app plan or design document
• Asks "what should I consider when building a new app?"

For Existing Apps:

• Wants to analyze or audit their current iOS app
• Asks to "run through my existing app"
• Needs architecture evaluation or recommendations
• Wants tech stack assessment
• Planning major refactoring or improvements
• Evaluating app health and identifying gaps

Planning Process

1. Understand Project Context

First, determine if this is a new app or existing app, then gather context:

App Status:

• New app (planning from scratch)
• Existing app (analyze/improve)

For NEW Apps - gather:

• Project Type: Personal, client, startup, learning
• Current Stage: Just an idea, have requirements, have designs, technical only
• Scope: Full planning, feature planning, architecture only, tech stack only

For EXISTING Apps - gather:

• Project Type: Personal, client, startup, enterprise
• App Age: How long in development/production
• Codebase Size: Small (<10 screens), medium (10-30), large (30+)
• Current Issues: Performance, maintainability, feature additions, technical debt
• Analysis Scope: Full audit, architecture review, tech stack evaluation, specific area
• Existing Tech Stack: SwiftUI/UIKit, architecture pattern, persistence layer
• Pain Points: What's not working well, what needs improvement

Then proceed to appropriate workflow:

• New App → Continue to "Planning Phases for New Apps" (Section 3)
• Existing App → Jump to "Analysis Process for Existing Apps" (Section 6)

2. Load Reference Materials

Before detailed planning, familiarize yourself with these references in .claude/skills/app-planner/:

• planning-checklist.md - Comprehensive planning checklist covering all phases
• architecture-guide.md - Architecture patterns, decisions, and trade-offs
• tech-stack-options.md - Technology choices for different requirements

3. Planning Phases for New Apps

Note: For existing apps, skip to Section 6 "Analysis Process for Existing Apps"

Guide the user through these planning phases based on their scope:

Phase 1: Product Planning

Goals:

• Define what the app does and who it's for
• Identify core features and prioritization
• Understand user needs and workflows

Activities:

1. Define App Purpose

   • What problem does it solve?
   • What's the core value proposition?
   • What makes it different?

2. Identify Target Users

   • Who will use this app?
   • What are their goals and pain points?
   • Create 1-2 user personas if helpful

3. Feature Definition

   • List all potential features
   • Categorize: MVP (must-have), v2 (nice-to-have), future
   • Prioritize based on value and complexity

4. User Journeys

   • Map key user workflows
   • Identify main user paths through the app
   • Note critical touchpoints

Phase 2: Technical Planning

Goals:

• Choose appropriate architecture and patterns
• Design data models
• Select technology stack
• Plan project structure

Activities:

1. Architecture Selection

   • Review architecture-guide.md for options (MVVM, TCA, etc.)
   • Consider project size, team experience, requirements
   • Ask user about preferences and constraints
   • Recommend architecture with rationale

2. Data Modeling

   • Identify main entities and relationships
   • Define data flow (where data comes from, where it goes)
   • Choose persistence layer:
     • Core Data (complex data, relationships, offline-first)
     • SwiftData (iOS 17+, modern alternative)
     • UserDefaults (simple settings only)
     • Realm (alternative to Core Data)
     • Custom backend + caching

3. Tech Stack Decisions

   • Review tech-stack-options.md for guidance
   • UI Framework: SwiftUI, UIKit, or hybrid
   • Minimum iOS version: Based on features needed
   • Networking: URLSession, Alamofire, or custom
   • Dependencies: SPM, CocoaPods, or manual
   • Third-party libraries: Based on requirements
   • Ask about user preferences and constraints

4. Project Structure

   • Folder organization (features, layers, modules)
   • Modularization strategy (monolith vs multi-module)
   • Code organization patterns

Phase 3: UI/UX Planning

Goals:

• Plan user interface and experience
• Ensure HIG compliance
• Design navigation and flows

Activities:

1. Design System

   • Color palette (consider dark mode)
   • Typography (SF Pro, custom fonts)
   • Spacing system (8pt grid recommended)
   • Component library planning

2. Navigation Pattern

   • Tab bar (2-5 main sections)
   • Sidebar (iPad, complex hierarchies)
   • Navigation stack (linear flows)
   • Sheet/modal presentations
   • Recommend based on app structure

3. Screen Planning

   • List all main screens
   • Create simple wireframes or descriptions
   • Define screen hierarchy
   • Plan empty states, loading states, error states

4. Accessibility First

   • Dynamic Type support
   • VoiceOver compatibility
   • Color contrast requirements
   • Accessibility features priority

5. Onboarding & UX Flows

   • First-time user experience
   • Key user flows
   • Error handling UX
   • Feedback mechanisms

Phase 4: Non-Functional Requirements

Goals:

• Define performance, security, testing requirements
• Plan for scalability and maintainability

Activities:

1. Performance Targets

   • Target device range (iPhone only, iPad support, Mac Catalyst)
   • Performance benchmarks
   • Memory constraints
   • Battery usage considerations

2. Security & Privacy

   • Authentication needs (if any)
   • Data encryption requirements
   • Privacy policy requirements
   • Secure storage for sensitive data
   • App Transport Security compliance

3. Testing Strategy

   • Unit testing approach and coverage goals
   • UI testing requirements
   • Beta testing plan
   • QA process

4. Monitoring & Analytics

   • Analytics needs (user behavior tracking)
   • Crash reporting (essential for production apps)
   • Performance monitoring
   • User feedback mechanism

Phase 5: Distribution & Business

Goals:

• Plan for App Store distribution
• Define monetization (if applicable)
• Set timeline and milestones

Activities:

1. App Store Planning

   • App name availability check
   • Bundle identifier decision
   • Screenshots/preview planning
   • App description and keywords

2. Monetization (if applicable)

   • Free, paid, freemium, subscription
   • In-app purchases planning
   • Ad integration strategy

3. Localization

   • Initial language(s)
   • Internationalization strategy
   • Future localization plans

4. Timeline & Milestones

   • MVP timeline estimate
   • Feature milestones
   • Release schedule
   • Version planning (1.0, 1.1, 2.0, etc.)

4. Create Planning Documentation Files

IMPORTANT: After completing planning phases, create actual documentation files that the user can keep, update, and version control.

Ask User About Documentation Location

Before creating files, ask where to put documentation:

• docs/planning/ (recommended for most projects)
• planning/ (root-level planning folder)
• .claude/planning/ (keep with Claude Code files)
• Custom location

Documentation Files to Create

For comprehensive planning, create these files:

1. docs/planning/overview.md - Executive summary and key decisions 2. docs/planning/features.md - Feature list, priorities, and roadmap 3. docs/planning/architecture.md - Architecture pattern and rationale 4. docs/planning/tech-stack.md - Technology choices and justification 5. docs/planning/ui-ux.md - Design system, navigation, screens 6. docs/planning/data-model.md - Data entities and relationships (if applicable) 7. docs/planning/personas.md - User personas (if created) 8. docs/planning/roadmap.md - Timeline and milestones

For focused planning (architecture only, tech stack only), create only relevant files.

Templates for Each Documentation File

File 1: overview.md

# [App Name] - Overview

**Last Updated**: [Date]

## Quick Summary

- **Purpose**: [One sentence - what problem does this solve?]
- **Target Users**: [Primary audience]
- **Platform**: iOS [version]+
- **Project Type**: [Personal/Client/Startup/Enterprise]
- **Status**: [Planning/In Development/Production]

## Vision

[2-3 sentences describing the app's vision and core value proposition]

## Key Decisions

### Architecture

- **Pattern**: [MVVM/TCA/MVC/etc.]
- **Rationale**: [Why this choice]

### Tech Stack

- **UI**: [SwiftUI/UIKit/Hybrid]
- **Min iOS**: [Version]
- **Persistence**: [Core Data/SwiftData/etc.]
- **Backend**: [CloudKit/Firebase/Custom/None]

### Timeline

- **MVP**: [Date/timeframe]
- **v1.0**: [Target launch]

## Key Risks & Mitigation

1. [Risk 1] - [Mitigation strategy]
2. [Risk 2] - [Mitigation strategy]

## Success Metrics

- [Metric 1]
- [Metric 2]
- [Metric 3]

## Related Documents

- [features.md](./features.md) - Feature list and roadmap
- [architecture.md](./architecture.md) - Architecture details
- [tech-stack.md](./tech-stack.md) - Technology choices
- [ui-ux.md](./ui-ux.md) - Design and UX

File 2: features.md

# [App Name] - Features

**Last Updated**: [Date]

## MVP Features (v1.0)

### Feature 1: [Name]

- **Priority**: High/Medium/Low
- **Complexity**: Low/Medium/High
- **Description**: [What it does]
- **User Value**: [Why users need this]
- **Dependencies**: [Other features needed first]
- **Status**: [ ] Not Started / [ ] In Progress / [x] Complete

### Feature 2: [Name]

[Same structure]

## Post-MVP Features (v1.1+)

### Feature 3: [Name]

- **Target Version**: v1.1 / v2.0
- **Priority**: High/Medium/Low
- **Description**: [What it does]
- **Why Later**: [Rationale for not including in MVP]

## Future Considerations

- [Feature idea 1]
- [Feature idea 2]

## Feature Dependencies

Feature A ├── Feature B (depends on A) └── Feature C (depends on A)

## Feature Estimates

| Feature | Complexity | Effort | Priority |
|---------|-----------|--------|----------|
| Feature 1 | Medium | 2 weeks | High |
| Feature 2 | Low | 3 days | High |
| Feature 3 | High | 4 weeks | Medium |

File 3: architecture.md

# [App Name] - Architecture

**Last Updated**: [Date]

## Architecture Pattern

**Chosen Pattern**: [MVVM/TCA/MVC/VIPER]

### Rationale

[Why this pattern was chosen for this specific app]

### Alternatives Considered

- **[Pattern 1]**: [Why not chosen]
- **[Pattern 2]**: [Why not chosen]

## Project Structure

AppName/ ├── App/ │ ├── AppName.swift │ └── Configuration/ ├── Features/ │ ├── FeatureA/ │ │ ├── Views/ │ │ ├── ViewModels/ │ │ └── Models/ │ └── FeatureB/ ├── Shared/ │ ├── Components/ │ ├── Extensions/ │ └── Utilities/ ├── Services/ │ ├── DataService/ │ └── NetworkService/ └── Resources/ ├── Assets.xcassets └── Localizable.strings

## Layer Responsibilities

### Presentation Layer (Views)
- SwiftUI views or UIKit view controllers
- UI presentation only
- Binds to ViewModels
- No business logic

### Business Logic Layer (ViewModels)
- Presentation logic
- State management
- Coordinates between View and Data layers
- Testable without UI

### Data Layer (Models & Services)
- Domain models
- Data access (repositories)
- API communication
- Persistence management

## Data Flow

User Action ↓ View ↓ ViewModel (handles action) ↓ Service/Repository ↓ Model (data) ↓ ViewModel (transforms for presentation) ↓ View (updates UI)

## Key Architectural Decisions

### 1. [Decision Name]
- **Decision**: [What was decided]
- **Context**: [Why it mattered]
- **Rationale**: [Why this choice]
- **Consequences**: [Trade-offs]

### 2. [Decision Name]
[Same structure]

## Testing Strategy

### Unit Tests
- ViewModels (business logic)
- Services and repositories
- Utilities and extensions
- **Coverage Goal**: 70%+

### UI Tests
- Critical user flows
- Key navigation paths

## Future Considerations

- [Potential architecture evolution]
- [Migration strategy if needed]

File 4: tech-stack.md

# [App Name] - Tech Stack

**Last Updated**: [Date]

## UI Framework

**Choice**: [SwiftUI/UIKit/Hybrid]

### Rationale

[Why this choice for this app]

### Version Support

- **Minimum iOS**: [e.g., iOS 17 for broad reach]
- **Target iOS**: [e.g., iOS 26]
- **Rationale**: [Why these versions]

## Persistence

**Choice**: [Core Data/SwiftData/Realm/UserDefaults/File System]

### Rationale

[Why this persistence layer]

### Data Sync

- **Strategy**: [CloudKit/Firebase/Custom/None]
- **Offline Support**: [Yes/No - approach]

## Networking

**Choice**: [URLSession/Alamofire/Moya/Custom]

### Rationale

[Why this networking approach]

### API Details

- **Type**: REST/GraphQL/None
- **Base URL**: [If applicable]
- **Authentication**: [Method if needed]

## Dependency Management

**Choice**: [Swift Package Manager/CocoaPods/Carthage]

### Rationale

[Why this dependency manager]

## Third-Party Dependencies

| Dependency | Purpose        | Version   | Justification |
| ---------- | -------------- | --------- | ------------- |
| [Name]     | [What it does] | [Version] | [Why needed]  |
| [Name]     | [What it does] | [Version] | [Why needed]  |

### Dependency Guidelines

- Minimize external dependencies
- Prefer native solutions when possible
- All dependencies must be actively maintained

## Development Tools

- **Linting**: SwiftLint
- **Formatting**: SwiftFormat (optional)
- **Analytics**: [Tool if needed]
- **Crash Reporting**: [Tool if needed]

## Backend Services

**Choice**: [CloudKit/Firebase/Supabase/Custom/None]

### Services Used

- [ ] Authentication
- [ ] Database/Storage
- [ ] Analytics
- [ ] Push Notifications
- [ ] Cloud Functions

### Rationale

[Why this backend choice]

## CI/CD

**Choice**: [Xcode Cloud/GitHub Actions/Bitrise/Other]

### Pipeline

- Automated builds
- Automated testing
- TestFlight deployment

## Alternative Considered

### [Alternative 1]

- **What**: [Alternative tech choice]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Why Not Chosen**: [Reason]

## Tech Stack Summary

UI: [SwiftUI] iOS: [15+] Architecture: [MVVM] Persistence: [Core Data] Backend: [CloudKit] Networking: [URLSession] Dependencies: [SPM] CI/CD: [Xcode Cloud]

## Migration Considerations

[If tech stack might change later, note migration paths]

File 5: ui-ux.md

# [App Name] - UI/UX Design

**Last Updated**: [Date]

## Design System

### Color Palette

**Light Mode:**

- Primary: `#XXXXXX` (Purpose)
- Secondary: `#XXXXXX` (Purpose)
- Background: System background
- Text: System label

**Dark Mode:**

- Primary: `#XXXXXX`
- Secondary: `#XXXXXX`
- Background: System background
- Text: System label

### Typography

**Font**: [SF Pro/Custom font]

**Text Styles:**

- Large Title: 34pt, Bold
- Title: 28pt, Regular
- Headline: 17pt, Semibold
- Body: 17pt, Regular
- Caption: 12pt, Regular

**Dynamic Type**: ✅ Supported

### Spacing

**Base Unit**: 8pt

**Scale**:

- XXS: 4pt
- XS: 8pt
- S: 12pt
- M: 16pt
- L: 24pt
- XL: 32pt
- XXL: 48pt

## Navigation

**Primary Pattern**: [Tab Bar/Sidebar/Navigation Stack]

### Rationale

[Why this navigation pattern]

### Tab Bar Structure (if applicable)

1. **Tab 1**: [Name] - [Icon] - [Purpose]
2. **Tab 2**: [Name] - [Icon] - [Purpose]
3. **Tab 3**: [Name] - [Icon] - [Purpose]

## Screens

### Screen 1: [Name]

- **Purpose**: [What users do here]
- **Navigation**: [How users get here]
- **Key Elements**: [Main UI components]
- **States**: Loading, Empty, Error, Success

### Screen 2: [Name]

[Same structure]

## User Flows

### Flow 1: [Primary User Flow]

Launch ↓ Home Screen ↓ Action Button ↓ Detail View ↓ Completion

### Flow 2: [Another Flow]
[Same structure]

## Accessibility

### VoiceOver
- [ ] All interactive elements labeled
- [ ] Meaningful labels (not just "Button")
- [ ] Logical navigation order
- [ ] Tested with VoiceOver

### Dynamic Type
- [ ] All text uses text styles
- [ ] Layout adapts to larger text
- [ ] Tested at largest size

### Color Contrast
- [ ] WCAG AA compliance (4.5:1 for text)
- [ ] Not relying on color alone for information

### Other
- [ ] Reduce Motion support
- [ ] Haptic feedback
- [ ] Clear tap targets (44pt minimum)

## Platform Considerations

### iPhone
- Supported sizes: [All/iPhone 13 and newer]
- Orientation: [Portrait only/Both]

### iPad
- Support: [Yes/No/Future]
- Layout: [Adaptive/Optimized]

### Mac Catalyst
- Support: [Yes/No/Future]

## Design Assets

- **App Icon**: [Status - designed/placeholder]
- **Launch Screen**: [Approach]
- **SF Symbols**: [Symbols used]
- **Custom Icons**: [If any]

## Onboarding

### First Launch
- [ ] Welcome screen
- [ ] Feature highlights
- [ ] Permission requests (with rationale)
- [ ] Optional tutorial

## Empty States

- [Screen] when empty: [Message/visual]
- [Feature] when no data: [Message/visual]

## Error States

- Network error: [Message and UI]
- Data error: [Message and UI]
- Permission denied: [Message and UI]

## Loading States

- Initial load: [Loading indicator type]
- Pull to refresh: [System/Custom]
- Pagination: [Approach]

File 6: data-model.md (if applicable)

# [App Name] - Data Model

**Last Updated**: [Date]

## Entities

### Entity 1: [Name]

**Purpose**: [What this entity represents]

**Attributes**:

- `id`: UUID (unique identifier)
- `attribute1`: String (description)
- `attribute2`: Date (description)
- `attribute3`: Double (description)

**Relationships**:

- `relationshipName`: Relationship to [OtherEntity] (one-to-many/many-to-one)

**Validation**:

- [Validation rule 1]
- [Validation rule 2]

### Entity 2: [Name]

[Same structure]

## Relationships

Entity1 ├── one-to-many → Entity2 └── many-to-one → Entity3

Entity2 └── many-to-many → Entity4

## Data Flow

### Create
1. User creates [entity] via UI
2. ViewModel validates input
3. Repository creates entity in persistence layer
4. UI updates with new entity

### Read
1. ViewModel requests data from repository
2. Repository fetches from persistence layer
3. Data transformed for presentation
4. UI displays data

### Update
1. User modifies [entity]
2. ViewModel validates changes
3. Repository updates persistence layer
4. UI reflects changes

### Delete
1. User confirms deletion
2. ViewModel requests deletion
3. Repository removes from persistence
4. UI updates

## Persistence Strategy

**Technology**: [Core Data/SwiftData]

**Context Management**:
- Main context: UI operations
- Background context: Heavy operations

**Fetch Strategies**:
- Batching: [Yes/No - batch size]
- Faulting: [Approach]
- Prefetching: [Relationships to prefetch]

## Cloud Sync

**Strategy**: [CloudKit/Firebase/None]

**Conflict Resolution**:
[How conflicts are handled]

**Sync Triggers**:
- App launch
- Significant data change
- Manual sync option

## Migration Strategy

**Version 1**: Initial schema

**Future Migrations**:
[Plan for schema changes]

## Sample Data

```swift
// Example entity
let example = Entity1(
    id: UUID(),
    attribute1: "Example",
    attribute2: Date(),
    attribute3: 123.45
)

**File 7: personas.md** (if created)
```markdown
# [App Name] - User Personas

**Last Updated**: [Date]

## Persona 1: [Name]

**Photo/Avatar**: [Optional]

### Demographics
- **Age**: [Age range]
- **Occupation**: [Job/role]
- **Location**: [Where they live]
- **Tech Savviness**: Low/Medium/High

### Background
[2-3 sentences about this person's background and context]

### Goals
- [Goal 1]
- [Goal 2]
- [Goal 3]

### Pain Points
- [Pain point 1]
- [Pain point 2]
- [Pain point 3]

### How [App Name] Helps
[How your app solves their problems]

### User Journey
1. [Discovery - how they find the app]
2. [Onboarding - first experience]
3. [Regular Usage - typical use case]
4. [Value Realization - when they see benefit]

### Quote
> "[A quote that represents this persona's perspective]"

## Persona 2: [Name]
[Same structure]

## Persona Comparison

| Aspect | Persona 1 | Persona 2 |
|--------|-----------|-----------|
| Primary Goal | [Goal] | [Goal] |
| Key Pain Point | [Pain] | [Pain] |
| Usage Frequency | Daily | Weekly |
| Key Feature | [Feature] | [Feature] |

File 8: roadmap.md

# [App Name] - Roadmap

**Last Updated**: [Date]

## Timeline Overview

Planning Development Testing Launch |==============|===============|===========|=====> [Date range] [Date range] [Date range] [Date]

## Milestones

### Milestone 1: Project Setup
**Target**: [Date/Week 1]
- [ ] Create Xcode project
- [ ] Set up git repository
- [ ] Configure CI/CD
- [ ] Create initial project structure
- [ ] Set up dependencies

### Milestone 2: Core Architecture
**Target**: [Date/Week 2]
- [ ] Implement MVVM structure
- [ ] Set up Core Data/persistence
- [ ] Create base ViewModels
- [ ] Set up networking layer

### Milestone 3: MVP Features
**Target**: [Date/Weeks 3-6]
- [ ] Feature 1 implementation
- [ ] Feature 2 implementation
- [ ] Feature 3 implementation
- [ ] Basic UI/UX
- [ ] Integration testing

### Milestone 4: Polish & Testing
**Target**: [Date/Week 7-8]
- [ ] UI polish
- [ ] Accessibility implementation
- [ ] Performance optimization
- [ ] Bug fixes
- [ ] User testing

### Milestone 5: Launch Prep
**Target**: [Date/Week 9]
- [ ] App Store assets
- [ ] Privacy policy
- [ ] App Store submission
- [ ] Marketing materials
- [ ] Support documentation

### Milestone 6: v1.0 Launch
**Target**: [Date]
- [ ] Submit to App Store
- [ ] App Review
- [ ] Public release
- [ ] Monitor analytics & crashes
- [ ] Gather user feedback

## Version Planning

### v1.0 - MVP (Launch)
- Core features only
- Stable and polished
- **Target**: [Date]

### v1.1 - Quick Improvements
- User feedback incorporated
- Quick wins
- Performance improvements
- **Target**: [Date - 1 month after launch]

### v2.0 - Major Update
- [Major feature 1]
- [Major feature 2]
- Significant improvements
- **Target**: [Date - 3-6 months after launch]

## Feature Release Schedule

| Version | Features | Target Date |
|---------|----------|-------------|
| v1.0 | [Feature 1, 2, 3] | [Date] |
| v1.1 | [Feature 4, improvements] | [Date] |
| v1.2 | [Feature 5, 6] | [Date] |
| v2.0 | [Major features] | [Date] |

## Dependencies & Blockers

### Current Blockers
- [Blocker 1 - impact and mitigation]
- [Blocker 2 - impact and mitigation]

### External Dependencies
- [Dependency 1 - impact on timeline]
- [Dependency 2 - impact on timeline]

## Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
| [Risk 2] | High/Med/Low | High/Med/Low | [Strategy] |

## Resource Allocation

- **Development**: [X hours/weeks]
- **Design**: [X hours/weeks]
- **Testing**: [X hours/weeks]
- **Marketing**: [X hours/weeks]

## Success Metrics

### Launch Metrics (v1.0)
- Downloads: [Target]
- Active users: [Target]
- Crash-free rate: >99%
- App Store rating: >4.0

### 3-Month Metrics
- Downloads: [Target]
- Daily active users: [Target]
- Retention: [Target]%
- [Custom metric]: [Target]

## Notes

[Any additional timeline notes, assumptions, or considerations]

5. Provide Recommendations

After planning, provide tailored recommendations:

Recommendations Format

## 📋 Planning Recommendations

### High Priority Decisions Needed

1. [Critical decision 1 - options and recommendation]
2. [Critical decision 2 - options and recommendation]

### Suggested Next Steps

1. **Immediate**: [What to do first]
2. **Week 1**: [Early tasks]
3. **Week 2-4**: [MVP development focus]

### Resource Recommendations

- [Tool recommendations]
- [Library recommendations]
- [Learning resources if needed]

### Potential Challenges

- [Challenge 1 - mitigation strategy]
- [Challenge 2 - mitigation strategy]

### Time Estimates

- Planning & Setup: [X days/weeks]
- MVP Development: [X weeks/months]
- Testing & Polish: [X weeks]
- App Store Submission: [X weeks]

6. Analysis Process for Existing Apps

Note: This section is for analyzing existing apps. For new apps, use Section 3 instead.

When analyzing an existing app, follow this systematic approach:

Step 1: Discover the Codebase

Use Glob and Grep tools to understand the project structure:

Key Discovery Tasks:

1. Identify project structure

   • Use Glob to find main directories
   • Identify file organization pattern
   • Locate main app files, views, models

2. Detect tech stack

   • SwiftUI vs UIKit (search for "import SwiftUI" vs "UIViewController")
   • Architecture hints (look for ViewModels, Coordinators, Interactors)
   • Persistence layer (search for Core Data, SwiftData, Realm imports)
   • Third-party dependencies (check Package.swift, Podfile)

3. Assess codebase size and complexity

   • Count Swift files
   • Identify main features/modules
   • Note file sizes (potential massive files)

Step 2: Analyze Current State

Based on the analysis scope, evaluate different aspects:

Architecture Analysis:

• Current Pattern: What architecture is being used (MVVM, MVC, mixed)?
• Consistency: Is the pattern applied consistently?
• Separation of Concerns: Are responsibilities properly separated?
• Code Organization: How is code organized (by feature, by layer)?
• Recommendation: Should architecture be changed or improved?

Tech Stack Evaluation:

• UI Framework: SwiftUI/UIKit usage, is it appropriate?
• Minimum iOS: What's the deployment target, should it change?
• Persistence: What's being used, is it the right choice?
• Dependencies: List third-party dependencies, are they necessary?
• Networking: How is networking handled?
• Recommendation: Tech stack improvements or migrations

Code Quality Assessment:

• File Sizes: Any massive files (>500 lines)?
• Code Duplication: Patterns of repeated code
• Naming Conventions: Consistent and clear?
• Comments: Adequate documentation?
• Testing: Test coverage, test quality
• Recommendation: Priority refactoring areas

Feature Analysis:

• Current Features: List what the app does
• Feature Organization: How are features structured?
• Missing Features: Gaps or incomplete features
• Feature Quality: Well-implemented or need work?
• Recommendation: Feature priorities

Performance & Best Practices:

• Memory Management: Retain cycles, memory leaks
• SwiftUI Patterns: State management issues
• Core Data Usage: Context management, fetch patterns
• Error Handling: How errors are handled
• Recommendation: Performance improvements

UI/UX State:

• HIG Compliance: Basic compliance check
• Accessibility: VoiceOver support, Dynamic Type
• Navigation: Navigation patterns used
• Design Consistency: Consistent UI patterns
• Recommendation: UI/UX improvements

Step 3: Identify Issues and Gaps

Create a comprehensive issues list:

Critical Issues (must fix):

• Architecture problems causing bugs
• Performance bottlenecks
• Security vulnerabilities
• Crashes or critical bugs

Medium Priority (should fix):

• Code maintainability issues
• Missing best practices
• Incomplete features
• Technical debt

Low Priority (nice to have):

• Code style improvements
• Minor optimizations
• Documentation gaps

Step 4: Create Analysis Documentation Files

IMPORTANT: Create actual documentation files for the analysis that can be tracked and referenced.

Ask User About Documentation Location

Before creating files, ask where to put analysis documentation:

• docs/analysis/ (recommended)
• analysis/ (root-level)
• .claude/analysis/ (keep with Claude Code files)
• Custom location

Documentation Files to Create

For existing app analysis, create TWO sets of files:

Current State Documentation (what exists now): 1. docs/current/overview.md - Current app overview and status 2. docs/current/features.md - Current features and capabilities 3. docs/current/architecture.md - Current architecture and patterns 4. docs/current/tech-stack.md - Current technology stack 5. docs/current/ui-ux.md - Current UI/UX state (optional) 6. docs/current/data-model.md - Current data model (if applicable)

Analysis & Improvement Documentation (what needs to change): 7. docs/analysis/analysis-report.md - Full analysis and assessment 8. docs/analysis/recommendations.md - Prioritized improvement recommendations 9. docs/analysis/issues.md - Issues tracker with priorities 10. docs/analysis/roadmap.md - Improvement roadmap and timeline

Rationale: Separating current state from improvements provides:

• Clear baseline documentation (what exists)
• Clear improvement path (what to change)
• Knowledge transfer for new team members
• Historical record of app state
• Comparison point for measuring progress

Current State Documentation Templates

File 1: docs/current/overview.md

# [App Name] - Current State Overview

**Last Updated**: [Date]
**Analysis Date**: [Date]

## App Summary

- **Name**: [App Name]
- **Bundle ID**: [Bundle identifier]
- **Current Version**: [Version in App Store / Development]
- **Platform**: iOS [deployment target]+
- **Status**: [In Development / Production / Maintenance]
- **Team Size**: [Solo / Small / Medium / Large]

## Purpose

[What the app does - 2-3 sentences]

## Current Users

- **Target Audience**: [Who uses it]
- **User Base**: [Number of users if known]
- **Primary Use Cases**: [How users use it]

## Key Information

### Technical Overview

- **Architecture**: [MVVM/MVC/TCA/Mixed]
- **UI Framework**: [SwiftUI/UIKit/Hybrid]
- **Min iOS Version**: [Version]
- **Persistence**: [Core Data/SwiftData/Realm/etc.]
- **Backend**: [CloudKit/Firebase/Custom/None]

### Codebase Stats

- **Swift Files**: [Count]
- **Screens/Features**: [Count]
- **Lines of Code**: [Approximate]
- **Test Coverage**: [Percentage if known]

### App Store Presence

- **Listed**: [Yes/No]
- **Category**: [Category]
- **Rating**: [Rating if applicable]
- **Last Update**: [Date]

## Current State Assessment

- **Overall Health**: [Excellent/Good/Fair/Needs Work]
- **Code Quality**: [X/10]
- **Architecture**: [X/10]
- **Documentation**: [X/10]
- **Test Coverage**: [X/10]

## Known Issues

1. [Major known issue 1]
2. [Major known issue 2]
3. [Major known issue 3]

## Recent Changes

- [Recent significant change 1]
- [Recent significant change 2]

## Related Documents

- [features.md](./features.md) - Current features
- [architecture.md](./architecture.md) - Current architecture
- [tech-stack.md](./tech-stack.md) - Current tech stack
- [../analysis/analysis-report.md](../analysis/analysis-report.md) - Analysis & recommendations

File 2: docs/current/features.md

# [App Name] - Current Features

**Last Updated**: [Date]

## Core Features

### Feature 1: [Name]

- **Status**: ✅ Complete / 🚧 Partial / ❌ Broken
- **Location**: [File/Module]
- **Description**: [What it does]
- **Quality**: [Well-implemented / Needs work / Has issues]
- **Usage**: [Heavily used / Moderately used / Rarely used]
- **Known Issues**: [List issues if any]

### Feature 2: [Name]

[Same structure]

### Feature 3: [Name]

[Same structure]

## Secondary Features

### Feature 4: [Name]

[Same structure]

## Incomplete/Partial Features

### Feature X: [Name]

- **Status**: 🚧 Incomplete
- **What Works**: [Completed parts]
- **What's Missing**: [Missing functionality]
- **Why Incomplete**: [Reason if known]

## Deprecated/Legacy Features

### Old Feature: [Name]

- **Status**: ⚠️ Deprecated
- **Replacement**: [New feature or none]
- **Should Remove**: [Yes/No - why]

## Feature Categories

### User-Facing Features

- [Feature 1]
- [Feature 2]
- [Feature 3]

### System Features

- [Authentication]
- [Data sync]
- [Notifications]

## Feature Quality Matrix

| Feature     | Status | Quality | Issues   | Priority |
| ----------- | ------ | ------- | -------- | -------- |
| [Feature 1] | ✅     | Good    | None     | High     |
| [Feature 2] | 🚧     | Fair    | [Issues] | Medium   |
| [Feature 3] | ✅     | Poor    | [Issues] | High     |

## Features by Module/Screen

### [Module/Screen 1]

- Feature A
- Feature B

### [Module/Screen 2]

- Feature C
- Feature D

## User Journeys

### Journey 1: [Primary Use Case]

[Screen 1] → [Action] → [Screen 2] → [Completion]

**Status**: [Works well / Has issues]

### Journey 2: [Another Use Case]
[Same structure]

## Related Documents
- [overview.md](./overview.md) - App overview
- [architecture.md](./architecture.md) - How features are implemented
- [../analysis/recommendations.md](../analysis/recommendations.md) - Feature improvements

File 3: docs/current/architecture.md

# [App Name] - Current Architecture

**Last Updated**: [Date]

## Architecture Pattern

**Current Pattern**: [MVVM/MVC/TCA/VIPER/Mixed]

**Consistency**: [Highly consistent / Mostly consistent / Inconsistent / Very mixed]

**Assessment**: [2-3 sentences about architecture state]

## Current Project Structure

[AppName]/ ├── [Actual folder structure from codebase] ├── ├── └──

**Organization Method**: [By feature / By layer / Mixed / Unclear]

**Assessment**: [Is structure logical and maintainable?]

## Layer Breakdown

### Presentation Layer
**Files**: [Count]
**Pattern**: [SwiftUI Views / UIViewControllers]
**Quality**: [Assessment]
**Issues**: [List issues]

### Business Logic Layer
**Files**: [Count]
**Pattern**: [ViewModels / Presenters / Controllers]
**Quality**: [Assessment]
**Issues**: [List issues]

### Data Layer
**Files**: [Count]
**Pattern**: [Repositories / Services / Direct access]
**Quality**: [Assessment]
**Issues**: [List issues]

## Actual Data Flow

**Observed Pattern**:

[How data actually flows in the current app]

**Issues**: [Any flow issues observed]

## Architecture Debt

### Mixed Patterns
- [Location where pattern 1 used]
- [Location where pattern 2 used]
- **Impact**: [How this affects development]

### Massive Files
| File | Lines | Should Be | Effort to Fix |
|------|-------|-----------|---------------|
| [File1.swift] | [XXX] | [Split into X files] | [Effort] |
| [File2.swift] | [XXX] | [Split into X files] | [Effort] |

### Tight Coupling
- [Component 1] ↔ [Component 2] - [Issue]
- [Component 3] ↔ [Component 4] - [Issue]

### Missing Abstractions
- [Area lacking abstraction 1]
- [Area lacking abstraction 2]

## Code Organization

### Strengths
- ✅ [What's good about current organization]
- ✅ [Another strength]

### Weaknesses
- ❌ [What's problematic]
- ❌ [Another issue]

## Testing Architecture

**Current State**:
- **Unit Tests**: [Count] files, [X%] coverage
- **UI Tests**: [Count] files
- **Test Quality**: [Assessment]
- **Testability**: [How easy to test - Good/Fair/Poor]

## Dependencies

**External Dependencies**: [Count]
**Dependency Management**: [SPM/CocoaPods/Carthage/Mixed]
**Dependency Issues**: [Any problematic dependencies]

## Related Documents
- [overview.md](./overview.md) - App overview
- [tech-stack.md](./tech-stack.md) - Technology details
- [../analysis/recommendations.md](../analysis/recommendations.md) - Architecture improvements

File 4: docs/current/tech-stack.md

# [App Name] - Current Tech Stack

**Last Updated**: [Date]

## UI Framework

**Current**: [SwiftUI/UIKit/Hybrid]

**Details**:

- SwiftUI: [Percentage or areas]
- UIKit: [Percentage or areas]
- Hybrid Strategy: [How mixed]

**Assessment**: [Is current choice appropriate?]

## iOS Version Support

**Deployment Target**: iOS [X]
**Latest Tested**: iOS [X]

**Assessment**:

- [Too old / Appropriate / Could be higher]
- **Impact**: [Benefits/limitations of current target]

## Persistence

**Current**: [Core Data/SwiftData/Realm/UserDefaults/File System]

**Details**:

- Entities: [Count]
- Complexity: [Simple/Medium/Complex]
- Performance: [Good/Fair/Poor]

**Assessment**: [Is choice appropriate for needs?]

## Data Sync

**Strategy**: [CloudKit/Firebase/Custom/None]

**Details**:

- Working: [Yes/No/Partially]
- Conflicts: [How handled]
- Issues: [Any sync issues]

## Networking

**Library**: [URLSession/Alamofire/Moya/Custom]

**Details**:

- API Type: [REST/GraphQL/None]
- Error Handling: [Good/Fair/Poor]
- Offline Support: [Yes/No/Partial]

**Assessment**: [Appropriate for needs?]

## Dependency Management

**Current**: [SPM/CocoaPods/Carthage/Mixed/None]

**Details**:

- Total Dependencies: [Count]
- Management Quality: [Good/Fair/Poor]

## Third-Party Dependencies

| Dependency | Version | Purpose   | Status                   | Issues       |
| ---------- | ------- | --------- | ------------------------ | ------------ |
| [Name]     | [X.X.X] | [Purpose] | ✅ Updated / ⚠️ Outdated | [Any issues] |
| [Name]     | [X.X.X] | [Purpose] | ✅ Updated / ⚠️ Outdated | [Any issues] |

### Deprecated Dependencies

- [Dependency name] - [Why deprecated, what to use instead]

### Unnecessary Dependencies

- [Dependency that could be removed] - [Why not needed]

## Development Tools

**Currently Used**:

- **Linting**: [SwiftLint / None]
- **Formatting**: [SwiftFormat / None]
- **Analytics**: [Tool / None]
- **Crash Reporting**: [Tool / None]

## Backend Services

**Provider**: [CloudKit/Firebase/Supabase/Custom/None]

**Services Used**:

- [x] Authentication - [Status]
- [x] Database - [Status]
- [ ] Analytics - [Not used]
- [ ] Push Notifications - [Not used]

**Assessment**: [Working well / Has issues / Could be improved]

## CI/CD

**Current Setup**: [Xcode Cloud/GitHub Actions/Bitrise/None]

**Pipeline**:

- Automated builds: [Yes/No]
- Automated testing: [Yes/No]
- TestFlight deployment: [Yes/No]

**Assessment**: [Adequate / Needs improvement / Not setup]

## Build Configuration

**Configurations**: [Debug, Release, other]
**Build Time**: [Approximate time]
**Issues**: [Slow builds, configuration issues, etc.]

## Tech Stack Summary

UI: [SwiftUI/UIKit] iOS Target: [Version] Architecture: [Pattern] Persistence: [Technology] Backend: [Service/None] Networking: [Library] Dependencies: [Manager] CI/CD: [Tool/None]

## Technology Debt

### Outdated Technologies
- [Technology 1] - Current: [Version], Latest: [Version]
- [Technology 2] - Current: [Version], Latest: [Version]

### Missing Modern Features
- [Feature available in newer iOS] - Requires iOS [X]
- [Another feature] - Requires iOS [X]

## Related Documents
- [overview.md](./overview.md) - App overview
- [architecture.md](./architecture.md) - Architecture patterns
- [../analysis/recommendations.md](../analysis/recommendations.md) - Tech stack improvements

File 5: docs/current/ui-ux.md (Optional - if doing UI/UX analysis)

# [App Name] - Current UI/UX State

**Last Updated**: [Date]

## Current Design System

### Colors

**Current Usage**: [Consistent / Mixed / Inconsistent]

**Observed Colors**:

- Primary: [Color/None defined]
- Secondary: [Color/None defined]
- Background: [System/Custom]

**Assessment**: [Has design system / Inconsistent / No system]

### Typography

**Font**: [SF Pro/Custom/Mixed]
**Dynamic Type**: [Supported / Partial / Not supported]

**Assessment**: [Consistent / Inconsistent]

### Spacing

**System**: [8pt grid / Inconsistent / No system]

**Assessment**: [Consistent / Needs improvement]

## Navigation

**Pattern**: [Tab Bar/Sidebar/Stack/Mixed]

**Details**:

- Tabs: [Count if applicable]
- Hierarchy: [Clear / Confusing]
- Back navigation: [Works well / Has issues]

**Assessment**: [Good / Could be improved / Confusing]

## Screen Inventory

### Main Screens

1. **[Screen Name]** - [Brief description] - Quality: [Good/Fair/Poor]
2. **[Screen Name]** - [Brief description] - Quality: [Good/Fair/Poor]
3. **[Screen Name]** - [Brief description] - Quality: [Good/Fair/Poor]

### Secondary Screens

[List]

## HIG Compliance

**Overall**: [Compliant / Mostly / Many issues]

**Issues Found**:

- [HIG violation 1]
- [HIG violation 2]
- [HIG violation 3]

## Accessibility

**VoiceOver**: [Supported / Partial / Not supported]
**Dynamic Type**: [Supported / Partial / Not supported]
**Color Contrast**: [Good / Some issues / Many issues]

**Assessment**: [Well implemented / Needs work / Poor]

## User Experience Issues

### Major Issues

- [UX issue 1]
- [UX issue 2]

### Minor Issues

- [Minor issue 1]
- [Minor issue 2]

## Strengths

- ✅ [UI/UX strength 1]
- ✅ [UI/UX strength 2]

## Related Documents

- [../analysis/recommendations.md](../analysis/recommendations.md) - UI/UX improvements

File 6: docs/current/data-model.md (If applicable)

# [App Name] - Current Data Model

**Last Updated**: [Date]

## Persistence Technology

[Core Data / SwiftData / Realm / Other]

## Current Entities

### Entity 1: [Name]

**Attributes**:

- [attribute1]: [Type]
- [attribute2]: [Type]

**Relationships**:

- [relationship]: to [Entity]

**Issues**: [Any issues with this entity]

### Entity 2: [Name]

[Same structure]

## Current Relationships

[Entity1] ←→ [Entity2] (relationship type) [Entity2] → [Entity3] (relationship type)

## Data Flow

**Current**: [How data currently flows through the app]

**Issues**: [Any data flow problems]

## Performance

**Fetch Performance**: [Good / Fair / Slow]
**Save Performance**: [Good / Fair / Slow]
**Known Bottlenecks**: [List if any]

## Migration History

**Current Version**: [Schema version]
**Migrations**: [Count of migrations performed]
**Issues**: [Any migration issues]

## Related Documents
- [architecture.md](./architecture.md) - How data layer is organized
- [../analysis/recommendations.md](../analysis/recommendations.md) - Data model improvements

---

Analysis File Templates

File 7: docs/analysis/analysis-report.md

# [App Name] - Analysis Report

## Executive Summary

- **App Purpose**: [What the app does]
- **Codebase Size**: [Number of files, screens]
- **Current Tech Stack**: [List main technologies]
- **Overall Health**: [Rating: Excellent/Good/Fair/Needs Work]
- **Primary Concerns**: [Top 3 issues]

## Current State

### Architecture

- **Pattern**: [MVVM/MVC/etc.]
- **Consistency**: [Assessment]
- **Rating**: X/10
- **Notes**: [Key observations]

### Tech Stack

- **UI Framework**: [SwiftUI/UIKit/Hybrid]
- **iOS Target**: [Version]
- **Persistence**: [Core Data/etc.]
- **Dependencies**: [List]
- **Rating**: X/10
- **Notes**: [Assessment]

### Code Quality

- **Organization**: [Assessment]
- **File Sizes**: [Average, largest files]
- **Naming**: [Assessment]
- **Testing**: [Coverage, quality]
- **Rating**: X/10
- **Notes**: [Key findings]

### Features

- **Current Features**: [List]
- **Feature Quality**: [Assessment]
- **Gaps**: [Missing features]
- **Rating**: X/10

### UI/UX

- **HIG Compliance**: [Basic assessment]
- **Accessibility**: [State]
- **Navigation**: [Patterns used]
- **Rating**: X/10

## Issues Found

### Critical (Must Fix)

1. [Issue 1 - Location - Impact - Recommendation]
2. [Issue 2 - Location - Impact - Recommendation]

### Medium Priority (Should Fix)

1. [Issue - Recommendation]
2. [Issue - Recommendation]

### Low Priority (Nice to Have)

1. [Issue - Recommendation]

## Recommendations

### Immediate Actions (Week 1)

1. [Action 1 - Why - Impact]
2. [Action 2 - Why - Impact]

### Short-term Improvements (Month 1)

1. [Improvement - Benefits]
2. [Improvement - Benefits]

### Long-term Strategy (3-6 months)

1. [Strategic change - Rationale]
2. [Strategic change - Rationale]

### Architecture Recommendations

- **Current**: [Current pattern]
- **Recommendation**: [Keep/Migrate/Improve]
- **Rationale**: [Why]
- **Migration Path**: [If applicable]

### Tech Stack Recommendations

- **SwiftUI Migration**: [If UIKit] - [Timeline, approach]
- **Dependency Updates**: [What to update/remove]
- **iOS Version**: [Should deployment target change?]
- **New Additions**: [Recommended libraries/tools]

### Refactoring Priorities

1. **High Priority**: [What - Why - Effort]
2. **Medium Priority**: [What - Why - Effort]
3. **Low Priority**: [What - Why - Effort]

## Estimated Effort

### Quick Wins (1-2 weeks)

- [Item 1]
- [Item 2]

### Medium Effort (1-2 months)

- [Item 1]
- [Item 2]

### Large Effort (3-6 months)

- [Item 1]
- [Item 2]

## Next Steps

1. [ ] [Immediate action 1]
2. [ ] [Immediate action 2]
3. [ ] [Plan refactoring strategy]
4. [ ] [Address critical issues]
5. [ ] [Implement quick wins]

File 2: recommendations.md

# [App Name] - Recommendations

**Last Updated**: [Date]
**Analysis Date**: [Date]

## Executive Summary

**Overall App Health**: [Excellent/Good/Fair/Needs Work]

**Top 3 Priorities**:

1. [Priority 1 - Impact]
2. [Priority 2 - Impact]
3. [Priority 3 - Impact]

## Immediate Actions (Week 1)

### 1. [Action Name]

- **Category**: [Architecture/Code Quality/Performance/etc.]
- **Priority**: Critical/High/Medium
- **Effort**: [Hours/Days]
- **Impact**: [Description of benefit]
- **Action Items**:
  - [ ] [Specific task 1]
  - [ ] [Specific task 2]

### 2. [Action Name]

[Same structure]

## Short-term Improvements (1-2 Months)

### Architecture Improvements

- **Current State**: [Current architecture issues]
- **Recommended Changes**:
  - [Change 1 - Rationale]
  - [Change 2 - Rationale]
- **Effort**: [Estimate]
- **Benefits**: [Expected improvements]

### Code Quality Improvements

- **Current State**: [Code quality issues]
- **Recommended Changes**:
  - [Change 1 - Rationale]
  - [Change 2 - Rationale]
- **Effort**: [Estimate]
- **Benefits**: [Expected improvements]

### Tech Stack Updates

- **Current State**: [Tech stack issues]
- **Recommended Changes**:
  - [Change 1 - Rationale - Migration path]
  - [Change 2 - Rationale - Migration path]
- **Effort**: [Estimate]
- **Benefits**: [Expected improvements]

## Long-term Strategy (3-6 Months)

### Strategic Recommendation 1: [Name]

- **Current State**: [Where we are]
- **Target State**: [Where we want to be]
- **Rationale**: [Why this change]
- **Approach**: [How to get there]
- **Timeline**: [Phases and milestones]
- **Risks**: [Potential issues and mitigation]

### Strategic Recommendation 2: [Name]

[Same structure]

## Technology Migrations

### SwiftUI Migration (if UIKit app)

- **Recommended**: [Yes/No/Partial]
- **Rationale**: [Why or why not]
- **Approach**: [Strategy - feature by feature, new features only, etc.]
- **Timeline**: [When to start, expected completion]
- **Risks**: [Challenges and mitigation]

### Architecture Migration (if recommended)

- **From**: [Current pattern]
- **To**: [Recommended pattern]
- **Rationale**: [Why change]
- **Approach**: [Migration strategy]
- **Timeline**: [Phases]
- **Risks**: [Challenges]

### iOS Version Update

- **Current**: iOS [X]
- **Recommended**: iOS [X]
- **Rationale**: [Benefits of updating]
- **Impact**: [What breaks, what becomes available]
- **Timeline**: [When to update]

## Dependency Recommendations

### Dependencies to Remove

| Dependency | Reason to Remove | Alternative           |
| ---------- | ---------------- | --------------------- |
| [Name]     | [Why remove]     | [What to use instead] |

### Dependencies to Add

| Dependency | Purpose        | Justification |
| ---------- | -------------- | ------------- |
| [Name]     | [What it does] | [Why needed]  |

### Dependencies to Update

| Dependency | Current   | Target    | Breaking Changes   |
| ---------- | --------- | --------- | ------------------ |
| [Name]     | [Version] | [Version] | [Yes/No - Details] |

## Refactoring Priorities

### High Priority

| File/Area   | Issue     | Recommendation | Effort       |
| ----------- | --------- | -------------- | ------------ |
| [File:Line] | [Problem] | [Solution]     | [Hours/Days] |

### Medium Priority

[Same table structure]

### Low Priority

[Same table structure]

## Testing Recommendations

### Unit Testing

- **Current Coverage**: [X%]
- **Target Coverage**: [X%]
- **Priority Areas**:
  - [Area 1 - Why important]
  - [Area 2 - Why important]
- **Effort**: [Estimate]

### UI Testing

- **Current State**: [Assessment]
- **Recommendations**:
  - [Test 1 - Rationale]
  - [Test 2 - Rationale]
- **Effort**: [Estimate]

## Performance Optimization

### Performance Issues Found

| Area       | Issue     | Impact        | Recommendation |
| ---------- | --------- | ------------- | -------------- |
| [Location] | [Problem] | [User impact] | [Solution]     |

### Optimization Priorities

1. **[Optimization 1]** - High impact, low effort
2. **[Optimization 2]** - Medium impact, medium effort
3. **[Optimization 3]** - High impact, high effort

## Security & Privacy

### Security Improvements

- [ ] [Security improvement 1]
- [ ] [Security improvement 2]

### Privacy Enhancements

- [ ] [Privacy enhancement 1]
- [ ] [Privacy enhancement 2]

## UI/UX Improvements

### HIG Compliance

- **Current State**: [Assessment]
- **Recommendations**:
  - [Issue 1 - Fix]
  - [Issue 2 - Fix]

### Accessibility

- **Current State**: [Assessment]
- **Priority Improvements**:
  - [ ] [Improvement 1]
  - [ ] [Improvement 2]

## Documentation

### Documentation to Create

- [ ] [Doc 1 - Purpose]
- [ ] [Doc 2 - Purpose]

### Documentation to Update

- [ ] [Doc 1 - What needs updating]
- [ ] [Doc 2 - What needs updating]

## Success Metrics

### Before Improvements

- [Metric 1]: [Current value]
- [Metric 2]: [Current value]
- [Metric 3]: [Current value]

### After Improvements (Expected)

- [Metric 1]: [Target value]
- [Metric 2]: [Target value]
- [Metric 3]: [Target value]

## Related Documents

- [analysis-report.md](./analysis-report.md) - Full analysis
- [issues.md](./issues.md) - Issues tracker
- [roadmap.md](./roadmap.md) - Improvement roadmap

File 3: issues.md

# [App Name] - Issues Tracker

**Last Updated**: [Date]

## Critical Issues (Fix Immediately)

### Issue 1: [Title]

- **Category**: [Bug/Architecture/Performance/Security]
- **Location**: `File.swift:Line`
- **Severity**: Critical
- **Impact**: [How this affects users or app stability]
- **Description**: [Detailed description]
- **Reproduction**: [How to reproduce if bug]
- **Recommendation**: [How to fix]
- **Effort**: [Estimate]
- **Status**: [ ] Open / [ ] In Progress / [ ] Fixed

### Issue 2: [Title]

[Same structure]

## High Priority Issues (Fix Soon)

### Issue 3: [Title]

- **Category**: [Category]
- **Location**: `File.swift:Line`
- **Severity**: High
- **Impact**: [Impact description]
- **Description**: [Details]
- **Recommendation**: [Solution]
- **Effort**: [Estimate]
- **Status**: [ ] Open / [ ] In Progress / [ ] Fixed

## Medium Priority Issues (Plan to Fix)

### Issue 4: [Title]

- **Category**: [Category]
- **Location**: `File.swift:Line`
- **Severity**: Medium
- **Impact**: [Impact description]
- **Description**: [Details]
- **Recommendation**: [Solution]
- **Effort**: [Estimate]
- **Status**: [ ] Open

## Low Priority Issues (Nice to Have)

### Issue 5: [Title]

- **Category**: [Category]
- **Location**: `File.swift:Line`
- **Severity**: Low
- **Impact**: [Impact description]
- **Description**: [Details]
- **Recommendation**: [Solution]
- **Effort**: [Estimate]
- **Status**: [ ] Open

## Issues by Category

### Architecture Issues

- [Issue #1 - Title]
- [Issue #2 - Title]

### Code Quality Issues

- [Issue #3 - Title]
- [Issue #4 - Title]

### Performance Issues

- [Issue #5 - Title]

### Security Issues

- [Issue #6 - Title]

### UI/UX Issues

- [Issue #7 - Title]

### Testing Issues

- [Issue #8 - Title]

## Issues Summary

| Priority  | Count   | Resolved | Remaining |
| --------- | ------- | -------- | --------- |
| Critical  | [X]     | [X]      | [X]       |
| High      | [X]     | [X]      | [X]       |
| Medium    | [X]     | [X]      | [X]       |
| Low       | [X]     | [X]      | [X]       |
| **Total** | **[X]** | **[X]**  | **[X]**   |

## Resolution Progress

- [x] Issue #1 - [Title] - Fixed on [Date]
- [ ] Issue #2 - [Title] - In progress
- [ ] Issue #3 - [Title] - Open

## Notes

[Any additional context about issues, patterns observed, or considerations]

File 4: roadmap.md

# [App Name] - Improvement Roadmap

**Last Updated**: [Date]
**Analysis Date**: [Date]

## Roadmap Overview

Stabilize Improve Modernize Enhance |=============|=============|=============|============> Weeks 1-2 Weeks 3-8 Months 3-6 Ongoing

## Phase 1: Stabilize (Weeks 1-2)

**Goal**: Fix critical issues and implement quick wins

### Critical Fixes
- [ ] [Critical issue 1] - [Effort] - Due: [Date]
- [ ] [Critical issue 2] - [Effort] - Due: [Date]

### Quick Wins
- [ ] [Quick win 1] - [Benefit] - [Effort]
- [ ] [Quick win 2] - [Benefit] - [Effort]
- [ ] [Quick win 3] - [Benefit] - [Effort]

### Success Criteria
- All critical issues resolved
- No crashes on critical paths
- Quick wins shipped

## Phase 2: Improve (Weeks 3-8)

**Goal**: Refactor priority areas and improve code quality

### Week 3-4: Architecture Improvements
- [ ] [Refactoring 1] - [Files affected]
- [ ] [Refactoring 2] - [Files affected]
- [ ] [Improvement 1]

### Week 5-6: Code Quality
- [ ] [Quality improvement 1]
- [ ] [Add tests for critical areas]
- [ ] [Update dependencies]

### Week 7-8: Performance & UX
- [ ] [Performance optimization 1]
- [ ] [UX improvement 1]
- [ ] [Accessibility improvements]

### Success Criteria
- Code quality score improved to [X/10]
- Test coverage at [X%]
- Performance metrics improved by [X%]

## Phase 3: Modernize (Months 3-6)

**Goal**: Major technical improvements and migrations

### Month 3: [Focus Area]
- [ ] [Major improvement 1]
- [ ] [Migration step 1]

### Month 4: [Focus Area]
- [ ] [Major improvement 2]
- [ ] [Migration step 2]

### Month 5-6: [Focus Area]
- [ ] [Complete migration]
- [ ] [Feature enhancements]
- [ ] [Comprehensive testing]

### Success Criteria
- [Major goal achieved]
- [Migration completed]
- [New capabilities enabled]

## Phase 4: Enhance (Ongoing)

**Goal**: Continuous improvement and new features

### Continuous Improvements
- Regular dependency updates
- Code quality maintenance
- Performance monitoring
- Technical debt management

### New Features
- [Feature 1] - [When]
- [Feature 2] - [When]
- [Feature 3] - [When]

## Milestones

### Milestone 1: Critical Issues Resolved
**Target**: [Date - Week 2]
- All critical issues fixed
- Quick wins implemented
- App stability improved

### Milestone 2: Code Quality Improved
**Target**: [Date - Week 8]
- Refactoring complete
- Test coverage at target
- Dependencies updated

### Milestone 3: Modernization Complete
**Target**: [Date - Month 6]
- Migrations finished
- New architecture stabilized
- Performance optimized

## Effort Estimates

### Quick Wins (1-2 Weeks Total)
| Item | Effort | Priority |
|------|--------|----------|
| [Quick win 1] | [X hours] | High |
| [Quick win 2] | [X hours] | High |
| [Quick win 3] | [X hours] | Medium |

### Medium Effort (1-2 Months Total)
| Item | Effort | Priority |
|------|--------|----------|
| [Item 1] | [X weeks] | High |
| [Item 2] | [X weeks] | Medium |

### Large Effort (3-6 Months Total)
| Item | Effort | Priority |
|------|--------|----------|
| [Item 1] | [X months] | High |
| [Item 2] | [X months] | Medium |

## Resource Requirements

- **Development**: [X hours/week]
- **Testing**: [X hours/week]
- **Code Review**: [X hours/week]
- **Documentation**: [X hours]

## Risks & Dependencies

### Risks
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk 1] | High/Med/Low | [Strategy] |
| [Risk 2] | High/Med/Low | [Strategy] |

### Dependencies
- [Dependency 1 - Impact if delayed]
- [Dependency 2 - Impact if delayed]

## Success Metrics

### Technical Metrics
- **Code Quality**: [Current X/10] → [Target Y/10]
- **Test Coverage**: [Current X%] → [Target Y%]
- **Build Time**: [Current Xs] → [Target Ys]
- **Crash-Free Rate**: [Current X%] → [Target Y%]

### User-Facing Metrics
- **App Launch Time**: [Current Xs] → [Target Ys]
- **Screen Load Time**: [Current Xs] → [Target Ys]
- **User Rating**: [Current X.X] → [Target Y.Y]

## Related Documents
- [analysis-report.md](./analysis-report.md) - Full analysis
- [recommendations.md](./recommendations.md) - Detailed recommendations
- [issues.md](./issues.md) - Issues tracker

Step 5: Provide Actionable Roadmap

Summarize the created documentation and next steps:

Phase 1: Stabilize (Weeks 1-2)

• Fix critical issues
• Address immediate bugs
• Implement quick wins

Phase 2: Improve (Weeks 3-8)

• Refactor priority areas
• Improve architecture consistency
• Add missing tests
• Update dependencies

Phase 3: Modernize (Months 3-6)

• Architecture migration (if needed)
• Tech stack updates (SwiftUI, etc.)
• Feature enhancements
• Performance optimization

Phase 4: Enhance (Ongoing)

• New features
• Continuous improvement
• Best practices maintenance

Existing App Analysis Tips

Be Thorough but Practical:

• Don't recommend rewriting unless truly necessary
• Prioritize impact vs effort
• Consider team bandwidth
• Balance idealism with pragmatism

Respect Existing Decisions:

• Understand why current choices were made
• Some "anti-patterns" may have valid reasons
• Consider historical context
• Be constructive, not critical

Focus on Value:

• Prioritize user-facing improvements
• Balance technical debt with features
• Quick wins build momentum
• Long-term vision with short-term gains

Consider Migration Paths:

• Incremental over big-bang
• Feature-by-feature migration
• Hybrid approaches during transition
• Risk mitigation strategies

Planning Tips

Ask Questions Early

• Don't assume requirements
• Clarify ambiguous needs
• Understand constraints upfront
• Use AskUserQuestion tool to gather context

Tailor to Project Type

Personal Projects:

• Simpler architecture often better
• Focus on learning and shipping
• Can use latest iOS versions
• Fewer third-party dependencies

Client Projects:

• Document everything
• Consider maintenance burden
• Balance features vs timeline
• Professional testing standards

Startups:

• Ship fast, iterate
• Plan for scale but start simple
• Analytics crucial
• User feedback loops important

Be Pragmatic

• Perfect is enemy of good
• Start simple, refine later
• Don't over-engineer for MVP
• Focus on core value proposition

Think Mobile-First

• Offline-first considerations
• Battery and performance
• Small screen constraints
• Touch interactions
• iOS platform conventions

References

• Swift API Design Guidelines
• iOS Human Interface Guidelines
• App Store Review Guidelines
• architecture-guide.md - Detailed architecture decisions
• tech-stack-options.md - Technology selection guide
• planning-checklist.md - Comprehensive planning checklist

Notes

• Use planning-checklist.md for comprehensive phase-by-phase planning
• Refer to architecture-guide.md for detailed architecture patterns
• Check tech-stack-options.md for technology recommendations
• Always generate the planning document for user reference
• Tailor depth of planning to user's needs and project type
• Use AskUserQuestion to clarify requirements and preferences

---

Source: flight505/skill-forge — distributed by TomeVault.