@mallardbay/cursor-rules 1.0.10 → 1.0.12

package/.cursor/shared/rules/typescript.mdc

@@ -1,24 +1,27 @@
 ---
-description: Outlines a pragmatic approach to TypeScript—favoring strict type safety where it adds real value in catching bugs and improving developer experience, without unnecessary overhead. Includes file organization, best practices, and consistent use of TypeScript to enforce clarity, maintainability, and confidence in the codebase.
-globs:
-alwaysApply: false
+alwaysApply: true
 ---
+
 # TypeScript Development Standards
 
 ## Type Safety
+
 Enforce comprehensive type safety across the codebase:
 
 ### Strict Type Checking
+
 Be as strictly as possible where it delivers clear value—specifically in preventing bugs and improving the developer experience. The goal is to enforce strong types and catch issues early, without introducing excessive friction or overhead. If a strict setting improves safety, maintainability, or clarity, we’ll use it. If it creates noise or slows down iteration without real benefit, we’ll dial it back. This is about pragmatic strictness, not dogmatism.
 
 ### File Organization
-- Place types at the bottom of files
-- Define PropTypes before component definitions
+
+-   Place types at the bottom of files
+-   Define PropTypes before component definitions
 
 ## Best Practices
-- Use TypeScript for all new code
-- Leverage TypeScript's type system for better code quality
-- Follow React best practices with TypeScript
-- Use proper type definitions for props and state
-- Utilize TypeScript's utility types when appropriate
-- Suggest existing libaries as needed
+
+-   Use TypeScript for all new code
+-   Leverage TypeScript's type system for better code quality
+-   Follow React best practices with TypeScript
+-   Use proper type definitions for props and state
+-   Utilize TypeScript's utility types when appropriate
+-   Suggest existing libaries as needed

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

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

@@ -0,0 +1,267 @@
+---
+name: review-pr
+description: Review a pull request systematically, checking code quality, functionality, security, and adherence to project standards. Use when reviewing PRs, providing code review feedback, or checking someone else's changes.
+version: 1.0.0
+tags:
+  - pr
+  - review
+  - code-quality
+  - workflow
+---
+
+# Review PR
+
+Systematically review a pull request, checking code quality, functionality, security, tests, and adherence to project standards. Provide constructive feedback and approve or request changes.
+
+## When to Use
+
+- User wants to review a pull request
+- User mentions code review, PR review, or checking someone else's changes
+- User provides a PR URL, number, or branch name
+- When asked to review code before merge
+
+## Instructions
+
+### Step 1: Get PR Information
+
+```bash
+# If PR number provided
+gh pr view <pr-number> --json number,title,body,author,headRefName,baseRefName,files,commits
+
+# If PR URL provided, extract number from URL
+# Format: github.com/{owner}/{repo}/pull/{number}
+
+# If branch name provided
+gh pr list --head <branch-name> --json number,title,url
+```
+
+**Key information to extract:**
+- PR number, title, description
+- Author and branch names
+- Changed files and commit history
+- Current review status
+
+### Step 2: Review PR Scope
+
+- [ ] PR size is reasonable (see [code-review.mdc](mdc:.cursor/rules/code-review.mdc) - max 400 lines)
+- [ ] PR description is clear and explains purpose
+- [ ] Related issues/tickets are referenced
+- [ ] Changes align with PR description
+- [ ] No unrelated changes included
+
+### Step 3: Code Quality Review
+
+Reference project standards:
+- [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - DRY, patterns, semantic clarity, cognitive complexity
+- [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) - Structure, naming, reuse
+- [testing.mdc](mdc:.cursor/rules/testing.mdc) - Test requirements
+
+**Check for:**
+
+**Functionality & Logic**
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases are handled
+- [ ] Error handling is comprehensive
+- [ ] Integration with existing code is smooth
+- [ ] No obvious bugs or logic errors
+
+**Code Quality**
+- [ ] Follows existing patterns (see [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc))
+- [ ] Reuses existing logic where possible
+- [ ] Function names are semantic and clear
+- [ ] Cognitive complexity is low
+- [ ] Separation of concerns is maintained
+- [ ] No code duplication (DRY principle)
+
+**Security**
+- [ ] No obvious security vulnerabilities
+- [ ] Input validation and sanitization
+- [ ] Authentication/authorization checks
+- [ ] No sensitive data exposed
+- [ ] Dependencies are up-to-date and secure
+
+**Performance**
+- [ ] No obvious performance bottlenecks
+- [ ] Efficient algorithms and data structures
+- [ ] No unnecessary re-renders/re-computations
+- [ ] Resource cleanup (memory, connections)
+
+**Style & Consistency**
+- [ ] Follows project naming conventions
+- [ ] Consistent with codebase style
+- [ ] No commented-out code or debug statements
+- [ ] Proper formatting
+
+### Step 4: Test Coverage Review
+
+- [ ] New code has tests (see [testing.mdc](mdc:.cursor/rules/testing.mdc))
+- [ ] Tests cover happy path, error cases, edge cases
+- [ ] Test quality is good (clear, focused, maintainable)
+- [ ] No duplicate or redundant tests
+- [ ] Tests follow project patterns
+
+### Step 5: Breaking Changes Analysis
+
+Check for breaking changes that could affect clients:
+
+- [ ] API endpoints, request/response formats, or signatures changed?
+- [ ] Public functions/interfaces modified or removed?
+- [ ] Database schema changes that aren't backward compatible?
+- [ ] Behavioral changes that alter existing functionality?
+- [ ] Configuration options changed or removed?
+
+**If breaking changes found:** Flag as **Blocking** unless properly handled with version bump, deprecation notices, migration guides, and CHANGELOG entries.
+
+### Step 6: Documentation Review
+
+- [ ] Complex logic is documented
+- [ ] Function/class documentation where needed
+- [ ] README updated if needed
+- [ ] Code comments explain "why" not "what"
+
+### Step 7: Architecture & Design
+
+- [ ] Aligns with system architecture
+- [ ] Follows established design patterns
+- [ ] No unnecessary abstractions
+- [ ] Proper separation of concerns
+- [ ] Changes are maintainable
+
+### Step 8: Provide Feedback
+
+**For each issue found:**
+
+1. **Categorize feedback:**
+   - **Blocking** - Must fix before merge (bugs, security, breaking changes)
+   - **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
+   - Explain why it matters
+   - Suggest solutions when possible
+   - Reference project standards
+   - Use positive, respectful language
+
+3. **Post comments on GitHub:**
+
+```bash
+# Post review comment on specific line
+gh pr comment <pr-number> --body "Comment text" --file <file-path> --line <line-number>
+
+# Or use API: POST /repos/{owner}/{repo}/pulls/{pull_number}/comments
+# Body: {"body": "...", "path": "file.ts", "line": 42}
+```
+
+**Comment format:**
+```markdown
+**Issue:** [Brief description]
+
+**Why:** [Why this matters - reference to standards if applicable]
+
+**Suggestion:** [How to fix or improve]
+```
+
+### Step 9: Submit Review
+
+**After reviewing:**
+
+1. **Summarize findings:**
+   - List blocking issues
+   - List important issues
+   - Note positive aspects
+
+2. **Submit review:**
+
+```bash
+# Request changes (blocking issues)
+gh pr review <pr-number> --request-changes --body "Review summary"
+
+# Approve (no blocking issues)
+gh pr review <pr-number> --approve --body "LGTM! Minor suggestions in comments."
+
+# Comment only (suggestions but not blocking)
+gh pr review <pr-number> --comment --body "Review summary"
+```
+
+**API endpoint:** `POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews`
+```json
+{
+  "body": "Review summary",
+  "event": "APPROVE" | "REQUEST_CHANGES" | "COMMENT",
+  "comments": [
+    {
+      "path": "file.ts",
+      "line": 42,
+      "body": "Comment text"
+    }
+  ]
+}
+```
+
+### Step 10: Follow Up
+
+- [ ] Respond to author's questions
+- [ ] Re-review after changes are made
+- [ ] Update review status if issues are resolved
+
+## Review Checklist Summary
+
+**Must Check:**
+- ✅ Functionality works correctly
+- ✅ Security vulnerabilities
+- ✅ Test coverage adequate
+- ✅ Follows project patterns
+- ✅ PR size reasonable
+- ✅ Breaking changes identified and properly handled
+
+**Should Check:**
+- Code quality and maintainability
+- Performance considerations
+- Documentation completeness
+- Error handling
+
+**Nice to Check:**
+- Code style consistency
+- Minor optimizations
+- Documentation improvements
+
+## Output Format
+
+Provide:
+
+1. **Review Summary:**
+   - Overall assessment
+   - Number of blocking/important/suggestion comments
+   - Key findings
+
+2. **Comments Posted:**
+   - List of comments with file:line references
+   - Categorization (blocking/important/suggestion)
+
+3. **Review Decision:**
+   - Approve / Request Changes / Comment
+   - Rationale
+
+4. **Positive Feedback:**
+   - What was done well
+   - Appreciate good patterns or solutions
+
+## Notes
+
+- **Read every line** of changed code
+- **Understand context** before commenting
+- **Be constructive** - focus on code, not person
+- **Ask questions** rather than making demands
+- **Reference standards** from project rules
+- **Test locally** if possible for complex changes
+- **Focus on scope** - don't request out-of-scope changes
+- Use the ask questions tool if PR context is unclear
+
+## References
+
+- [code-review.mdc](mdc:.cursor/rules/code-review.mdc) - PR review standards
+- [general-best-practices.mdc](mdc:.cursor/rules/general-best-practices.mdc) - Code quality standards
+- [testing.mdc](mdc:.cursor/rules/testing.mdc) - Test requirements
+- [code-quality.mdc](mdc:.cursor/rules/code-quality.mdc) - Code structure standards