@mallardbay/cursor-rules 1.0.23 → 1.0.25

package/.cursor/rules/testing.mdc

@@ -59,6 +59,7 @@ Avoid e2e tests for UI. Favor unit tests.
     -   Apollo mocks
     -   Provider mocks
 -   Keep mocks simple and maintainable
+-   **Do not use variable matchers for Apollo mocks**—match exact variables (e.g. avoid `expect.anything()` or `variables: {}`) so tests fail when the component passes incorrect variables to queries or mutations
 
 ### Test Utilities
 

package/.cursor/shared/rules/general-best-practices.mdc

@@ -114,6 +114,11 @@ These principles apply to all code changes and should guide every implementation
 4. **Check git history** to understand why code exists as it does
 5. **Identify related files** that might be affected
 6. **Ask clarifying questions** if requirements are unclear
+7. **Use MCP servers when available**—leverage Model Context Protocol servers for enhanced capabilities
+   - **Context7 MCP**: Use the context7 MCP server when available to retrieve up-to-date documentation and code examples for libraries
+   - If context7 MCP is not available, suggest adding it to improve access to library documentation
+   - **Suggest useful MCP servers**: When appropriate, suggest popular and useful MCP servers that could enhance development workflow based on the task at hand
+   - Consider MCP servers for documentation, testing, debugging, and other development tasks
 
 ### During Implementation
 1. Make **small, incremental changes**

package/.cursor/shared/rules/testing.mdc

@@ -62,6 +62,7 @@ Avoid e2e tests for UI. Favor unit tests.
     -   Apollo mocks
     -   Provider mocks
 -   Keep mocks simple and maintainable
+-   **Do not use variable matchers for Apollo mocks**—match exact variables (e.g. avoid `expect.anything()` or `variables: {}`) so tests fail when the component passes incorrect variables to queries or mutations
 
 ### Test Utilities
 

package/.cursor/shared/skills/commit-and-pr/SKILL.md

@@ -34,12 +34,13 @@ The issue number can be provided in various formats: `123`, `#123`, `issue 123`,
 
 **Important:** When this skill is invoked, check the user's message for a GitHub issue number first. Users can provide the issue number when invoking the skill (e.g., `/commit-and-pr 123` or `/commit-and-pr #123` or "commit and create PR for issue 123"). Extract it from their message before asking for it.
 
-### Step 1: Check Git Status
+### Step 1: Check Git Status and Branch
 
-First, check the current git status to understand what needs to be committed:
+First, check the current git status and branch:
 
 ```bash
 git status
+git branch --show-current
 ```
 
 Identify:
@@ -48,6 +49,39 @@ Identify:
 - Current branch name
 - Whether there are any uncommitted changes
 
+**CRITICAL: Verify Branch Protection**
+
+**Never push directly to protected branches:**
+- `main`
+- `development`
+- `production`
+
+**If currently on a protected branch:**
+1. **Stop immediately** - do not commit or push
+2. Create a new branch with a semantic release prefix:
+   - `feat/` - for new features
+   - `fix/` - for bug fixes
+   - `test/` - for test-related changes
+   - `docs/` - for documentation
+   - `refactor/` - for refactoring
+   - `chore/` - for maintenance tasks
+   - `perf/` - for performance improvements
+   - `style/` - for formatting/style changes
+3. **Example branch names:**
+   - `feat/add-user-authentication`
+   - `fix/resolve-login-bug`
+   - `test/add-component-tests`
+   - `docs/update-api-documentation`
+4. Switch to the new branch:
+   ```bash
+   git checkout -b <semantic-prefix>/<descriptive-name>
+   ```
+5. Then proceed with the commit and PR workflow
+
+**If already on a feature branch:**
+- Verify the branch name follows semantic prefix conventions
+- If it doesn't, consider renaming it before proceeding (optional but recommended)
+
 ### Step 2: Add Untracked Files
 
 Add all untracked files to staging:
@@ -184,6 +218,21 @@ Where:
 
 ### Step 6: Push Branch
 
+**Before pushing, verify branch protection one more time:**
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+PROTECTED_BRANCHES="main development production"
+
+if echo "$PROTECTED_BRANCHES" | grep -q "$CURRENT_BRANCH"; then
+  echo "ERROR: Cannot push to protected branch: $CURRENT_BRANCH"
+  echo "Please create a feature branch with semantic prefix (feat/, fix/, test/, etc.)"
+  exit 1
+fi
+```
+
+**If branch is safe to push:**
+
 Push the current branch to remote:
 ```bash
 git push origin $(git branch --show-current)
@@ -194,6 +243,11 @@ If branch doesn't exist on remote, set upstream:
 git push -u origin $(git branch --show-current)
 ```
 
+**Branch naming reminder:**
+- Use semantic prefixes: `feat/`, `fix/`, `test/`, `docs/`, `refactor/`, `chore/`, `perf/`, `style/`
+- Follow with descriptive name: `feat/add-user-authentication`, `fix/resolve-login-bug`
+- Never push directly to `main`, `development`, or `production`
+
 ### Step 7: Extract PR Information
 
 Gather information needed for PR:
@@ -395,14 +449,17 @@ If PR was just created (from Step 10):
 
 ## Notes
 
+- **CRITICAL: Never push directly to protected branches** (`main`, `development`, `production`)
+- **Always use semantic release prefixes** for branch names (`feat/`, `fix/`, `test/`, `docs/`, `refactor/`, `chore/`, `perf/`, `style/`)
 - This skill assumes conventional commit format (feat, fix, docs, etc.)
 - GitHub issue numbers are plain numbers (e.g., `123`) but should be formatted with `#` prefix in commit messages and PR titles for GitHub linking
 - PR template TODOs should be filled by developer after PR creation
-- Always verify git status before making changes
+- Always verify git status and branch name before making changes
 - Use GitHub CLI (`gh`) for PR creation - it's the most reliable method
 - If commitizen config is non-standard, may need to adapt the commit step
 - Consider running `prep-for-pr` skill before this one to ensure code quality
 - When extracting issue numbers, remove `#` prefix for storage but add it back when using in commits/PRs for GitHub linking
+- If on a protected branch, create a feature branch first before committing
 
 ## Authentication
 

package/.cursor/shared/skills/commit-and-push/SKILL.md

@@ -48,3 +48,4 @@ This is an alias skill that uses the same functionality as `commit-and-pr`. It c
 - This skill provides the same functionality as `commit-and-pr`
 - Use whichever name feels more natural: `/commit-and-pr` or `/commit-and-push`
 - Both skills behave identically
+- **CRITICAL: Never push directly to protected branches** (`main`, `development`, `production`) - always use semantic prefix branches (`feat/`, `fix/`, `test/`, etc.)

package/.cursor/shared/skills/fix-tests/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: fix-tests
+description: Fix failing tests and linting errors to get the build green locally. Prioritize understanding failures before making changes. Fix all failures, even if not caused by our changes. Use when tests are failing, linting errors exist, or the build needs to be fixed.
+version: 1.0.0
+tags:
+  - tests
+  - linting
+  - debugging
+  - test-fixes
+  - quality
+  - workflow
+  - build
+---
+
+# Fix Tests and Linting
+
+Fix failing tests and linting errors to get the build green locally. Prioritize understanding failures before making changes. Fix all failures, even if they weren't caused by our changes. This skill helps maintain code quality and ensures the build passes.
+
+## When to Use
+
+- When tests are failing and need to be fixed
+- When linting errors exist and need to be resolved
+- When the build is failing and needs to be fixed
+- User mentions failing tests, linting errors, or build failures
+- After code changes break existing tests or introduce linting errors
+- When tests need updates due to API or behavior changes
+- **Goal: Get the build green locally**—fix all test and linting failures
+
+## Instructions
+
+**Critical Principle: Prioritize understanding failures over making changes without understanding.** Always analyze and understand the root cause before applying fixes.
+
+### Running Tests with Sharding
+
+**Use test sharding to run tests efficiently:**
+- **Server projects**: Run tests in 10 shards (e.g., `yarn test --shard=1/10`, `yarn test --shard=2/10`, etc.)
+- **Frontend projects**: Run tests in 4 shards (e.g., `yarn test --shard=1/4`, `yarn test --shard=2/4`, etc.)
+- Run all shards to ensure complete test coverage
+- This prevents running all tests in parallel and helps identify failures more efficiently
+
+### Fixing Tests
+
+1. **Identify failing tests**
+   - Run the test suite using appropriate sharding (10 shards for server, 4 for frontend)
+   - Run all shards to get a complete picture of failures
+   - Identify which tests are failing
+   - Note error messages and stack traces
+
+2. **Analyze test failures (CRITICAL: Understand before fixing)**
+   - **Prioritize understanding**: Read error messages carefully, understand what each test is trying to verify
+   - **Investigate root causes**: Don't make changes until you understand why tests are failing
+   - Identify the root cause of failures by examining:
+     - Code changes that broke existing behavior
+     - Test setup or mocking issues
+     - Outdated test expectations
+     - Missing dependencies or configuration
+     - Flaky test conditions
+     - Pre-existing failures (tests that were already broken)
+   - **Fix all failures**: Even if a test failure wasn't caused by our changes, we still need to fix it to get the build green
+
+3. **Apply appropriate fixes**
+   - Fix code if tests revealed actual bugs
+   - Update tests if expectations need to change
+   - Fix test setup, mocks, or fixtures
+   - Update test utilities or helpers
+   - Address timing or async issues
+   - Fix pre-existing failures—don't skip tests that were already broken
+
+4. **Verify fixes**
+   - Run tests again using sharding to confirm fixes work
+   - Run all shards to ensure no new failures were introduced
+   - Verify test coverage is maintained
+
+5. **Follow testing standards**
+   - Adhere to project testing standards (see [testing.mdc](mdc:.cursor/rules/testing.mdc))
+   - Maintain test quality and clarity
+   - Keep tests focused and atomic
+   - Use appropriate test utilities and patterns
+
+### Fixing Linting Errors
+
+1. **Run linting**
+   - Use `yarn lint:quiet:slow` to identify all linting errors (as specified in [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc))
+   - This provides deeper checks and identifies all issues
+
+2. **Analyze linting errors (CRITICAL: Understand before fixing)**
+   - **Prioritize understanding**: Read each linting error carefully
+   - **Investigate root causes**: Understand why each error exists before fixing
+   - **Never disable eslint rules** to make errors go away—fix the underlying issues instead
+   - Identify if errors are due to:
+     - Code quality issues that need fixing
+     - Missing dependencies or configuration
+     - Pre-existing errors (linting issues that were already present)
+   - **Fix all errors**: Even if a linting error wasn't caused by our changes, we still need to fix it to get the build green
+
+3. **Apply appropriate fixes**
+   - Fix code quality issues properly
+   - Add missing dependencies or configuration
+   - Refactor code to address linting concerns
+   - Fix pre-existing errors—don't skip linting issues that were already present
+   - **Never add `eslint-disable` comments** unless there's a legitimate, documented reason
+
+4. **Verify fixes**
+   - Run `yarn lint:quiet:slow` again to confirm all errors are resolved
+   - Ensure no new linting errors were introduced
+
+### Final Verification
+
+- Run all test shards to ensure all tests pass
+- Run `yarn lint:quiet:slow` to ensure all linting errors are resolved
+- **Goal achieved**: Build is green locally with all tests passing and no linting errors
+
+## Notes
+
+- **Always understand failures before fixing**—prioritize understanding over quick fixes
+- **Fix all failures**—even if they weren't caused by our changes, we need to fix them to get the build green
+- Focus on fixing root causes, not symptoms
+- Use test sharding (10 for server, 4 for frontend) to run tests efficiently
+- Use `yarn lint:quiet:slow` for comprehensive linting checks
+- Never disable eslint rules—fix the underlying issues instead
+- Ensure tests accurately validate expected behavior
+- Maintain or improve test coverage
+- Follow existing test patterns and conventions
+- Keep tests clear, fast, and maintainable
+- **Goal: Get the build green locally**—all tests passing, no linting errors

package/.cursor/shared/skills/review-pr/SKILL.md

@@ -136,6 +136,7 @@ Check for breaking changes that could affect clients:
    - **Important** - Should fix (code quality, maintainability)
    - **Suggestion** - Nice to have (style, minor improvements)
    - **Question** - Need clarification
+   
 
 2. **Write constructive comments:**
    - Be specific about the issue

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mallardbay/cursor-rules",
-    "version": "1.0.23",
+    "version": "1.0.25",
     "description": "Mallard Bay shared cursor rules",
     "main": "bin/setup-cursor.sh",
     "repository": "git@github.com:mallardbay/cursor-rules.git",