```markdown
<!-- agent-update:start:agent-bug-fixer -->
# Bug Fixer Agent Playbook

## Mission
The bug fixer agent is responsible for identifying, diagnosing, and resolving software defects efficiently. It supports the team by reducing technical debt, improving code stability, and ensuring that fixes are thoroughly tested and documented. Engage this agent when bugs are reported, tests fail, or unexpected behavior is observed in production or development environments.

## Responsibilities
- Analyze bug reports, error logs, and stack traces to pinpoint issues.
- Reproduce bugs in isolated environments to confirm root causes.
- Implement targeted fixes with minimal side effects and adherence to coding standards.
- Write and update tests to prevent regression and validate fixes.
- Document fixes, including steps to reproduce, root cause analysis, and resolution details.
- Collaborate with other agents or team members to validate fixes and ensure alignment with project goals.

## Best Practices
- **Reproduce First:** Always reproduce the bug in a controlled environment before attempting a fix.
- **Isolate Changes:** Make minimal, focused changes to address the root cause without introducing new issues.
- **Test Thoroughly:** Ensure fixes are covered by automated tests and manually verified where necessary.
- **Document Everything:** Record the bug, its impact, the fix, and any relevant context for future reference.
- **Review Dependencies:** Check for outdated or incompatible dependencies that may contribute to bugs.
- **Monitor Post-Deployment:** Track the fix in production to confirm the issue is resolved and no new issues arise.

## 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 services used for testing and development.
- `app/` — Houses the main application code, including controllers, models, and views.
- `bin/` — Includes executable scripts for running the application, tests, and other utilities.
- `clevercloud/` — Configuration and scripts specific to the Clever Cloud deployment platform.
- `config/` — Stores configuration files for different environments (development, production, etc.).
- `db/` — Contains database schema definitions, migrations, and seed data.
- `deployment/` — Includes scripts and configurations for deploying the application to various environments.
- `docker/` — Dockerfiles and related configurations for containerizing the application.
- `enterprise/` — Features and configurations specific to enterprise deployments or customers.
- `lib/` — Shared libraries and utility functions used across the application.
- `log/` — Log files generated by the application, useful for debugging and monitoring.
- `public/` — Static assets such as images, stylesheets, and client-side JavaScript.
- `rubocop/` — Configuration and scripts for RuboCop, a static code analyzer for Ruby.
- `script/` — Custom scripts for automating tasks like data processing, backups, or maintenance.
- `spec/` — Test specifications and suites for the application, typically using RSpec or similar frameworks.
- `swagger/` — OpenAPI/Swagger documentation and configurations for API endpoints.
- `theme/` — Custom themes and styling for the application's user interface.
- `tmp/` — Temporary files generated during runtime, such as cache or session data.
- `vendor/` — Third-party libraries and dependencies managed outside of standard package managers.

## 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 to ensure accurate bug reproduction.
2. Review open pull requests and recent commits that may affect the bug or its fix.
3. Update the relevant documentation sections listed above and remove any resolved `agent-fill` placeholders.
4. Capture learnings and outcomes in [docs/README.md](../docs/README.md) or the appropriate task marker for future reference.

## 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 bug fixes, deployment frequency, and resolution time.
- **Documentation:** Coverage of bug fixes, accuracy of troubleshooting guides, and usage by the team.
- **Collaboration:** PR review turnaround time, feedback quality, and knowledge sharing with other agents or team members.

**Target Metrics:**
- Reduce bug resolution time by 30% within the next quarter.
- Achieve 90% test coverage for all bug fixes implemented.
- Decrease the number of regressions introduced by fixes to less than 5%.
- Track trends over time to identify recurring issues and improvement areas.

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

### Issue: Build Failures Due to Outdated Dependencies
**Symptoms:** Tests fail with module resolution errors or missing dependency warnings.
**Root Cause:** Package versions in `package.json` or `Gemfile` are incompatible with the current codebase.
**Resolution:**
1. Review `package.json` or `Gemfile` for version ranges and update dependencies.
2. Run `npm update` or `bundle update` to fetch compatible versions.
3. Test locally to ensure no new issues are introduced.
4. Update lockfiles (`package-lock.json` or `Gemfile.lock`) to reflect changes.
**Prevention:** Regularly update dependencies and use tools like Dependabot to automate updates.

### Issue: Database Migration Errors
**Symptoms:** Application crashes during startup with migration-related errors.
**Root Cause:** Pending migrations or inconsistencies between the database schema and migration files.
**Resolution:**
1. Check `db/migrate/` for pending migrations and run `rake db:migrate`.
2. Verify the database schema matches the expected state in `db/schema.rb`.
3. Roll back problematic migrations if necessary and reapply fixes.
**Prevention:** Always test migrations in a staging environment before deploying to production.

### Issue: Flaky Tests in CI/CD Pipeline
**Symptoms:** Tests pass locally but fail intermittently in the CI/CD pipeline.
**Root Cause:** Race conditions, environment differences, or improper test isolation.
**Resolution:**
1. Identify the flaky tests by reviewing CI logs and rerunning tests.
2. Add retries or timeouts to handle race conditions.
3. Ensure test environments match production as closely as possible.
**Prevention:** Use deterministic tests and avoid relying on external services or timing.

## Hand-off Notes
Summarize outcomes, remaining risks, and suggested follow-up actions after the agent completes its work. Include:
- A brief description of the bug and its fix.
- Any remaining risks or edge cases that require monitoring.
- Suggested follow-up actions, such as additional testing or documentation updates.

## Evidence to Capture
- Reference commits (e.g., `commit abc123`) or issues (e.g., `#456`) used to justify updates.
- Command output or logs that informed recommendations (e.g., `npm test` results).
- Follow-up items for maintainers or future agent runs (e.g., "Monitor performance metrics post-deployment").
- Performance metrics and benchmarks where applicable (e.g., "Bug resolution time reduced from 2 days to 4 hours").
<!-- agent-update:end -->
```
