From 9cc3d587450d9607b6ba0a18d8463f4602f2f3fb Mon Sep 17 00:00:00 2001 From: William Harris Date: Mon, 6 Apr 2026 19:45:50 +0000 Subject: [PATCH 1/4] docs: plan making skill wip --- .cursor/skills/plan-making/SKILL.md | 68 ++++++++ .cursor/skills/plan-making/template-large.md | 157 +++++++++++++++++++ .cursor/skills/plan-making/template-small.md | 74 +++++++++ 3 files changed, 299 insertions(+) create mode 100644 .cursor/skills/plan-making/SKILL.md create mode 100644 .cursor/skills/plan-making/template-large.md create mode 100644 .cursor/skills/plan-making/template-small.md diff --git a/.cursor/skills/plan-making/SKILL.md b/.cursor/skills/plan-making/SKILL.md new file mode 100644 index 00000000..9687dd09 --- /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 + +Ask these questions to size the work: + +| Question | S | M | L | XL | +|----------|---|---|---|-----| +| Files changed | 1-3 | 3-8 | 8-20 | 20+ | +| Architecture decisions needed? | No | Minor | Yes | Major | +| New components/packages? | No | Maybe 1 | Yes | Multiple | +| Milestones needed? | No | No | Probably | Yes | +| Phased rollout / feature flags? | No | No | Maybe | Yes | + +Pick the size that matches the majority of answers. 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 reflect 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 +- **Under-specifying large plans**: Skipping architecture decisions, non-goals, or edge cases in L/XL plans leads to scope creep and rework +- **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..4150b6bd --- /dev/null +++ b/.cursor/skills/plan-making/template-large.md @@ -0,0 +1,157 @@ +# Large/XL Plan Template (L-XL) + +Use for work touching 8+ files, requiring architecture decisions, new components, or phased rollout. + +## Key Principle + +Go deep. Large plans are long-lived reference documents. Future you (and the AI) will re-read them during implementation. Invest in thorough design decisions, non-goals, edge cases, and test stubs now to avoid rework and scope creep later. + +## 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. Include code snippets, XML layouts, etc.] + +### Phase N: [Name] + +[Same pattern. Large plans typically have 4-10 phases grouped into milestones.] + +### Milestone Checkpoint + +[What milestone N delivers. Validate before proceeding.] + +## Edge Cases & Error Handling + +[Dedicated section for: empty states, null returns, permission denials, migration paths, graceful degradation.] + +## Files to Modify/Create + +### New Files + +| File | Purpose | +|------|---------| + +### Modified Files + +| File | Changes | +|------|---------| + +## Testing Plan + +[Organized by Robolectric vs instrumentation. Full test stubs with @Test methods and Given/When/Then comments. Group by test class.] + +### Unit Tests (Robolectric) + +[Test class per component. Full method signatures with scenario comments.] + +### Instrumentation Tests + +[Only for things requiring real Android APIs.] + +## 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 +- **Full code snippets** for Kotlin and XML +- **Edge Cases** section with empty states, error handling, refresh triggers +- **Testing Plan** with full `@Test` stubs organized by Robolectric vs instrumentation +- **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 +- Full code snippets in implementation phases +- Edge Cases & Error Handling section +- Full `@Test` method stubs in Testing Plan +- 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..c53a0ec1 --- /dev/null +++ b/.cursor/skills/plan-making/template-small.md @@ -0,0 +1,74 @@ +# Small/Medium Plan Template (S-M) + +Use for work touching 1-8 files with no major architecture 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 From 40fe0ff6696107e2ea2254c8087115b308d30f36 Mon Sep 17 00:00:00 2001 From: William Harris Date: Mon, 6 Apr 2026 19:57:05 +0000 Subject: [PATCH 2/4] docs: round 2 --- .cursor/skills/plan-making/SKILL.md | 22 ++++++++++---------- .cursor/skills/plan-making/template-large.md | 16 +++++--------- 2 files changed, 16 insertions(+), 22 deletions(-) diff --git a/.cursor/skills/plan-making/SKILL.md b/.cursor/skills/plan-making/SKILL.md index 9687dd09..064eb232 100644 --- a/.cursor/skills/plan-making/SKILL.md +++ b/.cursor/skills/plan-making/SKILL.md @@ -21,17 +21,18 @@ Before writing a plan: ### Step 2: Determine T-Shirt Size -Ask these questions to size the work: +Size based on **conceptual complexity**, not file count (a variable rename across 20 files is still small). Use these signals: -| Question | S | M | L | XL | -|----------|---|---|---|-----| -| Files changed | 1-3 | 3-8 | 8-20 | 20+ | -| Architecture decisions needed? | No | Minor | Yes | Major | -| New components/packages? | No | Maybe 1 | Yes | Multiple | -| Milestones needed? | No | No | Probably | Yes | -| Phased rollout / feature flags? | No | No | Maybe | Yes | +| 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 answers. When borderline, size down — you can always expand later. +Pick the size that matches the majority of signals. When borderline, size down — you can always expand later. ### Step 3: Select Template @@ -50,7 +51,7 @@ Filename should be descriptive and concise (e.g., `data_sync_improvements.md`, ` ## Repo Conventions to Embed -Every plan should reflect these project rules: +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 @@ -63,6 +64,5 @@ Every plan should reflect these project rules: ## 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 -- **Under-specifying large plans**: Skipping architecture decisions, non-goals, or edge cases in L/XL plans leads to scope creep and rework - **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 index 4150b6bd..80afdfd3 100644 --- a/.cursor/skills/plan-making/template-large.md +++ b/.cursor/skills/plan-making/template-large.md @@ -1,6 +1,6 @@ # Large/XL Plan Template (L-XL) -Use for work touching 8+ files, requiring architecture decisions, new components, or phased rollout. +Use for work with high subsystem fan-out, architecture decisions, new components, or phased rollout. ## Key Principle @@ -55,10 +55,6 @@ Go deep. Large plans are long-lived reference documents. Future you (and the AI) [What milestone N delivers. Validate before proceeding.] -## Edge Cases & Error Handling - -[Dedicated section for: empty states, null returns, permission denials, migration paths, graceful degradation.] - ## Files to Modify/Create ### New Files @@ -73,11 +69,11 @@ Go deep. Large plans are long-lived reference documents. Future you (and the AI) ## Testing Plan -[Organized by Robolectric vs instrumentation. Full test stubs with @Test methods and Given/When/Then comments. Group by test class.] +[Organized by Robolectric vs instrumentation. Full test stubs with @Test methods and Given/When/Then comments. Group by test class. Edge cases and error handling scenarios (empty states, null returns, permission denials, graceful degradation) belong here as test cases, not as a separate section.] ### Unit Tests (Robolectric) -[Test class per component. Full method signatures with scenario comments.] +[Test class per component. Full method signatures with scenario comments. Include edge case and error handling tests inline with the component they cover.] ### Instrumentation Tests @@ -108,8 +104,7 @@ Go deep. Large plans are long-lived reference documents. Future you (and the AI) - **Implementation Plan** with 7 phases grouped into 3 milestones - **Phase substeps** (0a, 0b, 0c) each independently verifiable - **Full code snippets** for Kotlin and XML -- **Edge Cases** section with empty states, error handling, refresh triggers -- **Testing Plan** with full `@Test` stubs organized by Robolectric vs instrumentation +- **Testing Plan** with full `@Test` stubs organized by Robolectric vs instrumentation, with edge cases (empty states, error handling, refresh triggers) as test 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 @@ -151,7 +146,6 @@ The Non-Goals section is **mandatory** for L/XL plans. Good non-goals are: - Non-Goals section - Key Decisions Summary table - Full code snippets in implementation phases -- Edge Cases & Error Handling section -- Full `@Test` method stubs in Testing Plan +- Full `@Test` method stubs in Testing Plan (including edge case and error handling scenarios) - Files to Modify/Create split into New and Modified - Milestone checkpoints between major phases From d2b6435b52f23695dfe046969fe75f317b586bbe Mon Sep 17 00:00:00 2001 From: William Harris Date: Mon, 6 Apr 2026 20:07:34 +0000 Subject: [PATCH 3/4] docs: round 3 --- .cursor/skills/plan-making/template-large.md | 17 ++++++++--------- .cursor/skills/plan-making/template-small.md | 2 +- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/.cursor/skills/plan-making/template-large.md b/.cursor/skills/plan-making/template-large.md index 80afdfd3..90f4020b 100644 --- a/.cursor/skills/plan-making/template-large.md +++ b/.cursor/skills/plan-making/template-large.md @@ -4,7 +4,7 @@ Use for work with high subsystem fan-out, architecture decisions, new components ## Key Principle -Go deep. Large plans are long-lived reference documents. Future you (and the AI) will re-read them during implementation. Invest in thorough design decisions, non-goals, edge cases, and test stubs now to avoid rework and scope creep later. +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 — code snippets, test stubs, and layouts only when they're genuinely the clearest way to communicate an approach. ## Template @@ -45,7 +45,7 @@ Go deep. Large plans are long-lived reference documents. Future you (and the AI) ### Phase 0: [Infrastructure / Setup] -[Substeps (0a, 0b, 0c if needed), each independently verifiable. Include code snippets, XML layouts, etc.] +[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] @@ -69,15 +69,15 @@ Go deep. Large plans are long-lived reference documents. Future you (and the AI) ## Testing Plan -[Organized by Robolectric vs instrumentation. Full test stubs with @Test methods and Given/When/Then comments. Group by test class. Edge cases and error handling scenarios (empty states, null returns, permission denials, graceful degradation) belong here as test cases, not as a separate section.] +[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) -[Test class per component. Full method signatures with scenario comments. Include edge case and error handling tests inline with the component they cover.] +[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.] +[Only for things requiring real Android APIs. Name what must be validated on a real device/emulator.] ## Future Enhancements (if applicable) @@ -103,8 +103,8 @@ Go deep. Large plans are long-lived reference documents. Future you (and the AI) - **Current Architecture** tables showing existing components - **Implementation Plan** with 7 phases grouped into 3 milestones - **Phase substeps** (0a, 0b, 0c) each independently verifiable -- **Full code snippets** for Kotlin and XML -- **Testing Plan** with full `@Test` stubs organized by Robolectric vs instrumentation, with edge cases (empty states, error handling, refresh triggers) as test scenarios +- **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 @@ -145,7 +145,6 @@ The Non-Goals section is **mandatory** for L/XL plans. Good non-goals are: - Non-Goals section - Key Decisions Summary table -- Full code snippets in implementation phases -- Full `@Test` method stubs in Testing Plan (including edge case and error handling scenarios) +- 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 index c53a0ec1..76054bd6 100644 --- a/.cursor/skills/plan-making/template-small.md +++ b/.cursor/skills/plan-making/template-small.md @@ -1,6 +1,6 @@ # Small/Medium Plan Template (S-M) -Use for work touching 1-8 files with no major architecture decisions. +Use for single-concern work with few or no design decisions. ## Key Principle From e3be305ef99c72c5d6898921b3d9c0ecf9a6096d Mon Sep 17 00:00:00 2001 From: William Harris Date: Mon, 6 Apr 2026 20:10:58 +0000 Subject: [PATCH 4/4] docs: last bit of plan cleanup --- .cursor/skills/plan-making/template-large.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.cursor/skills/plan-making/template-large.md b/.cursor/skills/plan-making/template-large.md index 90f4020b..3e12796d 100644 --- a/.cursor/skills/plan-making/template-large.md +++ b/.cursor/skills/plan-making/template-large.md @@ -4,7 +4,7 @@ Use for work with high subsystem fan-out, architecture decisions, new components ## 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 — code snippets, test stubs, and layouts only when they're genuinely the clearest way to communicate an approach. +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