rshankras 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:
Define App Purpose
- What problem does it solve?
- What's the core value proposition?
- What makes it different?
Identify Target Users
- Who will use this app?
- What are their goals and pain points?
- Create 1-2 user personas if helpful
Feature Definition
- List all potential features
- Categorize: MVP (must-have), v2 (nice-to-have), future
- Prioritize based on value and complexity
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:
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
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
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
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:
Design System
- Color palette (consider dark mode)
- Typography (SF Pro, custom fonts)
- Spacing system (8pt grid recommended)
- Component library planning
Navigation Pattern
- Tab bar (2-5 main sections)
- Sidebar (iPad, complex hierarchies)
- Navigation stack (linear flows)
- Sheet/modal presentations
- Recommend based on app structure
Screen Planning
- List all main screens
- Create simple wireframes or descriptions
- Define screen hierarchy
- Plan empty states, loading states, error states
Accessibility First
- Dynamic Type support
- VoiceOver compatibility
- Color contrast requirements
- Accessibility features priority
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:
Performance Targets
- Target device range (iPhone only, iPad support, Mac Catalyst)
- Performance benchmarks
- Memory constraints
- Battery usage considerations
Security & Privacy
- Authentication needs (if any)
- Data encryption requirements
- Privacy policy requirements
- Secure storage for sensitive data
- App Transport Security compliance
Testing Strategy
- Unit testing approach and coverage goals
- UI testing requirements
- Beta testing plan
- QA process
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:
App Store Planning
- App name availability check
- Bundle identifier decision
- Screenshots/preview planning
- App description and keywords
Monetization (if applicable)
- Free, paid, freemium, subscription
- In-app purchases planning
- Ad integration strategy
Localization
- Initial language(s)
- Internationalization strategy
- Future localization plans
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:
Identify project structure
- Use Glob to find main directories
- Identify file organization pattern
- Locate main app files, views, models
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)
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]
**D
…(truncated)