---
trigger: model_decision
description: When a new feature is added, this prompt needs to be run
---

# Development Guidelines

## Code Quality Standards

### Testing Requirements
- MANDATORY: Every new feature MUST include corresponding tests
- Write tests BEFORE implementing complex features (TDD approach)
- Test coverage for new code should be >80%
- Include both unit tests and integration tests where applicable
- Test edge cases, error paths, and boundary conditions

### Documentation Standards
- Update relevant documentation IN THE SAME COMMIT as code changes
- Documentation locations:
  - README.md: User-facing features, installation, quick start
  - CHANGELOG.md: All changes, following Keep a Changelog format
  - Code comments: Complex logic, non-obvious decisions, API contracts
  - Function/struct docs: Public APIs must have doc comments
- Use concrete examples in documentation
- Keep docs concise but complete

### Code Organization
- CRITICAL: Clean up as you go - no orphaned files or dead code
- Remove commented-out code blocks (use git history instead)
- Delete unused imports, functions, and variables immediately
- Consolidate duplicate code into reusable functions
- Move TODO items from loose files into:
  - Code comments with `// TODO(context):` for implementation tasks
  - GitHub Issues for larger features
  - NEVER create standalone .md files for tracking

### When Making Changes
For EVERY significant change, complete ALL of these:

1. Write/update tests
2. Update documentation (README, CHANGELOG, code comments)
3. Update build scripts if dependencies/build process changed
4. Remove any temporary/debug code added during development
5. Delete unused files created during exploration
6. Verify no dead code remains (unused functions, imports, variables)

### Cleanup Checklist (Run BEFORE committing)
- [ ] Removed all debug print statements
- [ ] Deleted temporary test files
- [ ] Removed commented-out code
- [ ] Cleaned up unused imports
- [ ] Deleted exploratory/spike code
- [ ] Consolidated duplicate logic
- [ ] Removed obsolete scripts/configs

### Communication Style
- Report what you've done: "Added feature X with tests in test/x_test.go"
- Highlight what needs attention: "WARNING: Manual testing needed for edge case Y"
- Ask questions directly: "Should we support Z? Trade-offs are..."
- NEVER say "I'll track this in a markdown file" - use code comments or tell me directly

### Script/Build System Updates
- Update Makefile/build.zig when adding new targets or commands
- Modify CI/CD configs (.github/workflows) if build/test process changes
- Update package.json/Cargo.toml/go.mod when dependencies change
- Document new scripts in README under "Development" section

## Anti-Patterns to AVOID
- Creating notes.md, todo.md, tasks.md, ideas.md files
- Leaving commented-out code "for reference"
- Keeping old implementation files with .old or .backup suffixes
- Adding features without tests
- Updating code without updating docs
- Leaving TODO comments without context or assignee

## Preferred Patterns
- Inline TODO comments: `// TODO(user): Add caching layer for better performance`
- Self-documenting code with clear names
- Tests that serve as usage examples
- Incremental, complete commits (code + tests + docs)
- Direct communication about tasks and priorities

## Definition of Done
A task is complete ONLY when:
1. Code is written and working
2. Tests are written and passing
3. Documentation is updated
4. All temporary/dead code is removed
5. Build scripts are updated if needed
6. Changes are committed with clear message