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

---

alwaysApply: false
---

# 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?"**

## 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

---

**See also**: `.cursor/rules/development/dependency_management.mdc` for
  detailed dependency management practices.

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

## Model Implementation Checklist

### Before Development Work

- [ ] **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

### During Development

- [ ] **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

### After Development

- [ ] **Code Path Validation**: Verify execution paths are correct
- [ ] **Evidence Documentation**: Document all code citations and evidence
- [ ] **Assumption Review**: Confirm all assumptions are documented
- [ ] **Environment Impact**: Assess how changes affect team member setups