crowd-funder-for-time-pwa/.cursor/rules/software_development.mdc

# Software Development Ruleset

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Core development guidelines

## Purpose

Specialized guidelines for software development tasks including code review,
debugging, architecture decisions, and testing.

## Core Principles

### 1. Evidence-First Development

- **Code Citations Required**: Always cite specific file:line references when
  making claims
- **Execution Path Tracing**: Trace actual code execution before proposing
  architectural changes
- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based"

### 2. Code Review Standards

- **Trace Before Proposing**: Always trace execution paths before suggesting
  changes
- **Evidence Over Inference**: Prefer code citations over logical deductions
- **Scope Validation**: Confirm the actual scope of problems before proposing
  solutions

### 3. Problem-Solution Validation

- **Problem Scope**: Does the solution address the actual problem?
- **Evidence Alignment**: Does the solution match the evidence?
- **Complexity Justification**: Is added complexity justified by real needs?
- **Alternative Analysis**: What simpler solutions were considered?

### 4. Dependency Management & Environment Validation

- **Pre-build Validation**: Always validate critical dependencies before executing
  build scripts
- **Environment Consistency**: Ensure team members have identical development
  environments
- **Dependency Verification**: Check that required packages are installed and
  accessible
- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues

## Required Workflows

### Before Proposing Changes

- [ ] **Code Path Tracing**: Map execution flow from entry to exit
- [ ] **Evidence Collection**: Gather specific code citations and logs
- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred
- [ ] **Scope Validation**: Confirm the actual extent of the problem
- [ ] **Dependency Validation**: Verify all required dependencies are available
  and accessible

### During Solution Design

- [ ] **Evidence Alignment**: Ensure solution addresses proven problems
- [ ] **Complexity Assessment**: Justify any added complexity
- [ ] **Alternative Evaluation**: Consider simpler approaches first
- [ ] **Impact Analysis**: Assess effects on existing systems
- [ ] **Environment Impact**: Assess how changes affect team member setups

## Software-Specific Competence Hooks

### Evidence Validation

- **"What code path proves this claim?"**
- **"How does data actually flow through the system?"**
- **"What am I assuming vs. what can I prove?"**

### Code Tracing

- **"What's the execution path from user action to system response?"**
- **"Which components actually interact in this scenario?"**
- **"Where does the data originate and where does it end up?"**

### Architecture Decisions

- **"What evidence shows this change is necessary?"**
- **"What simpler solution could achieve the same goal?"**
- **"How does this change affect the existing system architecture?"**

### Dependency & Environment Management

- **"What dependencies does this feature require and are they properly
  declared?"**
- **"How will this change affect team member development environments?"**
- **"What validation can we add to catch dependency issues early?"**

## Dependency Management Best Practices

### Pre-build Validation

- **Check Critical Dependencies**: Validate essential tools before executing build
  scripts
- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to
  avoid PATH issues
- **Environment Consistency**: Ensure all team members have identical dependency
  versions

### Common Pitfalls

- **Missing npm install**: Team members cloning without running `npm install`
- **PATH Issues**: Direct command execution vs. npm script execution differences
- **Version Mismatches**: Different Node.js/npm versions across team members

### Validation Strategies

- **Dependency Check Scripts**: Implement pre-build validation for critical
  dependencies
- **Environment Requirements**: Document and enforce minimum Node.js/npm versions
- **Onboarding Checklist**: Standardize team member setup procedures

### Error Messages and Guidance

- **Specific Error Context**: Provide clear guidance when dependency issues occur
- **Actionable Solutions**: Direct users to specific commands (`npm install`,
  `npm run check:dependencies`)
- **Environment Diagnostics**: Implement comprehensive environment validation
  tools

### Build Script Enhancements

- **Early Validation**: Check dependencies before starting build processes
- **Graceful Degradation**: Continue builds when possible but warn about issues
- **Helpful Tips**: Remind users about dependency management best practices

## Integration with Other Rulesets

### With base_context.mdc

- Inherits generic competence principles
- Adds software-specific evidence requirements
- Maintains collaboration and learning focus

### With research_diagnostic.mdc

- Enhances investigation with code path tracing
- Adds evidence validation to diagnostic workflow
- Strengthens problem identification accuracy

## Usage Guidelines

### When to Use This Ruleset

- Code reviews and architectural decisions
- Bug investigation and debugging
- Performance optimization
- Feature implementation planning
- Testing strategy development

### When to Combine with Others

- **base_context + software_development**: General development tasks
- **research_diagnostic + software_development**: Technical investigations
- **All three**: Complex architectural decisions or major refactoring

## Self-Check (model, before responding)

- [ ] Code path traced and documented
- [ ] Evidence cited with specific file:line references
- [ ] Assumptions clearly flagged as proven vs. inferred
- [ ] Solution complexity justified by evidence
- [ ] Simpler alternatives considered and documented
- [ ] Impact on existing systems assessed
- [ ] Dependencies validated and accessible
- [ ] Environment impact assessed for team members
- [ ] Pre-build validation implemented where appropriate

<<<<<<< HEAD
## Additional Core Principles

### 4. Dependency Management & Environment Validation
- **Pre-build Validation**: Always validate critical dependencies before executing build scripts
- **Environment Consistency**: Ensure team members have identical development environments
- **Dependency Verification**: Check that required packages are installed and accessible
- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues

## Additional Required Workflows

### Dependency Validation (Before Proposing Changes)
- [ ] **Dependency Validation**: Verify all required dependencies are available and accessible

### Environment Impact Assessment (During Solution Design)
- [ ] **Environment Impact**: Assess how changes affect team member setups

## Additional Competence Hooks

### Dependency & Environment Management
- **"What dependencies does this feature require and are they properly declared?"**
- **"How will this change affect team member development environments?"**
- **"What validation can we add to catch dependency issues early?"**

## Dependency Management Best Practices

### Pre-build Validation
- **Check Critical Dependencies**: Validate essential tools before executing build scripts
- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to avoid PATH issues
- **Environment Consistency**: Ensure all team members have identical dependency versions

### Common Pitfalls
- **Missing npm install**: Team members cloning without running `npm install`
- **PATH Issues**: Direct command execution vs. npm script execution differences
- **Version Mismatches**: Different Node.js/npm versions across team members

### Validation Strategies
- **Dependency Check Scripts**: Implement pre-build validation for critical dependencies
- **Environment Requirements**: Document and enforce minimum Node.js/npm versions
- **Onboarding Checklist**: Standardize team member setup procedures

### Error Messages and Guidance
- **Specific Error Context**: Provide clear guidance when dependency issues occur
- **Actionable Solutions**: Direct users to specific commands (`npm install`, `npm run check:dependencies`)
- **Environment Diagnostics**: Implement comprehensive environment validation tools

### Build Script Enhancements
- **Early Validation**: Check dependencies before starting build processes
- **Graceful Degradation**: Continue builds when possible but warn about issues
- **Helpful Tips**: Remind users about dependency management best practices

- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely
- **Document Type Decisions**: Explain complex type structures and their purpose
=======
---

**Status**: Active development guidelines
**Priority**: High
**Estimated Effort**: Ongoing
**Dependencies**: base_context.mdc, research_diagnostic.mdc
**Stakeholders**: Development team
>>>>>>> master