Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
rshankras avatar

App Planner

rshankras/claude-code-apple-skills

  • 2 installs
  • 591 repo stars
  • Updated July 24, 2026
  • rshankras/claude-code-apple-skills

Guides comprehensive iOS/Swift app planning for new apps or audits of existing ones, covering product, technical stack, UI/UX, and distribution decisions.

About

Walks through planning a new iOS/Swift app from concept to architecture or auditing an existing app's state and tech stack. A developer uses it to define features, requirements, and a distribution strategy or to evaluate an app for improvement.

  • Separate flows for new-app planning and existing-app audits
  • Covers product, technical, UI/UX, and distribution considerations

App Planner by the numbers

  • 2 all-time installs (skills.sh)
  • Ranked #2,412 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/rshankras/claude-code-apple-skills --skill app-planner

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs2
repo stars★ 591
Last updatedJuly 24, 2026
Repositoryrshankras/claude-code-apple-skills ↗

What it does

Guides comprehensive iOS/Swift app planning for new apps or audits of existing ones, covering product, technical stack, UI/UX, and distribution decisions.

Files

SKILL.mdMarkdownGitHub ↗

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

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

File 7: personas.md (if created)

# [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

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

Related skills

mattpocockGrill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.691k196kmattpocockGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.585k196kopen.feishu.cnLark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.493kopen.feishu.cnLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.493kopen.feishu.cnLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).493kopen.feishu.cnLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.493k
Productivity & Planningpm
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.