Runbook: Quality Check Failing

Trigger

• make verify fails locally.
• CI quality gate fails on lint/type/test/docs sync stage.

Fast triage

1. Run full gate once: make verify.
2. Identify failing step: lint-check, type-check, test, docs-fix.
3. Run only the step that failed to get faster feedback.

Most common causes

• Lint/type errors after refactor.
• Tests expect outdated API contract or DB state.
• Docs not synchronized after endpoint/config changes.
• New module not wired into imports or package exports.

Recovery steps by stage

Lint fails

• Run make lint-fix and make lint-check.

Type-check fails

• Run make type-check.
• Fix signatures/annotations/import types.

Tests fail

• Run make test.
• For focused debugging run make test-one path=....
• If schema changed, validate migrations/fixtures.

Docs sync fails or changes produced

• Run make docs-fix.
• Commit generated updates if valid.

Final recovery sequence

1. make verify
2. make release-check

Exit criteria

• make verify passes end-to-end.
• make release-check passes.
• Your diff only includes changes you meant to ship.

Follow-up

• If the steps were unclear, update developer docs or a runbook.
• If governance or architecture changed, add or update an ADR.

Page history