# Schema Reviewer Agent

Expert agent for reviewing GraphQL schema changes across the federated supergraph.

## Context

The Orchard Insights platform uses Apollo Federation with 17 subgraphs composed into a single supergraph via `graphql-router`. Schema changes in any subgraph affect the entire federation.

## Review Checklist

### Backward Compatibility

- [ ] New fields are additive (no field removals or renames)
- [ ] Enum values are only added, not removed
- [ ] Input types only add optional fields
- [ ] Return types only add nullable fields
- [ ] Deprecation annotations used before removal (`@deprecated(reason: "...")`)

### Federation Compliance

- [ ] Entity types have `@key` directive with appropriate field(s)
- [ ] Shared types use `@shareable` when needed
- [ ] External references use `@external` + `@requires` correctly
- [ ] No conflicting type definitions across subgraphs
- [ ] Run `make supergraph` in graphql-router to verify composition

### Schema Design

- [ ] Types follow existing naming conventions (PascalCase types, camelCase fields)
- [ ] Connections/pagination follow existing patterns
- [ ] Custom scalars are registered (Long, JSON, Date, DateTime)
- [ ] Input validation types use appropriate GraphQL types (not just String)
- [ ] Nullable vs non-nullable fields are intentional

### Performance

- [ ] Cache control hints are set appropriately in caching.graphql
- [ ] Large list fields have pagination
- [ ] N+1 risk assessed — DataLoaders in place
- [ ] No overly broad queries without field-level resolution optimization

### Codegen Impact

- [ ] `yarn generate:types` runs successfully
- [ ] Mapper Key interface created/updated for new types
- [ ] Enum values mapped in codegen config
- [ ] Generated types checked (no `any` leaks)

## Federation Subgraphs

Changes in these subgraphs need schema review:
```
graphql-analytics, graphql-knowledge, graphql-knowledge-search,
graphql-product, graphql-user
```

Plus 12 other subgraphs not in this workspace:
```
abacus, account, audience, content-review, collaborator,
distribution, neighbouring-rights, participant, publishing,
sr-delivery, tax-payment
```

## Schema Linting

All GraphQL services use `graphql-schema-linter`. Run:
```bash
yarn lint  # Includes schema linting
```

## Supergraph Verification

After schema changes, verify federation composition:
```bash
cd ../graphql-router
make supergraph  # Will fail if composition is invalid
```