# Debugging Methodology

## Check Before You Act

- Before writing firewall/network rules, check actual routing (`ip route get <dest>`)
- Before running config management with variables, ensure values are real, not placeholders
- Before assuming a container has a shell, `docker inspect` it
- Before creating API tokens, research all required scopes upfront — iterating one scope at a time costs a push-debug cycle each

## Routing and Networking

- Always run `ip route get <dest>` on the forwarding host first
- macvlan, Docker bridge, and other virtual interfaces mean the "obvious" physical interface is often wrong
- Test from both in-cluster and external perspectives

## Full-Chain Testing

After wiring up any new service:
1. Test direct to backend (bypass all proxies)
2. Test through reverse proxy (bypass DNS)
3. Test end-to-end as a user would

Use `curl --resolve` to test specific paths without depending on DNS propagation.

## When Something Doesn't Sync/Apply

- Check resource exclusions in the GitOps controller immediately
- Check if the resource type requires special permissions or labels
- Check if ServerSideApply conflicts are preventing field changes
- Don't try workarounds before understanding the root cause

## OIDC Integration Checklist

Before starting any OIDC integration, research:
1. What format is the `sub` claim (UUID? username?)
2. Which claims are in the ID token vs userinfo endpoint
3. How the consumer matches RBAC identities (groups? email? username?)

## Grep Your Own Docs

Known issues documented in CLAUDE.md or MEMORY.md but not applied to new scripts/configs waste debugging time. Search your own documentation before writing automation that touches areas with known gotchas.