Development Guidelines

Philosophy

Core Beliefs

• Incremental progress over big bangs - Small changes that compile and pass tests
• Learning from existing code - Study and plan before implementing
• Pragmatic over dogmatic - Adapt to project reality
• Clear intent over clever code - Be boring and obvious

Simplicity Means

• Single responsibility per function/class
• Avoid premature abstractions
• No clever tricks - choose the boring solution
• If you need to explain it, it's too complex

Process

1. Planning & Staging

Break complex work into 3-5 stages. Document in IMPLEMENTATION_PLAN.md:

## Stage N: [Name]
**Goal**: [Specific deliverable]
**Success Criteria**: [Testable outcomes]
**Tests**: [Specific test cases]
**Status**: [Not Started|In Progress|Complete]

• Update status as you progress
• Remove file when all stages are done

2. Implementation Flow

1. Understand - Study existing patterns in codebase
2. Test - Write test first (red)
3. Implement - Minimal code to pass (green)
4. Refactor - Clean up with tests passing
5. Commit - With clear message linking to plan

3. When Stuck (After 3 Attempts)

CRITICAL: Maximum 3 attempts per issue, then STOP.

1. Document what failed:

   • What you tried
   • Specific error messages
   • Why you think it failed

2. Research alternatives:

   • Find 2-3 similar implementations
   • Note different approaches used

3. Question fundamentals:

   • Is this the right abstraction level?
   • Can this be split into smaller problems?
   • Is there a simpler approach entirely?

4. Try different angle:

   • Different library/framework feature?
   • Different architectural pattern?
   • Remove abstraction instead of adding?

Technical Standards

Architecture Principles

• Composition over inheritance - Use dependency injection
• Interfaces over singletons - Enable testing and flexibility
• Explicit over implicit - Clear data flow and dependencies
• Test-driven when possible - Never disable tests, fix them

Code Quality

• Every commit must:

  • Compile successfully
  • Pass all existing tests
  • Include tests for new functionality
  • Follow project formatting/linting

• Before committing:

  • Run formatters/linters
  • Self-review changes
  • Ensure commit message explains "why"

Error Handling

• Fail fast with descriptive messages
• Include context for debugging
• Handle errors at appropriate level
• Never silently swallow exceptions

Decision Framework

When multiple valid approaches exist, choose based on:

1. Testability - Can I easily test this?
2. Readability - Will someone understand this in 6 months?
3. Consistency - Does this match project patterns?
4. Simplicity - Is this the simplest solution that works?
5. Reversibility - How hard to change later?

Project Integration

Learning the Codebase

• Find 3 similar features/components
• Identify common patterns and conventions
• Use same libraries/utilities when possible
• Follow existing test patterns

Tooling

• Use project's existing build system
• Use project's test framework
• Use project's formatter/linter settings
• Don't introduce new tools without strong justification

Quality Gates

Definition of Done

• [ ] Tests written and passing
• [ ] Code follows project conventions
• [ ] No linter/formatter warnings
• [ ] Commit messages are clear
• [ ] Implementation matches plan
• [ ] No TODOs without issue numbers

Test Guidelines

• Test behavior, not implementation
• One assertion per test when possible
• Clear test names describing scenario
• Use existing test utilities/helpers
• Tests should be deterministic

Important Reminders

NEVER:

• Use --no-verify to bypass commit hooks
• Disable tests instead of fixing them
• Commit code that doesn't compile
• Make assumptions - verify with existing code

ALWAYS:

• Commit working code incrementally
• Update plan documentation as you go
• Learn from existing implementations
• Stop after 3 failed attempts and reassess