arisguimera Writing Mobile Plans
Overview
Write comprehensive implementation plans assuming the engineer has zero context for our codebase. Document everything they need: which files to touch, code, testing, how to verify. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Announce at start: "I'm using the mobile-planning skill to create the implementation plan."
Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md
- (User preferences for plan location override this default)
Numbered Task Lists Are INPUT, Not Substitute
If the user hands you a numbered list of 3+ tasks, that list is raw input — not a finished plan. You MUST still invoke this skill to validate:
- Dependencies: which task must finish before another can start
- File-level conflicts: can tasks be parallelized without agent collisions (e.g. two agents editing the same DI module or build file)
- Scope boundaries: what each task pulls in (a "fix bug X" task may require related tests and touch adjacent code)
- Approval checkpoint: present the dependency graph and wait for explicit user approval before dispatching any agent or writing any code
A user-supplied list describes what. Planning determines how, in what order, and by whom.
Scope Check
If the spec covers multiple independent subsystems, suggest breaking into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
File Structure
Before defining tasks, map out which files will be created or modified. Design units with clear boundaries. Prefer smaller, focused files. In existing codebases, follow established patterns.
Bite-Sized Task Granularity
Each step is one action (2-5 minutes):
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step
Plan Document Header
Every plan MUST start with this header:
# [Feature Name] Implementation Plan
> **For agentic workers:** Use `mobiai-mobile-executing-plans-with-subagents` (recommended) or `mobiai-mobile-executing-plans` to implement this plan task-by-task. Steps use checkbox syntax for tracking.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
**Platform:** [Android / iOS / KMP / Flutter / React Native]
---
Task Structure
### Task N: [Component Name]
**Files:**
- Create: `exact/path/to/file.kt`
- Modify: `exact/path/to/existing.kt:123-145`
- Test: `exact/path/to/test.kt`
- [ ] **Step 1: Write the failing test**
```kotlin
@Test
fun `specific behavior description`() {
val result = function(input)
assertEquals(expected, result)
}
```
- [ ] **Step 2: Run test to verify it fails**
Run: `./gradlew testDebugUnitTest --tests "com.example.MyTest"`
Expected: FAIL with "function not defined"
- [ ] **Step 3: Write minimal implementation**
```kotlin
fun function(input: Type): ReturnType {
return expected
}
```
- [ ] **Step 4: Run test to verify it passes**
Run: `./gradlew testDebugUnitTest --tests "com.example.MyTest"`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add tests/path/test.kt src/path/file.kt
git commit -m "feat: add specific feature"
```
Mobile-Specific Considerations
Include these in the plan when relevant:
| Consideration | Include when |
|---|---|
| Build verification | After every 2-3 tasks: ./gradlew assembleDebug or xcodebuild build |
| DB migrations | Any Room/CoreData schema change — include migration code |
| Permissions | New permission needed — include manifest/plist entry + runtime request |
| ProGuard/R8 rules | New serialization or reflection — include keep rules |
| Multi-platform | KMP/Flutter/RN — separate tasks for shared code vs platform-specific |
| Navigation | New screen — include route registration and navigation call |
| DI registration | New injectable class — include module/component registration |
No Placeholders
Every step must contain the actual content. These are plan failures — never write them:
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (repeat the code)
- Steps that describe what to do without showing how
Remember
- Exact file paths always
- Complete code in every step
- Exact commands with expected output
- DRY, YAGNI, TDD, frequent commits
Self-Review
After writing the complete plan, check:
1. Spec coverage: Skim each requirement. Can you point to a task that implements it? List any gaps.
2. Placeholder scan: Search for red flags from the "No Placeholders" section. Fix them.
3. Type consistency: Do types, method signatures, and property names match across tasks?
If you find issues, fix them inline.
Execution Handoff
After saving the plan, offer execution choice:
"Plan complete and saved to <path>. Two execution options:
1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks
2. Inline Execution - Execute tasks in this session with checkpoints
Which approach?"
If Subagent-Driven chosen: Use mobiai-mobile-executing-plans-with-subagents
If Inline Execution chosen: Use mobiai-mobile-executing-plans