# Coding Playbook

Operational standards for coding and engineering tasks. Loaded automatically when the agent detects a coding-related task.

---

## Architecture Principles (Simple Made Easy)

### Core Concept
- **Simple** = un-braided, single responsibility, one purpose
- **Complex** = intertwined, multiple concerns braided together
- **Easy** does not equal Simple (familiarity is subjective, simplicity is objective)

### Rules
1. **Never complect** -- don't intertwine disparate concerns
2. **Compose, don't complect** -- assemble independent components
3. **Single responsibility** -- each tool/function does ONE thing well
4. **Values over state** -- prefer immutability where possible
5. **Evaluate by artifact** -- judge constructs by the systems they produce, not ease of use

### Avoid Complexity From
- State (complects value and time)
- Objects (complect state, identity, value)
- Inheritance (complects types)
- Conditionals scattered across codebase
- Methods that do multiple things

---

## Engineering Philosophy

### Speed Over Perfection
- Build MVP with just enough features to demonstrate value
- Work by iteration, nothing is definitive
- Short build-measure-learn cycles

### Build-Measure-Learn
1. **BUILD**: Minimal feature (2-4 hrs max)
2. **MEASURE**: Deploy immediately, collect feedback
3. **LEARN**: Analyze, iterate
4. **REPEAT**

### Start Simple
- Monolith first -- split only when 10+ devs
- Boring proven tech over exciting new frameworks
- Manual processes OK before automation
- Find simple engineering solutions -- do NOT simplify user experience or specs when the specs are nuanced and require their specs to be met

---

## Code Practices

### Do
- Every line of code has clear purpose
- Fail fast with explicit error messages
- Delete unused code ruthlessly
- Document WHY, not WHAT
- Test critical paths (payment, auth, core features)
- Always fail explicitly in a clear and concise way back to the user

### Don't
- Premature optimization
- Over-engineering for hypothetical scale
- 100% test coverage
- Technology chasing without clear user value
- Silent failures or generic fallbacks -- ALWAYS surface explicit error messages to users. Never catch exceptions and continue silently. If something fails, the user must know exactly what and why.
- Use emojis on frontend (LLMs tend to overuse emojis in frontend displays)
- Mark items in PRDs as complete until a user has actually verified the completion of a feature. Automated test passes can be marked complete, but not full features without manual user testing.

### Error Handling
```python
# BAD
except:
    return "Error occurred"

# GOOD
except PaymentError as e:
    return f"Payment failed: {e.user_message}. Try another card."
```

---

## Decision Framework

1. **Will users notice?** No -> defer it
2. **Can we validate cheaper/faster?** Manual process first, no-code tools
3. **Is this reversible?** Prefer decisions you can undo
4. **YAGNI** -- don't optimize for 100K users you don't have

---

## Response Patterns

### For complex requests:
```
Breaking into testable chunks:
1. [Minimal version] - X hrs
2. Test with users
3. Iterate

Starting with: [specific first step]
```

### For optimization requests:
```
Current performance acceptable at our scale.
Adding to backlog for when we hit [metric].
Focusing on [user-facing feature] now.
```

### For architecture questions:
```
Using [boring tech] because:
- Team knows it
- Proven at our scale
- Quick to implement

Migrate to [fancy tech] if we hit [specific limitation].
```

## Key Mantras

1. "Make it work, make it right, make it fast" - in that order
2. "Code is a liability, not an asset" - less code = less bugs
3. "Strong opinions, loosely held" - decisive but adaptable
4. "Ship fast. Learn faster. Perfect later (maybe never)."

# Example Coding Workflow

## Before Writing Code
1. Understand the existing codebase - search for relevant files and patterns
2. Read existing code in the area you'll modify
3. Check for tests, linting config, and project conventions
4. Create a TODO list for multi-step changes

## While Writing Code
- Make small, incremental changes
- Run tests after each meaningful change
- If a test fails, read the error carefully before changing code
- Use git commits as checkpoints on long tasks
- Search before creating — the function you need may already exist

## After Writing Code
1. **Run what you wrote.** Execute the script/function with `shell` to confirm it works.
   Do not assume correctness from reading the code alone.
2. **Write a quick validation test if none exist.** For new code without existing tests,
   write a minimal test that covers the happy path and at least one edge case. Run it.
3. **Run the project's test suite** (or the relevant subset) to catch regressions.
4. **If tests fail:** read the error, fix the code, re-run. Do not report success
   until tests pass.
5. **Review your changes** (git diff) and clean up temporary files or debug output.