From c3a996f6280b4f42fe82eaf8bc5e6edc022a8431 Mon Sep 17 00:00:00 2001 From: Sreedhar Busanelli Date: Mon, 13 Apr 2026 11:39:12 -0500 Subject: [PATCH 1/3] Fix: Remove deprecated Option 3 (Notepads) from cursor setup documentation - Remove deprecated Notepads section as per issue #44 - Update Phase-Specific Skills to use on-demand rule files instead - Update Usage Tips to remove notepad references - Maintain existing functionality with Rules Directory and .cursorrules options --- docs/cursor-setup.md | 31 +++++++++++-------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/docs/cursor-setup.md b/docs/cursor-setup.md index bd419e3c..11ac905f 100644 --- a/docs/cursor-setup.md +++ b/docs/cursor-setup.md @@ -29,15 +29,6 @@ echo "\n---\n" >> .cursorrules cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .cursorrules ``` -### Option 3: Notepads - -Cursor's Notepads feature lets you store reusable context. Create a notepad for each skill you use frequently: - -1. Open Cursor → Settings → Notepads -2. Create a new notepad named "swe: Test-Driven Development" -3. Paste the content of `skills/test-driven-development/SKILL.md` -4. Reference it in chat with `@notepad swe: Test-Driven Development` - ## Recommended Configuration ### Essential Skills (Always Load) @@ -48,20 +39,20 @@ Add these to `.cursor/rules/`: 2. `code-review-and-quality.md` — Five-axis review 3. `incremental-implementation.md` — Build in small verifiable slices -### Phase-Specific Skills (Load as Notepads) +### Phase-Specific Skills (Load on Demand) -Create notepads for skills you use contextually: +For phase-specific work, create additional rule files as needed: -- "swe: Spec Development" → `spec-driven-development/SKILL.md` -- "swe: Frontend UI" → `frontend-ui-engineering/SKILL.md` -- "swe: Security" → `security-and-hardening/SKILL.md` -- "swe: Performance" → `performance-optimization/SKILL.md` +- `spec-development.md` -> `spec-driven-development/SKILL.md` +- `frontend-ui.md` -> `frontend-ui-engineering/SKILL.md` +- `security.md` -> `security-and-hardening/SKILL.md` +- `performance.md` -> `performance-optimization/SKILL.md` -Reference them with `@notepad` when working on relevant tasks. +Add these to `.cursor/rules/` when working on relevant tasks, then remove when done to manage context limits. ## Usage Tips -1. **Don't load all skills at once** — Cursor has context limits. Load 2-3 skills as rules and keep others as notepads. -2. **Reference skills explicitly** — Tell Cursor "Follow the test-driven-development rules for this change" to ensure it reads the loaded rules. -3. **Use agents for review** — Copy `agents/code-reviewer.md` content and tell Cursor to "review this diff using this code review framework." -4. **Load references on demand** — When working on performance, reference `@notepad performance-checklist` or paste the checklist content. +1. **Don't load all skills at once** - Cursor has context limits. Load 2-3 essential skills as rules and add phase-specific skills as needed. +2. **Reference skills explicitly** - Tell Cursor "Follow the test-driven-development rules for this change" to ensure it reads the loaded rules. +3. **Use agents for review** - Copy `agents/code-reviewer.md` content and tell Cursor to "review this diff using this code review framework." +4. **Load references on demand** - When working on performance, add `performance.md` to `.cursor/rules/` or paste the checklist content directly. From ad35cbf9cfd1a13ea0908064087717be04205a91 Mon Sep 17 00:00:00 2001 From: Sreedhar Busanelli Date: Mon, 13 Apr 2026 11:44:42 -0500 Subject: [PATCH 2/3] Fix: Add guidance to prevent redundant build verification commands Fixes #47 ## Changes - Add verification guidance to incremental-implementation skill checklist - Add test guidance to test-driven-development skill verification section - Add common rationalizations about redundant verification in both skills - Add red flags for running same command multiple times after success ## Impact This addresses the issue where agents run build verification commands (npx tsc --noEmit, npx vite build, npm test) multiple times consecutively after successful runs, providing clear guidance to trust the first successful verification. --- skills/incremental-implementation/SKILL.md | 4 ++++ skills/test-driven-development/SKILL.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/skills/incremental-implementation/SKILL.md b/skills/incremental-implementation/SKILL.md index a845cbda..0df9a02a 100644 --- a/skills/incremental-implementation/SKILL.md +++ b/skills/incremental-implementation/SKILL.md @@ -208,6 +208,8 @@ After each increment, verify: - [ ] The new functionality works as expected - [ ] The change is committed with a descriptive message +**Note:** Run verification commands once per increment. If a command succeeds with no output or errors, do not repeat it. Redundant verification wastes time and provides no additional value. + ## Common Rationalizations | Rationalization | Reality | @@ -217,6 +219,7 @@ After each increment, verify: | "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. | | "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. | | "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. | +| "Let me run the build command again just to be sure" | If a command succeeded with no errors, running it again provides no additional value. Trust the first successful run. | ## Red Flags @@ -229,6 +232,7 @@ After each increment, verify: - Building abstractions before the third use case demands it - Touching files outside the task scope "while I'm here" - Creating new utility files for one-time operations +- Running the same build/test command multiple times after a successful run ## Verification diff --git a/skills/test-driven-development/SKILL.md b/skills/test-driven-development/SKILL.md index 41b876f1..8e48fac3 100644 --- a/skills/test-driven-development/SKILL.md +++ b/skills/test-driven-development/SKILL.md @@ -356,6 +356,7 @@ For detailed testing patterns, examples, and anti-patterns across frameworks, se | "I tested it manually" | Manual testing doesn't persist. Tomorrow's change might break it with no way to know. | | "The code is self-explanatory" | Tests ARE the specification. They document what the code should do, not what it does. | | "It's just a prototype" | Prototypes become production code. Tests from day one prevent the "test debt" crisis. | +| "Let me run the tests again just to be extra sure" | If tests passed cleanly, running them again provides no additional confidence. Trust the first successful run. | ## Red Flags @@ -366,6 +367,7 @@ For detailed testing patterns, examples, and anti-patterns across frameworks, se - Tests that test framework behavior instead of application behavior - Test names that don't describe the expected behavior - Skipping tests to make the suite pass +- Running the same test command multiple times after a successful run ## Verification @@ -377,3 +379,5 @@ After completing any implementation: - [ ] Test names describe the behavior being verified - [ ] No tests were skipped or disabled - [ ] Coverage hasn't decreased (if tracked) + +**Note:** Run test commands once per implementation cycle. If tests pass cleanly, do not repeat the same test command. Redundant test runs waste time and provide no additional confidence. From b76534301587b9e75ad9cf5fdc1cd6cbe6318da3 Mon Sep 17 00:00:00 2001 From: Addy Osmani Date: Wed, 6 May 2026 18:12:48 -0700 Subject: [PATCH 3/3] docs: tighten redundant-verification wording for consistency Unify the framing across the verification note, rationalization row, and red flag entry in both incremental-implementation and test-driven-development skills. The previous wording mixed "once per increment" (correct) with "no additional value after success" (only true if nothing has changed), which an agent could read as "skip verification entirely after one success." The unified rule: after a successful run, don't repeat the same command unless the code has changed since. --- skills/incremental-implementation/SKILL.md | 6 +++--- skills/test-driven-development/SKILL.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/skills/incremental-implementation/SKILL.md b/skills/incremental-implementation/SKILL.md index 0df9a02a..123e4d24 100644 --- a/skills/incremental-implementation/SKILL.md +++ b/skills/incremental-implementation/SKILL.md @@ -208,7 +208,7 @@ After each increment, verify: - [ ] The new functionality works as expected - [ ] The change is committed with a descriptive message -**Note:** Run verification commands once per increment. If a command succeeds with no output or errors, do not repeat it. Redundant verification wastes time and provides no additional value. +**Note:** Run each verification command after a change that could affect it. After a successful run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no information. ## Common Rationalizations @@ -219,7 +219,7 @@ After each increment, verify: | "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. | | "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. | | "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. | -| "Let me run the build command again just to be sure" | If a command succeeded with no errors, running it again provides no additional value. Trust the first successful run. | +| "Let me run the build command again just to be sure" | After a successful run, repeating the same command adds nothing unless the code has changed since. Run it again after subsequent edits, not as reassurance. | ## Red Flags @@ -232,7 +232,7 @@ After each increment, verify: - Building abstractions before the third use case demands it - Touching files outside the task scope "while I'm here" - Creating new utility files for one-time operations -- Running the same build/test command multiple times after a successful run +- Running the same build/test command twice in a row without any intervening code change ## Verification diff --git a/skills/test-driven-development/SKILL.md b/skills/test-driven-development/SKILL.md index 8e48fac3..c96a67f4 100644 --- a/skills/test-driven-development/SKILL.md +++ b/skills/test-driven-development/SKILL.md @@ -356,7 +356,7 @@ For detailed testing patterns, examples, and anti-patterns across frameworks, se | "I tested it manually" | Manual testing doesn't persist. Tomorrow's change might break it with no way to know. | | "The code is self-explanatory" | Tests ARE the specification. They document what the code should do, not what it does. | | "It's just a prototype" | Prototypes become production code. Tests from day one prevent the "test debt" crisis. | -| "Let me run the tests again just to be extra sure" | If tests passed cleanly, running them again provides no additional confidence. Trust the first successful run. | +| "Let me run the tests again just to be extra sure" | After a clean test run, repeating the same command adds nothing unless the code has changed since. Run again after subsequent edits, not as reassurance. | ## Red Flags @@ -367,7 +367,7 @@ For detailed testing patterns, examples, and anti-patterns across frameworks, se - Tests that test framework behavior instead of application behavior - Test names that don't describe the expected behavior - Skipping tests to make the suite pass -- Running the same test command multiple times after a successful run +- Running the same test command twice in a row without any intervening code change ## Verification @@ -380,4 +380,4 @@ After completing any implementation: - [ ] No tests were skipped or disabled - [ ] Coverage hasn't decreased (if tracked) -**Note:** Run test commands once per implementation cycle. If tests pass cleanly, do not repeat the same test command. Redundant test runs waste time and provide no additional confidence. +**Note:** Run each test command after a change that could affect the result. After a clean run, don't repeat the same command unless the code has changed since — re-running on unchanged code adds no confidence.