# Service catalog that stays accurate

The Service Catalog is only as good as the tags feeding it. Unified tagging (service, env, version on everything) is the prerequisite; everything below assumes it is done.

## Build it

1. **Tag every service** with unified tagging: agent config for infra, env vars for tracers, resource specs for serverless. No tag, no catalog entry worth trusting.
2. **Service definitions in the repo**: a small definition file per service (name, team, contacts, links to runbooks and dashboards) committed next to the code. The catalog reads it; the repo owns it.
3. **Scorecards**: define the standards (has runbook, has SLO, has on-call, logs parsed, traces sampled) and score every service. Publish the scores. Nothing motivates like a red scorecard in the team channel.
4. **Ownership tags**: `team:` on every service so the catalog answers "who owns this" without a wiki hunt.

## Keep it accurate

- **Stale service cleanup**: services with no telemetry in 30 days get flagged, then removed. A catalog full of dead services is a catalog nobody trusts.
- **Definition review in code review**: the service definition file changes with the service. New endpoint, new dependency: update the file in the same PR.
- **Dependency map**: the service map derives from trace data, which means it reflects reality, not the architecture diagram from 2023. Use it in incident response instead of the wiki.

## Verify

Every production service appears with correct team, runbook link, and SLO status. The scorecard has no reds older than a quarter. An incident responder can find the owner and runbook from the catalog alone.