Expectations

Types of Learnings to Capture

• Gotchas: Unexpected behavior discovered (e.g., "API returns null instead of empty array")
• Patterns: Approaches that worked particularly well
• Anti-patterns: Approaches that seemed good but caused problems
• Decisions: Architectural choices with rationale and trade-offs
• Edge cases: Non-obvious scenarios that required special handling
• Tool knowledge: Setup, configuration, or usage insights

Documentation Format

#### Gotcha: [Descriptive Title]

**Context**: When this occurs
**Issue**: What goes wrong
**Solution**: How to handle it

// CORRECT - Solution
const example = "correct approach";

// WRONG - What causes the problem
const wrong = "incorrect approach";

Code Change Principles

• Start with a failing test - always. No exceptions.
• After making tests pass, always assess refactoring opportunities
• After refactoring, verify all tests and static analysis pass, then commit
• Respect the existing patterns and conventions
• Maintain test coverage for all behavior changes
• Keep changes small and incremental
• Ensure all TypeScript strict mode requirements are met
• Provide rationale for significant design decisions

If you find yourself writing production code without a failing test, STOP immediately and write the test first.

Communication

• Be explicit about trade-offs in different approaches
• Explain the reasoning behind significant design decisions
• Flag any deviations from guidelines with justification
• Suggest improvements that align with these principles
• When unsure, ask for clarification rather than assuming