docs: plan making skill (#265)

* docs: plan making skill

wip

* docs: round 2

* docs: round 3

* docs: last bit of plan cleanup

Author: williscool

.cursor/skills/plan-making/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: plan-making
+description: Creates development plan documents in docs/dev_todo/ using size-appropriate templates. Use when the user asks to plan a feature, write an RFC, create a dev plan, or when a task is complex enough to warrant a written plan before implementation.
+---
+
+# Plan Making
+
+## CRITICAL: Never Use Cursor Plan Mode
+
+**Do NOT use Cursor's built-in Plan Mode or create `.cursor/plans/*.plan.md` files.** That format is proprietary, throwaway-oriented, and not suitable for long-lived documentation. Plans in this project are learning artifacts kept in `docs/dev_todo/` (active) and `docs/dev_completed/` (done).
+
+## Workflow
+
+### Step 1: Gather Context
+
+Before writing a plan:
+- Read the GitHub issue (if linked)
+- Check `docs/README.md` for related architecture docs
+- Search `docs/dev_completed/` for prior art on similar work
+- Search `docs/dev_todo/` for related active plans
+
+### Step 2: Determine T-Shirt Size
+
+Size based on **conceptual complexity**, not file count (a variable rename across 20 files is still small). Use these signals:
+
+| Signal | S | M | L | XL |
+|--------|---|---|---|-----|
+| Scope boundary | One bug, one pattern, one screen | Single feature, single concern | End-to-end feature slice across layers | Multi-milestone program with child plans |
+| Subsystem fan-out | Single subsystem | 1-2 subsystems | Multiple (UI + storage + background + settings) | Broad (nav + tabs + data + calendar + sync + tests) |
+| Design decisions | None or obvious | 1-2 minor choices | Multiple options with tradeoffs | Decision tables, library evaluations |
+| New architectural components | None | Maybe a helper | Named new class/pattern (e.g. `NotificationContext`, `FilterState`) | New navigation patterns, new packages |
+| Independent deliverable phases | 1 | 2-3 | 4-6 across layers | 7+ grouped into milestones |
+| Risk / rollback story | Trivial | Low | Feature flags, migration concerns | Legacy fallback, data loss prevention, phased rollout |
+
+Pick the size that matches the majority of signals. When borderline, size down — you can always expand later.
+
+### Step 3: Select Template
+
+- **S or M** → Read [template-small.md](template-small.md) and follow it
+- **L or XL** → Read [template-large.md](template-large.md) and follow it
+
+### Step 4: Write the Plan
+
+Output location: `docs/dev_todo/<snake_case_name>.md`
+
+Filename should be descriptive and concise (e.g., `data_sync_improvements.md`, `events_view_lookahead.md`).
+
+### Step 5: README Linking
+
+**Do NOT add the plan to `docs/README.md` at creation time.** The README index is updated only when a feature is complete and the plan moves to `docs/dev_completed/`. During active development the plan lives in `docs/dev_todo/` without a README entry.
+
+## Repo Conventions to Embed
+
+Every plan should respect these project rules:
+
+- **Tests first** — New features require tests before or during implementation
+- **`CNPlusClockInterface`** — Never use `System.currentTimeMillis()` directly; use the clock interface for testable time-dependent code
+- **No broad `Exception` catching** — Always catch specific exception types
+- **Robolectric preferred** — Use Robolectric for logic tests; instrumentation only for real Android APIs (Calendar Provider, notifications, etc.)
+- **Check existing docs** — Reference `docs/architecture/` and `docs/dev_completed/` for patterns and prior decisions
+- **MockK limitations** — `mockkStatic`, `mockkConstructor`, `anyConstructed` fail in instrumentation tests; use dependency injection (see `docs/dev_completed/constructor-mocking-android.md`)
+- **Concise code** — Everything it needs, nothing it doesn't
+
+## Anti-Patterns
+
+- **Over-specifying small plans**: Full code listings and test stubs in an S/M plan waste tokens and will change during implementation anyway
+- **Implementation weeds in S/M plans**: Focus on *what* and *why*, not *how* — the how is discovered during implementation
+- **Missing non-goals in L/XL plans**: Every large plan must explicitly state what is out of scope to prevent scope creep

.cursor/skills/plan-making/template-large.md

@@ -0,0 +1,150 @@
+# Large/XL Plan Template (L-XL)
+
+Use for work with high subsystem fan-out, architecture decisions, new components, or phased rollout.
+
+## Key Principle
+
+Hit the right level of specificity — everything the plan needs, nothing it doesn't. Large plans are long-lived reference documents that future you (and the AI) will re-read during implementation. Invest in design decisions, non-goals, and scope boundaries. But don't pre-specify implementation details that will change during the build — TO BE CLEAR ONLY INCLUDE code snippets, test stubs, layouts, etc. when they're genuinely the clearest way to communicate an approach.
+
+## Template
+
+```markdown
+# Feature: [Title]
+
+**GitHub Issue:** [#NNN](link)
+
+## Background
+
+[Problem statement, how it works today, history of related issues. Include tables of related issues if there's a trail.]
+
+## Goal
+
+[What we're building and what it enables for the user. 2-5 sentences.]
+
+## Non-Goals
+
+[Explicitly state what this plan does NOT cover. This is critical for preventing scope creep. Each item should be a concrete thing someone might reasonably expect to be included but isn't.]
+
+- **[Thing A]** — [why it's out of scope or deferred]
+- **[Thing B]** — [why]
+
+## Key Decisions Summary
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+
+## Current Architecture (if modifying existing systems)
+
+[Tables of existing components, data flow, key insight that unlocks the approach.]
+
+## Design Decisions
+
+[Detailed sections for non-obvious choices. Each with options considered and rationale.]
+
+## Implementation Plan
+
+### Phase 0: [Infrastructure / Setup]
+
+[Substeps (0a, 0b, 0c if needed), each independently verifiable. Describe what changes and why. Only include code snippets or layouts when prose alone can't convey the approach clearly.]
+
+### Phase N: [Name]
+
+[Same pattern. Large plans typically have 4-10 phases grouped into milestones.]
+
+### Milestone Checkpoint
+
+[What milestone N delivers. Validate before proceeding.]
+
+## Files to Modify/Create
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+
+### Modified Files
+
+| File | Changes |
+|------|---------|
+
+## Testing Plan
+
+[Describe what needs to be tested and why, organized by Robolectric vs instrumentation. Name the scenarios to cover — including edge cases and error handling — but don't write full test stubs. The implementation will determine the exact test shape.]
+
+### Unit Tests (Robolectric)
+
+[Key scenarios per component. Edge case and error handling scenarios inline with the component they cover.]
+
+### Instrumentation Tests
+
+[Only for things requiring real Android APIs. Name what must be validated on a real device/emulator.]
+
+## Future Enhancements (if applicable)
+
+[Numbered phases beyond current scope. Brief descriptions only.]
+
+## Notes
+
+[Design principles, behavior clarifications, technical notes that don't fit elsewhere.]
+
+## Related Work
+
+[Links to related docs in docs/architecture/, docs/dev_completed/, docs/dev_todo/.]
+```
+
+## Reference Examples
+
+### events_view_lookahead.md (Size XL)
+
+`docs/dev_todo/events_view_lookahead.md` — the gold standard for a large plan:
+
+- **Key Decisions Summary** table up front for quick reference
+- **UI Vision** with ASCII mockups
+- **Current Architecture** tables showing existing components
+- **Implementation Plan** with 7 phases grouped into 3 milestones
+- **Phase substeps** (0a, 0b, 0c) each independently verifiable
+- **Code snippets** where they clarify non-obvious approaches
+- **Testing Plan** organized by Robolectric vs instrumentation, with edge cases (empty states, error handling, refresh triggers) as named scenarios
+- **Files to Modify/Create** split into New and Modified tables
+- **Future Enhancements** as numbered phases beyond current scope
+- **Notes** with design principles and technical clarifications
+- Total: ~2000 lines
+
+### settings_backup.md (Size L)
+
+`docs/dev_completed/settings_backup.md` — good example of a large (not XL) plan:
+
+- **Research Notes** documenting investigation findings
+- **Current Architecture** of settings storage
+- **4 phases** with clear boundaries
+- **Permission Strategy** as a dedicated section (domain-specific concern)
+- **Open Questions** with recommendations
+- **Appendix** for implementation notes discovered during the build
+- Total: ~360 lines
+
+## Non-Goals Section Guidance
+
+The Non-Goals section is **mandatory** for L/XL plans. Good non-goals are:
+
+- Things adjacent to the feature that someone might assume are included
+- Explicitly deferred work (with reasoning)
+- Scope boundaries that prevent creep
+
+**Example** (from a hypothetical navigation refactor):
+
+```markdown
+## Non-Goals
+
+- **Bidirectional sync** — stays as-is; the delete+reupload approach sidesteps sync issues
+- **Animated tab transitions** — visual polish deferred to a future phase
+- **Deep link support** — existing deep links continue to work; new deep link routes are future work
+- **Tablet layout** — single-column layout only; responsive layouts are a separate effort
+```
+
+## What L/XL Plans MUST Include (that S-M plans skip)
+
+- Non-Goals section
+- Key Decisions Summary table
+- Testing Plan with named scenarios (including edge cases and error handling), split by Robolectric vs instrumentation
+- Files to Modify/Create split into New and Modified
+- Milestone checkpoints between major phases

.cursor/skills/plan-making/template-small.md

@@ -0,0 +1,74 @@
+# Small/Medium Plan Template (S-M)
+
+Use for single-concern work with few or no design decisions.
+
+## Key Principle
+
+Focus on **what** and **why**, not implementation details. Code will change during the build — don't waste tokens specifying it upfront. Brief illustrative snippets are fine when they clarify an approach; full listings are not.
+
+## Template
+
+```markdown
+# [Feature/Fix/Refactor]: [Title]
+
+**GitHub Issue:** [#NNN](link)
+
+## Overview
+
+[1-3 sentences: what we're doing, why, and the key insight or approach]
+
+## Background (if needed)
+
+[Brief context: how it works today, related issues, why the current state is a problem. Skip if the overview is sufficient.]
+
+## Plan
+
+### Phase 1: [Name]
+
+[What changes and why. List files involved. If a design choice exists, state the choice and rationale in 1-2 sentences. No full code listings.]
+
+### Phase 2: [Name]
+
+[Same pattern. Most S/M plans have 1-3 phases.]
+
+## Files Changed Summary
+
+| File | Change |
+|------|--------|
+
+## Testing
+
+[What to test and how (Robolectric vs instrumentation). Describe test scenarios, don't write full test stubs.]
+
+## Open Questions (if any)
+
+[Unresolved decisions. Remove this section if there are none.]
+```
+
+## Example: Data Sync Improvements (Size M)
+
+This is the plan from [#260](https://github.com/williscool/CalendarNotification/issues/260) — an excellent example of the right detail level for a medium plan:
+
+- **Overview** frames the problem and goal in 2 sentences
+- **Background** explains current workflow and why it's broken
+- **Phases** name files and describe changes without full code
+- **Phase 3 (future)** explicitly defers investigation — keeps scope tight
+- Total: ~90 lines
+
+## Example: Search Bar X of Y Count (Size S-M)
+
+`docs/dev_todo/search_bar_x_of_y_count.md` — good example of a small-medium plan:
+
+- **Design Decisions** table for the few choices that exist
+- **Phases** include brief code fragments (5-10 lines) only where they clarify the approach
+- **Testing** names specific test cases without writing full stubs
+- Total: ~160 lines
+
+## What NOT to Include in S-M Plans
+
+- Full Kotlin/XML code listings (save for implementation)
+- Full `@Test` method stubs with Given/When/Then
+- ASCII UI mockups (if UI is simple enough to describe in words)
+- Edge cases section (handle during implementation)
+- Architecture diagrams
+- Future enhancements beyond the immediate scope