writing-plans

name	writing-plans
description	Use when you have an approved spec and need to break it into bite-sized vertical-slice tasks with exact files, test code, and commands. Required before /build for non-trivial features.

Writing Plans

Adapted from superpowers/skills/writing-plans. Trimmed for small-team capstone (no subagent handoff; plan files are read by both agent and human teammates).

Write a comprehensive implementation plan assuming you (or future-you, two weeks later) have zero context. Document everything: which files to touch per task, code, tests, commands.

DRY. YAGNI. TDD. Frequent commits.

When to use

• A spec exists from /spec (or skill brainstorming).
• Feature ≥ 3 tasks. Sub-1-task feature → bypass, code directly with TDD.

Output location

Save the plan to: docs/plans/YYYY-MM-DD-<feature-name>.md

Also create tasks/todo-<feature>.md with an actionable checkbox list.

Scope check

Does the spec cover multiple independent subsystems? → suggest breaking it into sub-project plans, each with its own spec → plan. Each plan must produce working, testable software on its own.

File structure mapping

Before defining tasks, map out the files to be created/modified:

• Each file has one clear responsibility. Files that change together → live together. Split by responsibility, not by technical layer.
• Prefer small focused files (< 300 lines) over large files doing many things.
• Existing codebase: follow patterns. Don't unilaterally restructure.

Plan document header

Every plan MUST start with:

# [Feature Name] Implementation Plan

> **For executor:** Follow the TDD cycle (skill `tdd`). Each step has a checkbox `- [ ]` for tracking.

**Goal:** [1 sentence describing what this builds]

**Architecture:** [2-3 sentences on the approach]

**Tech stack:** [key libs/tech]

**Spec:** `docs/specs/<spec-file>.md`

---

Task granularity (bite-sized)

Each step = 1 action ~2-5 minutes:

• "Write failing test" — step
• "Run test, confirm it fails" — step
• "Implement minimal code to pass" — step
• "Run tests, confirm pass" — step
• "Commit" — step

Task structure template

### Task N: [Component name]

**Files:**
- Create: `health_system/lib/features/emergency/data/sos_repository.dart`
- Create: `health_system/test/features/emergency/sos_repository_test.dart`
- Modify: `health_system/lib/features/emergency/emergency.dart` (add export)

**Dependencies:** Task 1, 2

- [ ] **Step 1: Write failing test**

```dart
test('confirmSOS posts to backend with userId + timestamp', () async {
  final dio = MockDio();
  final repo = SosRepository(dio: dio);
  when(() => dio.post(any(), data: any(named: 'data')))
      .thenAnswer((_) async => Response(requestOptions: RequestOptions(path: ''), statusCode: 200, data: {'id': 'sos-1'}));
  final result = await repo.confirmSOS(userId: 'u1');
  expect(result.id, 'sos-1');
  verify(() => dio.post('/api/mobile/sos/confirm', data: {'userId': 'u1'})).called(1);
});

• Step 2: Run test, confirm FAIL

# cwd: d:\DoAn2\VSmartwatch\health_system
flutter test test/features/emergency/sos_repository_test.dart

Expected: FAIL — SosRepository not defined.

• Step 3: Implement minimal

class SosRepository {
  SosRepository({required this.dio});
  final Dio dio;

  Future<SosResult> confirmSOS({required String userId}) async {
    final res = await dio.post(
      '/api/mobile/sos/confirm',
      data: {'userId': userId},
    );
    return SosResult(id: res.data['id']);
  }
}

• Step 4: Run test, confirm PASS

flutter test test/features/emergency/sos_repository_test.dart

Expected: PASS 1/1.

• Step 5: Commit

git add health_system/lib/features/emergency/ health_system/test/features/emergency/
git commit -m "feat(emergency): them SosRepository.confirmSOS"

## No placeholders — plan failure

Don't write any of these. Every step MUST have real content:

- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases" — write the exact code
- "Write tests for the above" — write the actual test code
- "Similar to Task N" — repeat the code; the executor may read out of order
- Steps that describe what without showing how — code blocks are mandatory for code steps
- References to types/functions/methods not defined in any task

## Vertical slice ordering

Order tasks by:

1. **Foundation first** — config, types, shared utilities, DI setup.
2. **Risk-first** — uncertain/complex items early to fail-fast learn.
3. **Dependencies** — respect the dependency graph.
4. **Quick wins** — momentum from small tasks first.

❌ Horizontal (anti-pattern): Task 1: Create all DB schemas Task 2: Create all APIs Task 3: Create all UI

✅ Vertical (correct): Task 1: User can confirm SOS from countdown dialog (UI + repo + backend POST + Postgres insert) Task 2: User can cancel SOS during countdown (UI + repo + backend cancel endpoint) Task 3: Family contact gets FCM notification on SOS (backend trigger + FCM payload + mobile foreground handler)

## Checkpoints

Insert between major phases:

```markdown
---
## Checkpoint: Auth flow complete

**Verify before proceeding:**
- [ ] Login email + Apple + Google work
- [ ] Logout clears cache
- [ ] Auth state persists across restart
- [ ] Test coverage ≥ 70% for the auth feature
- [ ] Manual test: cold start → login → kill app → reopen → still logged in
---

Self-review before committing the plan

After writing the plan, reread with fresh eyes:

1. Spec coverage: skim each spec section / requirement. Is there a task implementing each? List gaps.
2. Placeholder scan: search the plan for the red-flag patterns from "No Placeholders". Fix.
3. Type/name consistency: function named clearLayers() in Task 3 but clearFullLayers() in Task 7 = bug. Check naming consistency throughout.

If you find issues, fix them inline. If you find a spec requirement with no task, add the task.

Execution handoff

Plan written and saved → notify the user:

"Plan saved to docs/plans/<file>.md. I'm ready to start with Task 1. Want me to run, or do you want to review first?"

Once approved → invoke skill tdd + execute task by task. Update tasks/todo-<feature>.md checkboxes after each task.

Remember

• Exact file paths, every time.
• Complete code per step — if a step changes code, show the code.
• Exact commands with expected output.
• DRY, YAGNI, TDD, frequent commits.