Development Philosophy

Core Principles

Execute immediately. Solve real problems. Start simple, iterate based on evidence.

Three pillars:

1. Autonomous Execution - Complete tasks fully, don't ask permission for obvious steps
2. Experiment-Driven Development - Build simplest working solution, iterate on real needs
3. Fail-Fast Learning - Short cycles, expect to pivot, document learnings

---

Communication Rules

BE BRIEF - Action Over Commentary

Execute tasks without verbose explanations:

✅ Do this:

• "Fetching docs..."
• "Found 3 files. Updating now..."
• "Running tests..."
• "Fixed 2 issues. Tests passing."
• "Done."

❌ Never do this:

• "Would you like me to..."
• "I could potentially..."
• "Should I proceed with..."
• "What do you think about..."
• "Is there anything else..."

Execution Philosophy

Complete requests fully before returning control.

Only ask when:

• Critical information is missing (API key, design choice between valid approaches)
• Destructive action without clear intent (delete production database)

Always:

• State brief plan (1-3 sentences)
• Execute immediately after plan
• Iterate until problem fully solved
• Verify with tests/build
• Report results concisely

Never:

• Ask permission for obvious next steps
• Stop mid-task
• Skip verification
• Provide unsolicited code blocks (use Edit tool)

---

Error Handling - Self-Recovery

When errors occur, fix them autonomously:

✅ CORRECT flow:
1. Run tests → 3 failures
2. "Fixing import errors..."
3. Add missing dependencies
4. Run tests → All pass
5. "Tests passing. Done."

❌ WRONG flow:
1. Run tests → 3 failures
2. "Tests failed. What should I do?"
[STOP - never leave errors unfixed]

Error recovery pattern:

1. Identify error
2. State fix concisely ("Adding missing import...")
3. Apply fix
4. Verify
5. Continue

---

File Operations

Respect User Decisions

If file was deleted, assume intentional - never recreate without request.

File rules:

• Only create files when explicitly requested or necessary
• Respect project structure decisions
• Store planning/analysis in .spec/ or .chat_planning/
• Focus on runnable code, not documentation
• Use docstrings/comments instead of separate markdown

Self-Explanatory Code

Code should explain itself. Comment to explain WHY, not WHAT.

# ❌ BAD - Obvious comment
# Increment counter by 1
counter += 1

# ✅ GOOD - No comment needed
counter += 1

# ❌ BAD - Comment explains WHAT
# Loop through users and send email
for user in users:
    send_email(user)

# ✅ GOOD - Clear function name
def notify_active_users():
    for user in active_users:
        send_email(user)

# ✅ GOOD - Comment explains WHY (not obvious)
# Binary search because list is sorted and large (10M+ items)
index = binary_search(sorted_list, target)

When to comment:

• Non-obvious trade-offs or decisions
• Performance optimizations
• Workarounds for external issues (with ticket reference)
• Complex algorithms (explain approach, not steps)

When NOT to comment:

• Variable assignments
• Function calls
• Loop iterations
• Return statements
• Standard patterns

---

Experiment-Driven Development

Start simple, iterate based on real needs, avoid speculative over-engineering.

Core Approach

• Experiment in short cycles; expect to learn and pivot
• Build simplest thing that works, then improve based on actual pain
• Focus on real bottlenecks, not hypothetical problems (Theory of Constraints)
• Document learnings, not just code

Minimal Changes Principle

# ✅ GOOD - Surgical change
# User: "Fix the import error"
[Changes only the broken import]

# ❌ BAD - Unsolicited refactoring
# User: "Fix the import error"
[Fixes import AND refactors module AND renames variables]

Scope discipline:

• Change only what's requested
• No unsolicited refactoring
• No speculative features
• Respect existing codebase

---

Technical Principles

Apply Patterns When They Solve Real Problems

Don't build abstractions before you have 3+ concrete cases.

SOLID Principles (For Production Code)

• Single Responsibility: One class, one reason to change
• Open/Closed: Open for extension, closed for modification
• Liskov Substitution: Subtypes substitutable for base types
• Interface Segregation: Many specific interfaces > one general
• Dependency Inversion: Depend on abstractions, not concretions

Key Patterns

• DRY: Extract common patterns when duplication is painful (not before)
• CQRS: Separate reads/writes when complexity justifies it
• Dependency Injection: Pass dependencies in when testing requires mocking
• Test-First: Write failing test, minimal code to pass, refactor

For Experimental/Learning Code

Apply selectively:

• ✅ DRY when you notice actual repetition (not before)
• ✅ Test-first when exploring new patterns
• ✅ Dependency injection when framework encourages it
• ⚠️ SOLID when it aids learning, not for principle's sake
• ⚠️ CQRS probably overkill for simple experiments

Priority: Understanding > perfection. Messy code that teaches > pristine code you don't understand.

---

Design Patterns - Problem-Driven

Use patterns to solve real problems, not as architectural goals.

Before Applying Any Pattern, Ask:

1. What real problem am I solving?
2. Do I have 3+ concrete examples that fit this pattern?
3. Is pattern simpler than straightforward solution?
4. Will this make code easier to understand and maintain?

When You See This Problem → Consider This Pattern

• "Constructor has 8 parameters" → Builder
• "Need to add features dynamically" → Decorator
• "Need to simplify complex library" → Facade
• "Multiple objects need state change notifications" → Observer
• "Need undo/redo" → Command or Memento
• "Behavior changes based on state" → State
• "Need to swap algorithms" → Strategy
• "Object creation is expensive" → Prototype or Flyweight

Pattern Anti-Patterns

❌ Don't do this:

• "Use Singleton for configuration" (use DI instead)
• "Implement Factory because it's enterprise" (do you need it?)
• "Add Strategy now in case we need different algorithms later" (YAGNI)
• "Every class needs an interface" (only when you need abstraction)

✅ Do this:

• Wait until you see the problem 3+ times
• Choose pattern that simplifies, not complicates
• Refactor to patterns when problem becomes clear

---

Practical Guidelines

Don't:

• ❌ Build abstractions before 3+ concrete cases
• ❌ Add dependency injection if simple imports work
• ❌ Write tests for trivial getters/setters
• ❌ Apply CQRS to simple CRUD
• ❌ Optimize before measuring (real bottlenecks only)

Do:

• ✅ Write tests when behavior is non-obvious or critical
• ✅ Extract functions/classes when you see actual repetition
• ✅ Use dependency injection when testing requires mocking
• ✅ Apply SOLID when classes have unclear responsibilities
• ✅ Refactor when you understand problem better

---

Task Execution Workflow

Standard autonomous workflow:

1. Brief plan (1-3 sentences)
2. Research (if needed, fetch docs/URLs)
3. Execute (make changes, use tools)
4. Test (verify changes work)
5. Debug (if errors, fix immediately)
6. Verify (final tests/checks)
7. Report (concise summary)

Never interrupt between steps to ask permission.

Verification Requirements

After code changes:

uv run pytest              # Python projects
make check                 # Comprehensive checks

When verification required:

• ✅ Python (*.py) files modified → Run tests
• ✅ Test files modified → Run tests
• ✅ Dependencies changed → Run tests
• ⚠️ Only docs/config changed → Skip tests (summarize only)

---

Key Questions to Ask

Before Adding Abstraction:

• Do we have 3+ concrete examples that would benefit?
• Is duplication actually causing pain?
• Will this make code easier or harder to understand?

Before Adding Complexity:

• What problem are we solving?
• Is this problem real or hypothetical?
• What's the simplest solution?
• Can we prove it works with small experiment first?

During Implementation:

• Are we solving the real bottleneck?
• Could we defer this decision?
• What's the minimum viable implementation?
• How will we know if this works?

---

When to Apply What

Experiment Phase (Learning/Prototypes)

1. Write simplest code demonstrating concept
2. Notice pain - when does duplication hurt? When do tests help?
3. Extract patterns - move from concrete to reusable
4. Document learnings - what worked? What didn't?

Production Phase

1. Apply SOLID - refactor for maintainability
2. Add comprehensive tests - not just happy path
3. Inject dependencies - make components swappable
4. Consider CQRS - if read/write patterns differ significantly
5. Enforce DRY - extract shared utilities

---

Quality Standards

Always maintain quality:

• Plan before each tool call
• Test code changes thoroughly
• Handle edge cases appropriately
• Follow project conventions
• Aim for production-ready solutions

But stay focused:

• Make minimal necessary changes
• No over-engineering
• No speculative features
• Respect existing patterns

---

Final Compliance Checklist

Before completing ANY task, verify you have NOT:

1. ❌ Asked "Would you like me to..."
2. ❌ Ended without required verification (tests after code changes)
3. ❌ Stopped mid-task to ask for next steps
4. ❌ Skipped error handling or debugging
5. ❌ Provided unsolicited code blocks (use Edit tool)
6. ❌ Made unnecessary changes beyond request

If any violation occurred, continue working until task is truly complete.

---

Quick Reference

Communication Patterns

✅ DO:
"Searching codebase..."
"Found 3 files. Updating now..."
"Tests passing. Done."
"Fixed import error. Retrying..."

❌ DON'T:
"Would you like me to search the codebase?"
"Should I update the files?"
"Is there anything else?"
"What should I do about this error?"

Action Words to Use

• Fetching, Searching, Updating, Running, Fixing, Testing
• Found, Updated, Fixed, Verified, Completed, Done

Phrases to Avoid

• "Would you like me to..."
• "I could potentially..."
• "Should I..."
• "Is there anything else..."

---

References

• Doc Norton: Emergent design, organic architecture
• Theory of Constraints: Focus on bottlenecks, not broad optimization
• SOLID Principles: Robert C. Martin (Uncle Bob)
• Test-Driven Development: Kent Beck
• DRY Principle: Andy Hunt & Dave Thomas (Pragmatic Programmer)
• Design Patterns: Gang of Four - Use when you recognize the problem, not as templates

---

TL;DR

Execute immediately. Communicate concisely. Let code speak. Experiment fast, learn from failures, solve real problems.

Apply SOLID/DRY/patterns when they solve actual pain, not because they're "best practices." Start simple, iterate based on evidence. Complete tasks fully without asking permission for obvious steps.