ADR-0004: OpenAI classification as a reviewed suggestion
- Status: Superseded by ADR-0009
- Date: 2026-09-11
Context
Deterministic rules classify most merged pull requests, but changes without a Conventional Commit title type or a familiar label stay Unknown. ReleaseFlow adds one AI provider, OpenAI, to help with those changes. It is the first network call the application makes. The product invariants require that AI failures become explicit review states, that network I/O never runs inside a database transaction, and that a person decides what ships.
Decision
- Only changes the rules left Unknown can be sent to OpenAI. Rule results are explainable and are never replaced by a model answer.
- A person starts each request from the Change Inbox, or through
POST /api/projects/{projectId}/changes/{changeId}/ai-classification. The webhook never calls OpenAI, and there is no background worker, queue, or automatic retry. After a failure, the person can press the button again. - The request uses the Chat Completions API with a strict JSON Schema
(Structured Outputs). The schema allows the same categories as the rules,
plus
unknown, a breaking flag, and a short rationale. The request setsstore: false. It sends only the title, labels, target branch, and at most 4000 characters of the description. The author is not sent. The prompt tells the model to treat pull request text as data. - An AI result is a suggestion. The change keeps
needs_review = true, and the AI can add a breaking flag but never remove one. A database check constraint enforces both. - A failed attempt is stored as
ai_status = FAILEDwith a fixed, safe message. The change stays Unknown and in review. - The service reads the change in one short transaction, calls OpenAI with no transaction open, and writes the outcome in a second transaction. The client refuses to run inside an active transaction.
- The client is a direct
RestClientclass with no provider interface. The API key and model come only from the environment. The model has no default, and AI stays disabled unless both values are present.
Consequences
- No new dependency is needed, and tests use a local HTTP stub instead of the real API.
- Reviewers see the model's category, breaking flag, and rationale next to the rule reasons, but no AI output bypasses review.
- Merged pull request text leaves the system when a person asks for a suggestion. Operators who cannot send that data can leave AI disabled.
- A second provider, automatic classification, or retries would each need a new decision rather than an extension point prepared now.