planning-android-implementation

Implementation Planning

This skill takes a refined specification (ideally from the refining-android-requirements skill) and produces a phased implementation plan with architecture design, file inventory, and risk assessment.

Prerequisite: A clear set of requirements. If requirements are vague or incomplete, invoke the refining-android-requirements skill first.

---

Step 1: Classify Change

Determine the change type to guide scope and planning depth:

Type	Description	Typical Scope
New Feature	Entirely new functionality, screens, or flows	New files + modifications, multi-phase
Enhancement	Extending existing feature with new capabilities	Mostly modifications, 1-2 phases
Bug Fix	Correcting incorrect behavior	Targeted modifications, single phase
Refactoring	Restructuring without behavior change	Modifications only, migration-aware
Infrastructure	Build, CI, tooling, or dependency changes	Config files, minimal code changes

State the classification and rationale before proceeding.

---

Step 2: Codebase Exploration

Search the codebase to find reference implementations and integration points. Use the discovery commands from the build-test-verify skill as needed.

Find Pattern Anchors

Identify 2-3 existing files that serve as templates for the planned work:

**Pattern Anchors:**
1. [file path] — [why this is a good reference]
2. [file path] — [why this is a good reference]
3. [file path] — [why this is a good reference]

Map Integration Points

Identify files that must be modified to integrate the new work:

• Navigation: Nav graph registrations, route definitions
• Dependency Injection: Hilt modules, @Provides / @Binds functions
• Data Layer: Repository interfaces, data source interfaces, Room DAOs
• API Layer: Retrofit service interfaces, request/response models
• Feature Flags: Feature flag definitions and checks
• Managers: Single-responsibility data layer classes (see docs/ARCHITECTURE.md Managers section)
• Test Fixtures: Shared test utilities in src/testFixtures/ directories
• Product Flavor Source Sets: Code in src/standard/ vs src/main/ for Play Services dependencies

Document Existing Patterns

Note the specific patterns used by the pattern anchors:

• State class structure (sealed class, data class fields)
• Action/Event naming conventions
• Repository method signatures and return types
• Test structure and assertion patterns

---

Step 3: Architecture Design

Produce an ASCII diagram showing component relationships for the planned work:

┌─────────────────┐
│   Screen        │ ← Compose UI
│  (Composable)   │
└────────┬────────┘
         │ State / Action / Event
┌────────▼────────┐
│   ViewModel     │ ← Business logic orchestration
└────────┬────────┘
         │ Repository calls
┌────────▼────────┐
│   Repository    │ ← Data coordination (sealed class results)
└───┬────┬────┬───┘
    │    │    │
┌───▼───┐ │ ┌─▼──────┐
│Manager│ │ │Manager │ ← Single-responsibility (optional)
└───┬───┘ │ └─┬──────┘
    │     │   │
┌───▼─────▼───▼────┐
│   Data Sources   │ ← Raw data (Result<T>, never throw)
└─┬────┬────┬──────┘
  │    │    │
 Room Retrofit SDK

Adapt the diagram to show the actual components planned. Consult docs/ARCHITECTURE.md for full data layer patterns and conventions.

Design Decisions

Document key architectural decisions in a table:

Decision	Resolution	Rationale
[What needed deciding]	[What was chosen]	[Why]

---

Step 4: File Inventory

Files to Create

File Path	Type	Pattern Reference
[full path]	[ViewModel / Screen / Repository / etc.]	[pattern anchor file]

Include in file inventory:

• ...Navigation.kt files for new screens
• ...Module.kt Hilt module files for new DI bindings
• Paired test files (...Test.kt) for each new class

Files to Modify

File Path	Change Description	Risk Level
[full path]	[what changes]	Low / Medium / High

Risk levels:

• Low: Additive changes (new entries in nav graph, new bindings in Hilt module)
• Medium: Modifying existing logic (adding parameters, new branches)
• High: Changing interfaces, data models, or shared utilities

---

Step 5: Implementation Phases

Break the work into sequential phases. Each phase should be independently testable and committable.

Phase ordering principle: Foundation → SDK/Data → Network → UI (tests accompany each phase)

For each phase:

### Phase N: [Name]

**Goal**: [What this phase accomplishes]

**Files**:
- Create: [list]
- Modify: [list]

**Tasks**:
1. [Specific implementation task]
2. [Specific implementation task]
3. ...

**Verification**:
- [Test command or manual verification step]

**Skills**: [Which workflow skills apply — e.g., `implementing-android-code`, `testing-android-code`]

Phase Guidelines

• Each phase should be small enough to be independently testable and committable
• Tests are written within the same phase as the code they verify (not deferred to a "testing phase")
• UI phases come after their data dependencies are in place
• If a phase has more than 5 tasks, consider splitting it

---

Step 6: Risk & Verification

Risk Assessment

Risk	Likelihood	Impact	Mitigation
[What could go wrong]	Low/Med/High	Low/Med/High	[How to prevent or handle]

Verification Plan

Automated Verification:

• Unit test commands (from build-test-verify skill)
• Lint/detekt commands
• Build verification

Manual Verification:

• [Specific manual test scenarios]
• [Edge cases to manually verify]
• Verify ViewModel state survives process death (test via SavedStateHandle persistence and Don't keep activities developer option)