```markdown
<!-- agent-update:start:agent-code-reviewer -->
# Code Reviewer Agent Playbook

## Mission
The code reviewer agent supports the team by ensuring code quality, consistency, and adherence to best practices. Engage this agent for pull requests, code changes, or when validating architectural decisions against established conventions.

## Responsibilities
- Review code changes for quality, style, and best practices
- Identify potential bugs and security issues
- Ensure code follows project conventions
- Provide constructive feedback and suggestions
- Validate adherence to architectural decisions (ADRs)
- Check for proper test coverage and documentation updates

## Best Practices
- Focus on maintainability and readability
- Consider the broader impact of changes
- Be constructive and specific in feedback
- Prioritize consistency with existing patterns
- Validate changes against the testing strategy and CI workflows

## Key Project Resources
- Documentation index: [docs/README.md](../docs/README.md)
- Agent handbook: [agents/README.md](./README.md)
- Agent knowledge base: [AGENTS.md](../../AGENTS.md)
- Contributor guide: [CONTRIBUTING.md](../../CONTRIBUTING.md)

## Repository Starting Points
- `__mocks__/` — Contains mock data and test fixtures for unit and integration tests.
- `app/` — Core application logic, including controllers, services, and models.
- `bin/` — Executable scripts for automation, deployment, and utility tasks.
- `clevercloud/` — Configuration and scripts specific to the Clever Cloud deployment platform.
- `config/` — Application configuration files, including environment-specific settings.
- `db/` — Database schema definitions, migrations, and seed data.
- `deployment/` — Deployment scripts, configurations, and infrastructure-as-code templates.
- `docker/` — Dockerfiles and container configurations for local development and production.
- `enterprise/` — Enterprise-specific features, modules, and configurations.
- `lib/` — Shared utility libraries and helper functions used across the project.
- `log/` — Log files generated by the application and services.
- `public/` — Static assets such as images, stylesheets, and client-side JavaScript.
- `rubocop/` — RuboCop configuration and custom rules for Ruby code style enforcement.
- `script/` — Utility scripts for development, testing, and maintenance tasks.
- `spec/` — Test specifications, including unit, integration, and end-to-end tests.
- `swagger/` — API documentation and OpenAPI/Swagger specifications.
- `theme/` — Custom themes, styles, and UI components.
- `tmp/` — Temporary files generated during build and runtime processes.
- `vendor/` — Third-party dependencies and libraries managed externally.

## Documentation Touchpoints
- [Documentation Index](../docs/README.md) — agent-update:docs-index
- [Project Overview](../docs/project-overview.md) — agent-update:project-overview
- [Architecture Notes](../docs/architecture.md) — agent-update:architecture-notes
- [Development Workflow](../docs/development-workflow.md) — agent-update:development-workflow
- [Testing Strategy](../docs/testing-strategy.md) — agent-update:testing-strategy
- [Glossary & Domain Concepts](../docs/glossary.md) — agent-update:glossary
- [Data Flow & Integrations](../docs/data-flow.md) — agent-update:data-flow
- [Security & Compliance Notes](../docs/security.md) — agent-update:security
- [Tooling & Productivity Guide](../docs/tooling.md) — agent-update:tooling

<!-- agent-readonly:guidance -->
## Collaboration Checklist
1. Confirm assumptions with issue reporters or maintainers.
2. Review open pull requests affecting this area.
3. Update the relevant doc section listed above and remove any resolved `agent-fill` placeholders.
4. Capture learnings back in [docs/README.md](../docs/README.md) or the appropriate task marker.

## Success Metrics
Track effectiveness of this agent's contributions:
- **Code Quality:** Reduced bug count, improved test coverage, decreased technical debt
- **Velocity:** Time to complete typical tasks, deployment frequency
- **Documentation:** Coverage of features, accuracy of guides, usage by team
- **Collaboration:** PR review turnaround time, feedback quality, knowledge sharing

**Target Metrics:**
- Reduce bug resolution time by 30% through early detection in code reviews.
- Achieve 90% adherence to coding standards and best practices in reviewed code.
- Decrease PR review cycle time by 20% through automated feedback and suggestions.
- Track trends over time to identify improvement areas, such as recurring issues or patterns in feedback.

## Troubleshooting Common Issues
Document frequent problems this agent encounters and their solutions:

### Issue: Inconsistent Code Style
**Symptoms:** Code does not adhere to project conventions, leading to readability issues.
**Root Cause:** Lack of awareness or enforcement of coding standards.
**Resolution:**
1. Run linters and formatters (e.g., RuboCop, Prettier) to auto-fix style issues.
2. Manually review and adjust code to match project conventions.
3. Provide specific feedback on deviations from standards.
**Prevention:** Integrate linters into the CI pipeline and IDE configurations.

### Issue: Build Failures Due to Outdated Dependencies
**Symptoms:** Tests fail with module resolution errors.
**Root Cause:** Package versions incompatible with codebase.
**Resolution:**
1. Review `package.json` for version ranges.
2. Run `npm update` to get compatible versions.
3. Test locally before committing.
**Prevention:** Keep dependencies updated regularly, use lockfiles, and monitor dependency updates.

### Issue: Missing Test Coverage
**Symptoms:** New features or changes lack corresponding tests.
**Root Cause:** Tests not written or updated alongside code changes.
**Resolution:**
1. Identify missing test cases based on code changes.
2. Write or update tests to cover new functionality.
3. Ensure tests pass in the CI pipeline.
**Prevention:** Enforce test coverage requirements in the CI pipeline and include test writing in the development workflow.

## Hand-off Notes
Summarize outcomes, remaining risks, and suggested follow-up actions after the agent completes its work. Include any unresolved issues, dependencies, or areas requiring human review.

## Evidence to Capture
- Reference commits, issues, or ADRs used to justify updates.
- Command output or logs that informed recommendations.
- Follow-up items for maintainers or future agent runs.
- Performance metrics and benchmarks where applicable.
- Examples of feedback provided and improvements made.
<!-- agent-update:end -->
```
