diff --git a/.cursor/skills/plan-making/SKILL.md b/.cursor/skills/plan-making/SKILL.md new file mode 100644 index 00000000..064eb232 --- /dev/null +++ b/.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/.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 diff --git a/.cursor/skills/plan-making/template-large.md b/.cursor/skills/plan-making/template-large.md new file mode 100644 index 00000000..3e12796d --- /dev/null +++ b/.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 diff --git a/.cursor/skills/plan-making/template-small.md b/.cursor/skills/plan-making/template-small.md new file mode 100644 index 00000000..76054bd6 --- /dev/null +++ b/.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