@mallardbay/cursor-rules 1.0.14 → 1.0.15

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

@@ -0,0 +1,163 @@
+---
+description: Core development principles and best practices that always apply—optimized for AI agents to produce clean, maintainable, reviewable code with low cognitive complexity, clear semantics, and incremental changes.
+alwaysApply: true
+---
+
+# General Best Practices
+
+These principles apply to all code changes and should guide every implementation decision.
+
+## Core Principles
+
+### DRY (Don't Repeat Yourself)
+- Extract common logic into reusable functions, utilities, or shared modules
+- Leverage existing patterns and utilities before creating new ones
+- When duplicating code, ask: "Can this be abstracted?"
+- Prefer composition and shared utilities over copy-paste solutions
+
+### Leverage Existing Patterns
+- **Always** search the codebase for similar implementations before creating new code
+- Follow established patterns, conventions, and architectural decisions
+- Use existing utilities, helpers, and shared libraries
+- Match the style and structure of related files
+- When patterns exist, use them consistently—don't invent new approaches without justification
+
+### Incremental Changes
+- **Minimize large changes in a single PR or commit**
+- Break large features into smaller, testable increments
+- Make changes that are easy to review and understand
+- Prefer multiple small PRs over one massive change
+- Each change should be independently testable and reviewable
+- If a change touches many files, consider splitting it into logical phases
+
+### Semantic Clarity
+- Use **semantic, self-documenting names** for functions, variables, and types
+- Function names should clearly describe what they do (e.g., `calculateTotalPrice` not `calc`)
+- Variable names should express intent (e.g., `userAccountBalance` not `bal`)
+- Terminology should be consistent across the codebase
+- Avoid abbreviations unless they're widely understood in the domain
+- Names should make code readable without comments
+
+### Cognitive Complexity
+- **Keep cognitive complexity low**—code should be easy to understand at a glance
+- Prefer early returns and guard clauses over deep nesting
+- Break complex logic into smaller, well-named functions
+- Maximum nesting depth: 3 levels
+- Use intermediate variables to clarify intent
+- Extract complex conditionals into named boolean functions
+- Avoid deeply nested ternaries—use if/else or extract to function
+
+### Separation of Concerns
+- **Files**: Each file should have a single, clear responsibility
+- **Functions**: Each function should do one thing well
+- Separate business logic from presentation, data access, and side effects
+- Keep UI components focused on rendering and user interaction
+- Extract business logic into pure functions or services
+- Avoid god objects or functions that do too much
+
+## Code Quality Standards
+
+### Avoid "AI Slop"
+- **Write code that's easy for humans to review**
+- Avoid generating large amounts of code without understanding context
+- Don't create unnecessary abstractions or over-engineered solutions
+- Remove unused code, imports, and dead branches
+- Clean up commented-out code and debugging statements
+- If an approach doesn't work, **clean up failed attempts** before trying another
+- Keep only relevant, working code—remove experimental code that didn't pan out
+
+### Testing and Linting
+- **Lint and test files related to your changes** before completing work
+- Run linters on modified files and fix issues
+- Run tests for affected modules, not the entire test suite unnecessarily
+- For large changes: **use test sharding**—split tests across multiple runs
+- **Do not run all tests in parallel** when dealing with many changes
+- Tests should be **clear, fast, and minimize setup duplication**
+- Use shared test utilities and fixtures to reduce boilerplate
+- Each test should be independent and runnable in isolation
+
+### Code Organization
+- Group related functionality together
+- Keep related code close (cohesion)
+- Minimize dependencies between modules (loose coupling)
+- Use appropriate data structures for the problem
+- Prefer composition over inheritance
+- Make functions pure when possible (no side effects)
+- Handle edge cases explicitly—don't rely on implicit behavior
+
+### Type Safety and Clarity
+- Use TypeScript types effectively—avoid `any` unless necessary
+- Make types explicit and meaningful
+- Use const assertions and readonly where appropriate
+- Prefer `const` over `let`, avoid `var`
+- Use type guards and discriminated unions for type narrowing
+
+### Performance Considerations
+- Consider performance implications, but **avoid premature optimization**
+- Profile before optimizing—optimize bottlenecks, not everything
+- Use appropriate algorithms and data structures
+- Avoid unnecessary re-renders, re-computations, or API calls
+- Cache expensive computations when appropriate
+
+## AI Agent Workflow
+
+### Before Making Changes
+1. **Create a plan** before making changes directly—outline the approach, identify affected files, and break down the work into steps
+2. **Read existing code** to understand patterns and context
+3. **Search the codebase** for similar implementations
+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
+
+### During Implementation
+1. Make **small, incremental changes**
+2. **Test as you go**—verify each change works before moving on
+3. **Lint frequently**—don't accumulate lint errors
+4. **Follow existing patterns**—don't reinvent the wheel
+5. **Use semantic names**—code should be self-documenting
+6. **Keep functions focused**—one responsibility per function
+7. **Extract common logic**—don't duplicate code
+
+### After Making Changes
+1. **Clean up failed attempts**—remove experimental code
+2. **Remove unused code**—imports, variables, functions
+3. **Run linters** on modified files
+4. **Run relevant tests**—not the entire suite unless necessary
+5. **Verify the change works** end-to-end
+6. **Check for side effects**—ensure changes don't break unrelated code
+
+### When Changes Are Large
+1. **Consider splitting** into multiple smaller PRs
+2. **Use test sharding**—run tests in batches, not all at once
+3. **Review incrementally**—make sure each part works before moving on
+4. **Document the approach**—explain why changes are structured this way
+5. **Check impact** on related systems and files
+
+## Anti-Patterns to Avoid
+
+- ❌ Copy-pasting code instead of extracting to a function
+- ❌ Creating new patterns when existing ones work
+- ❌ Making massive changes in one go
+- ❌ Using vague names like `data`, `temp`, `value`, `thing`
+- ❌ Deeply nested conditionals and loops
+- ❌ Functions that do multiple unrelated things
+- ❌ Leaving commented-out code or debugging statements
+- ❌ Skipping tests or linting "to save time"
+- ❌ Running entire test suite for small changes
+- ❌ Leaving experimental code after failed attempts
+- ❌ Premature optimization without profiling
+- ❌ Using `any` types to avoid type errors
+- ❌ Magic numbers or strings without constants
+
+## Remember
+
+**Code is read far more often than it's written.** Write code that:
+- Is easy to understand
+- Is easy to review
+- Is easy to test
+- Is easy to modify
+- Follows established patterns
+- Has clear semantics
+- Minimizes cognitive load
+
+When in doubt, prefer clarity and simplicity over cleverness.

package/.cursor/shared/skills/address-pr-feedback/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: address-pr-feedback
+description: Address pull request feedback by finding the PR, reviewing comments, creating an implementation plan, and resolving GitHub conversations after fixes are applied. Use when responding to PR reviews, addressing feedback, or resolving review comments.
+version: 1.0.0
+tags:
+  - pr
+  - review
+  - github
+  - workflow
+---
+
+# Address PR Feedback
+
+Find a pull request by branch name, review all feedback, create a plan to address it, assess validity and priority, implement fixes, and resolve GitHub conversations.
+
+## When to Use
+
+- User wants to address PR feedback or review comments
+- User mentions responding to PR reviews
+- User wants to resolve GitHub conversations
+- After receiving feedback on a pull request
+- When preparing to address reviewer comments
+
+## Instructions
+
+### Step 1: Find the Pull Request
+
+```bash
+# Get branch name
+BRANCH=$(git branch --show-current)
+
+# Find PR (prefer GitHub CLI)
+gh pr list --head $BRANCH --json number,title,url
+
+# Or use API: GET /repos/{owner}/{repo}/pulls?head={owner}:{branch-name}&state=open
+```
+
+### Step 2: Check Merge Conflicts & CI Status
+
+**Check conflicts:**
+```bash
+gh pr view <pr-number> --json mergeable,mergeableState
+# mergeable_state: clean = no conflicts, dirty = conflicts exist, behind = needs update
+```
+
+**If conflicts exist:** Resolve before addressing feedback
+```bash
+git fetch origin <base-branch>
+git rebase origin/<base-branch>  # or merge
+# Resolve conflicts, test, then push
+git push origin <branch-name>  # or --force-with-lease if rebased
+```
+
+**Check CI/CD status:**
+```bash
+gh pr checks <pr-number>
+# Or: gh pr view <pr-number> --json statusCheckRollup
+```
+
+**API endpoints:**
+- Conflicts: `GET /repos/{owner}/{repo}/pulls/{pull_number}` → check `mergeable_state`
+- Checks: `GET /repos/{owner}/{repo}/commits/{sha}/check-runs` or `/status`
+
+**If checks failing:** Fix issues, push, wait for re-run. Only resolve conversations when checks pass.
+
+```bash
+# Get all review comments (includes threads)
+gh pr view <pr-number> --json comments,reviews
+
+# API endpoints:
+# GET /repos/{owner}/{repo}/pulls/{pull_number}/comments - Review comments
+# GET /repos/{owner}/{repo}/issues/{pr_number}/comments - General PR comments  
+# GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews - Review summaries (APPROVED, CHANGES_REQUESTED, etc.)
+```
+
+### Step 4: Analyze Feedback
+
+Categorize by:
+- **Type**: Blocking (must fix), Suggestions, Questions, Praise (no action)
+- **Priority**: High (bugs/security), Medium (quality), Low (style)
+- **Category**: Bugs, Code Quality, Tests, Documentation, Performance, Style
+
+Assess validity against [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc). Group related feedback and identify contradictions.
+
+### Step 5: Create Implementation Plan
+
+List all feedback with: comment ID, thread ID, file:line, reviewer, priority, and proposed solution. Organize by file, order by priority, note dependencies.
+
+**Format:**
+```markdown
+### High Priority
+- [ ] Comment #123 (thread:456) - `src/utils.ts:45` - @reviewer
+  Issue: Missing null check → Solution: Add guard clause
+```
+
+### Step 6: Implement Fixes
+
+Work through plan systematically. Reference feedback in commits:
+```bash
+git commit -m "fix: add null check
+
+Addresses review comment #123"
+git push origin <branch-name>
+```
+
+### Step 7: Resolve GitHub Conversations
+
+Reply to comments acknowledging fixes:
+```bash
+gh pr comment <pr-number> --body "Fixed in commit abc123. Thanks!"
+```
+
+**API endpoints:**
+- Reply: `POST /repos/{owner}/{repo}/pulls/{pull_number}/comments` with `{"body":"...", "in_reply_to": <comment_id>}`
+- Resolve thread: `PUT /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/resolved`
+
+Reference commit hash and thank reviewers.
+
+### Authentication
+
+**Preferred: GitHub CLI**
+```bash
+gh auth login  # Handles auth automatically
+```
+
+**Alternative: Personal Access Token**
+- Create PAT with scopes: `repo`, `pull_requests:write`, `issues:write`
+- Set: `export GITHUB_TOKEN=your_token_here`
+- Never commit tokens. Use GitHub Secrets in CI/CD.
+
+### Step 8: Verify and Follow Up
+
+Re-check conflicts and CI status. Verify conversations resolved. Request re-review if needed:
+```bash
+gh pr comment <number> --body "@reviewer Ready for another look! ✅"
+```
+
+**Final checklist:** No conflicts ✅ | Checks passing ✅ | Feedback addressed ✅ | Conversations resolved ✅
+
+## Output Format
+
+Provide: PR status (conflicts & checks), summary of feedback addressed, changes made, conversations resolved, remaining items, next steps.
+
+## Notes
+
+- Be respectful in responses. Reference commits. Explain if not implementing a suggestion.
+- Group related fixes. Test before resolving conversations. Ask questions if feedback is unclear.
+
+## References
+
+- [GitHub REST API - Pull Requests](https://docs.github.com/en/rest/pulls)
+- [GitHub REST API - Pull Request Comments](https://docs.github.com/en/rest/pulls/comments)
+- [GitHub REST API - Checks](https://docs.github.com/en/rest/checks)
+- [GitHub REST API - Statuses](https://docs.github.com/en/rest/commits/statuses)
+- [GitHub CLI Documentation](https://cli.github.com/manual/)
+- [code-review.mdc](mdc:.cursor/rules/code-review.mdc) - PR review standards

package/.cursor/shared/skills/prep-for-pr/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: prep-for-pr
+description: Prepare the current branch for a pull request by checking code quality, completeness, and adherence to best practices. Use when preparing to create a PR, tidying up a branch, or ensuring code is ready for review.
+version: 1.0.0
+tags:
+  - pr
+  - preparation
+  - code-quality
+  - workflow
+---
+
+# Prep for PR
+
+Prepare the current branch for a pull request by systematically checking code quality, completeness, and adherence to best practices. This skill helps ensure your branch is ready before creating a PR.
+
+## When to Use
+
+- Preparing to create a pull request
+- Tidying up a branch before submitting
+- User mentions preparing for PR, getting ready for review, or checking branch quality
+- Before pushing changes for review
+- When you want to ensure code meets quality standards
+
+## Instructions
+
+Systematically check the new work on this branch and fix issues as you find them. Work through the following checklist:
+
+**Important:** This skill references project rules for detailed guidance. Review the relevant rules files for complete standards:
+- [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - Core principles, DRY, patterns, semantic clarity, cognitive complexity, anti-patterns
+- [testing.mdc](mdc:.cursor/rules/testing.mdc) - Test coverage, organization, and quality standards
+- [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) - Code structure, naming conventions, reuse guidelines
+- [code-review.mdc](mdc:.cursor/rules/code-review.mdc) - PR size and review requirements
+
+### Code Quality Checks
+
+**Feature Gaps**
+- [ ] Are all requirements from the ticket/issue addressed?
+- [ ] Are edge cases handled appropriately?
+- [ ] Is error handling comprehensive?
+- [ ] Are user-facing features complete (no TODOs or placeholders)?
+
+**Potential New Bugs**
+- [ ] Review logic for potential race conditions
+- [ ] Check for null/undefined handling
+- [ ] Verify error paths are tested
+- [ ] Look for off-by-one errors or boundary issues
+- [ ] Check for memory leaks or resource cleanup issues
+- [ ] Verify async/await patterns are correct
+- [ ] Check for potential infinite loops or performance issues
+
+**Missing Tests**
+- [ ] Are all new functions/components tested? (See [testing.mdc](mdc:.cursor/rules/testing.mdc))
+- [ ] Are edge cases covered in tests?
+- [ ] Are error cases tested?
+- [ ] Is integration testing appropriate and present?
+- [ ] Do tests follow existing test patterns?
+
+**Duplicated Tests**
+- [ ] Are there redundant test cases?
+- [ ] Can tests be consolidated without losing coverage?
+- [ ] Are test utilities being reused appropriately?
+
+**Anti-Patterns**
+- [ ] Check against project anti-patterns in [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc)
+- [ ] Verify no copy-paste code that should be extracted (DRY principle)
+- [ ] Ensure no commented-out code or debugging statements
+- [ ] Check for code smells (god objects, deep nesting, magic numbers)
+
+**Files Only Imported by Tests**
+- [ ] Identify any files/functions only used in test files
+- [ ] Determine if these should be removed or if they're intentionally test-only utilities
+- [ ] Flag dead code that can be safely removed
+
+**AI Slop That Needs to Be Flagged**
+- [ ] Check against "Avoid AI Slop" section in [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc)
+- [ ] Look for code that doesn't follow project patterns
+- [ ] Identify code that seems generated without understanding context
+- [ ] Check for unused imports or variables
+
+### Best Practices Verification
+
+**All New Code Uses Pre-Existing Patterns**
+- [ ] Code follows established architectural patterns (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - "Leverage Existing Patterns")
+- [ ] File structure matches existing conventions (see [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc))
+- [ ] Naming conventions are consistent (see [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) and [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - "Semantic Clarity")
+- [ ] Code organization follows project standards
+
+**Whenever Possible We Reused Existing Logic**
+- [ ] No duplicate code that could use shared utilities (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - "DRY Principle")
+- [ ] Existing functions/components are leveraged
+- [ ] Shared libraries are used appropriately (see [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) - "Code Reuse")
+
+**New Code is Setup in Way We Can Share/Reuse Later**
+- [ ] Functions are properly abstracted
+- [ ] Code is modular and composable (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - "Separation of Concerns")
+- [ ] Utilities are placed in appropriate shared locations
+- [ ] Components are reusable, not overly specific
+
+**Make Sure Function Names Make Sense Based on Context**
+- [ ] Function names clearly describe what they do (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - "Semantic Clarity")
+- [ ] Names are semantic and self-documenting
+- [ ] Terminology is consistent with codebase
+- [ ] Names match their actual behavior
+
+**New Code is Simple to Understand for Humans**
+- [ ] Code is readable without excessive comments
+- [ ] Complex logic is broken down into smaller functions (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - "Cognitive Complexity")
+- [ ] Cognitive complexity is low (maximum nesting depth: 3 levels)
+- [ ] Code flow is easy to follow
+- [ ] Proper description/documentation where needed
+
+### Preparation Process
+
+1. **Analyze the current branch**
+   - Read through all changed files
+   - Understand the overall change and scope
+   - Identify what was added, modified, or removed
+
+2. **Work through the checklist systematically**
+   - Check each category thoroughly
+   - Fix issues as you find them
+   - Don't just flag—actually improve the code
+
+3. **Make improvements**
+   - Refactor code that doesn't follow patterns
+   - Add missing tests
+   - Remove duplicated code
+   - Fix bugs and edge cases
+   - Clean up AI-generated code that doesn't fit
+   - Improve naming and structure
+
+4. **Verify completeness**
+   - Ensure all requirements are met
+   - Confirm tests are comprehensive
+   - Verify code follows project standards
+   - Check that everything is ready for review
+
+5. **Use the ask questions tool** if you need clarification on:
+   - Requirements or acceptance criteria
+   - Project-specific patterns or conventions
+   - Expected behavior or edge cases
+   - Where to place new code or utilities
+
+## Output Format
+
+After preparing the branch, provide:
+
+1. **Summary**: Overview of what was checked and improved
+2. **Issues Fixed**: List of specific issues that were addressed
+3. **Remaining Items**: Any items that need attention but couldn't be fixed automatically
+4. **Readiness Status**: Whether the branch is ready for PR creation
+
+## Notes
+
+- Actively fix issues, don't just identify them
+- Focus on important issues first (bugs, missing tests, anti-patterns)
+- Reference existing code patterns when making changes
+- Make code improvements that will make the PR easier to review
+- Ensure the branch is in a good state before creating the PR
+- Balance thoroughness with pragmatism—fix what matters most