# Skill: Service integration in a complex codebase
## Purpose
Extend or integrate with existing services in our main backend codebase while preserving ownership boundaries, reliability standards, and observability requirements.
## When to use this skill
- The change requires adding or modifying a backend API, job, or event.
- The service lives in a **shared monorepo** with clear ownership and domain boundaries.
- The work may require coordination with other teams, but the main implementation happens in our services.
## Inputs
- **Business requirement**: short description of the user or system behavior change.
- **Primary service(s)**: names/paths of the services and domains involved.
- **Existing contracts**: relevant API schemas, events, or message formats.
- **Non-functional requirements**: latency, error budget, data retention, and throughput expectations.
- **Change management**: rollout strategy, feature flags, or migration plan.
## Out of scope
- Greenfield systems that require new infrastructure or data stores.
- Cross-region or cross-cloud replication design.
- Changes that conflict with established ownership boundaries without prior approval.
## Conventions
- Follow the **domain boundaries** and module layout described in `AGENTS.md` and internal architecture docs.
- Use existing **configuration, logging, metrics, and tracing** patterns.
- Reuse established **error handling** and **retry/backoff** utilities.
## Required behavior
1. Introduce new APIs, jobs, or events using existing framework patterns.
2. Maintain backwards compatibility wherever possible; if breaking changes are required, document migration steps.
3. Ensure all new behavior is observable via logs, metrics, and/or traces.
4. Respect existing security and privacy requirements (authN/Z, PII handling, data residency).
## Required artifacts
- Code changes in the relevant service(s) and domain modules.
- **Unit tests** for core logic and boundary conditions.
- **Integration or contract tests** for new or modified interfaces, where harnesses exist.
- Updated **runbooks or design docs** only if required by your team's process (link from the PR description instead of duplicating here).
## Implementation checklist
1. Identify ownership and confirm which service(s) should change.
2. Map the data and control flow across services and dependencies.
3. Design the integration surface (API, event, or job) and validate it against existing conventions.
4. Implement the change, keeping related files and modules co-located.
5. Add or update tests at the appropriate layers (unit, integration, contract).
6. Ensure logs/metrics/traces make the new behavior debuggable in production.
7. Wire in feature flags or configuration for safe rollout if necessary.
## Verification
Run the service-level validation commands, for example:
- `pnpm test --filter <service>` or `pytest` in the service directory
- `pnpm lint` or equivalent linter for the language in use
- Any existing **contract or integration test suites** referenced from `AGENTS.md` or service docs
The skill is complete when:
- All relevant tests and linters pass.
- The new integration behaves correctly in local or staging environments.
- Observability signals (logs, metrics, traces) show the expected behavior without noisy regressions.
## Safety and escalation
- If the change touches **shared schemas, core auth logic, billing, or compliance-critical data**, stop and request explicit human approval and design review.
- If dependencies owned by other teams need changes, create or update their tickets and clearly document assumptions and contract expectations in the PR.
