Skip to main content

​
What We Learned

Writing implementation-ready GitHub issues directly from API contracts (OpenAPI, Protobuf, service communication maps) surfaces schema drift that code reviews would miss. When we generated 16 Block C/E issues from choco-hq’s contract surface, the RBAC issue exposed three conflicting role definitions:
  • Proto (common.proto:120): 6 roles — reader, contributor, editor, reviewer, maintainer, admin
  • DB migration (000001_initial_schema.up.sql:80): 4 roles — owner, admin, editor, viewer
  • Acceptance criteria (acceptance-criteria.yaml:415): 6 roles — aligned with proto
The DB migration was written early and never updated when the proto was finalized. Without contract-first issue generation, this drift would surface as a runtime bug after auth implementation.

​
Why It Matters

Schema drift between contract layers (proto, DB, acceptance criteria) is invisible to CI. Linters check syntax, not semantic alignment. The only reliable detection method is a human or agent reading across contract boundaries — which is exactly what issue generation forces you to do. The cost gradient is steep: catching drift during issue writing is free. Catching it during code review costs a round-trip. Catching it in production costs an incident.

​
The Pattern

  1. Read all contracts for the target scope (proto, OpenAPI, DB migrations, acceptance criteria)
  2. Cross-reference enums, field names, and cardinality across layers
  3. Flag mismatches as explicit acceptance criteria in the issue (e.g., “DB migration aligns CHECK constraint with proto enum”)
  4. Include the file paths and line numbers so the implementer can verify

​
Applicability

Any multi-layer system where contracts are defined in separate files (proto + OpenAPI + SQL + acceptance YAML). Especially valuable during the B-to-C transition where contracts are “finalized” but downstream schemas may be stale from earlier prototyping.