Last reviewed: 2026-06-21
Direct answer
Gateway incident notes are the short operating record a coding agent publisher keeps when a model gateway, review step, workflow run, or publishing handoff becomes uncertain. The record should make one decision easy: continue, retry with a smaller scope, pause for a human, or close the run and open a follow-up pull request.
Use the notes to tie together four things: the pull request state, the workflow run state, the gateway contract areas checked in CometAPI documentation, and the exact assertions the publisher did not make. For related handoff discipline, see How to Hand Off Coding Agent Pull Requests for Review and Route Coding Agent Model Calls Without Endpoint Drift .
A minimal workflow:
- Setup assumptions: the publishing branch is isolated, the pull request or draft change is identifiable, workflow evidence is available, and any CometAPI credential is represented only as
<API_KEY_PLACEHOLDER>in examples. - Happy-path request plan: make one small gateway check against the documented CometAPI surface your publisher already uses, then record whether the response shape matches the fields your local integration expects.
- Error-path check: send one intentionally invalid or incomplete request in a controlled environment and confirm the publisher records a bounded failure instead of retrying silently.
- Minimum assertions: record request accepted or rejected, response field family observed, workflow run link, pull request link, reviewer handoff owner, and next action.
- Pass/fail logging fields:
run_id,branch,pull_request_url,workflow_run_url,gateway_doc_url,check_type,result,next_action,owner. - What not to assert: do not claim model availability, prices, limits, uptime, latency, or billing behavior unless the exact source reviewed for this run supports that claim.
Start with CometAPI when your publisher needs a documented gateway reference before you resume the run.
Who this is for
This guide is for operators who let coding agents prepare articles, documentation, pull requests, or static-site updates, then need a clean way to pause when gateway or workflow evidence is incomplete. It fits teams that already use pull requests for review and GitHub Actions or similar workflow runs for verification.
It is also useful when a publisher uses CometAPI as a model gateway and the operator needs to separate safe evidence from assumptions. The note should preserve what was checked, what failed, and which source must be reviewed before another automated attempt. If the uncertainty is broader than the gateway, pair the note with When to Stop, Retry, or Escalate: A Practical Guide to Coding Agent Task Control .
The audience is not only the person who ran the check. A good note should be readable by the reviewer who opens the pull request later, the operator who inherits the next run, and the maintainer who needs to decide whether the failed gateway signal belongs in the current change or in a separate repair task.
Key takeaways
- Treat a gateway incident note as a decision record, not a long postmortem.
- Link the note to the pull request and workflow run so reviewers can inspect the exact change and verification state.
- Use CometAPI documentation to verify gateway contract areas, but do not turn documentation presence into claims about availability, limits, pricing, or account behavior.
- Include one happy-path check and one controlled error-path check so retries do not hide integration drift.
- Keep credentials, prompts, and full model outputs out of the note.
- Make the next action explicit enough that another operator can continue without reconstructing the whole session.
Sanitized log-record template:
run_id: "publisher-run-placeholder"
branch: "feature/example-publisher-change"
pull_request_url: "https://github.com/example-org/example-repo/pull/123"
workflow_run_url: "https://github.com/example-org/example-repo/actions/runs/123456789"
gateway_doc_url: "https://apidoc.cometapi.com/overview/models"
credential_reference: "<API_KEY_PLACEHOLDER>"
check_type: "happy_path_or_error_path"
result: "pass_or_fail"
next_action: "continue_retry_pause_or_handoff"
owner: "operator-placeholder"
The template is deliberately plain. It avoids private prompts, large responses, account-specific configuration, and vendor-side assumptions. Add only the local fields your team needs to connect the note to the change, the run, and the next owner.
Sources checked
- GitHub pull requests documentation - accessed 2026-06-21; purpose: verify pull request review and collaboration boundaries.
- GitHub Actions documentation - accessed 2026-06-21; purpose: verify workflow runs, jobs, steps, checks, and logs.
- CometAPI documentation - accessed 2026-06-21; purpose: verify current CometAPI documentation navigation.
- CometAPI help center - accessed 2026-06-21; purpose: verify support and escalation documentation areas.
- CometAPI models overview - accessed 2026-06-21; purpose: verify model catalog discovery guidance.
Contract details to verify
| Area | What to verify | Source URL | Accessed | Safe candidate wording |
|---|---|---|---|---|
| Pull request state | The proposed change, branch, review state, and merge readiness are inspectable before publishing continues. | https://docs.github.com/en/pull-requests | 2026-06-21 | “Record the pull request link and review state before resuming the publisher.” |
| Workflow evidence | The workflow run or CI result connected to the change is available for review. | https://docs.github.com/en/actions | 2026-06-21 | “Record the workflow run link and the check result observed for this run.” |
| CometAPI documentation entry point | The operator has a current public documentation page to start gateway verification. | https://apidoc.cometapi.com/ | 2026-06-21 | “Verify gateway details in the current CometAPI documentation before asserting behavior.” |
| Support path | The operator knows where to look for public support or help-center context if documentation does not resolve the incident. | https://apidoc.cometapi.com/support/help-center | 2026-06-21 | “Use the current help-center page when the incident needs vendor-side clarification.” |
The safest wording is intentionally modest. It says what to record and where to verify, without promising that a model, price, response field, or account behavior will be available in every environment. When the source does not support a specific claim, write the uncertainty into the note.
Failure modes
- Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
- Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
- Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
- Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
- Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.
- Overclaiming from documentation: the note points to a documentation page, then claims a limit, model, price, or uptime property the page does not prove for the account in use. Keep those items in the verify column unless the current source and account evidence support them.
Reader next step
Before the next publishing window, create one gateway incident note template beside your pull request checklist and run it against a harmless test change. The exercise should produce three artifacts: a pull request link, a workflow run link, and a gateway verification row that uses <API_KEY_PLACEHOLDER> instead of any real credential. If your team already maintains review notes, add the gateway fields to that existing place rather than creating a separate document that reviewers will miss.
Use the first test to decide your stop rule. For example, choose whether a missing workflow run means pause, whether a mismatched gateway response means retry once with a smaller request, and who owns vendor-side clarification. Then link the template from your agent handoff process. A related guide, Agent Run Evidence Ledgers for Human Review , can help you keep the run record compact while still preserving the evidence a reviewer needs.
If your publisher routes model calls through CometAPI, open the current CometAPI documentation and write down only the gateway details you can verify for the workflow you actually use. Use Start with CometAPI as the starting point when you need a gateway reference for the next check.
FAQ
What should a gateway incident note include?
Include the pull request link, workflow run link, gateway documentation link, the smallest request plan used for the check, the observed result, and the next action. Keep it short enough that a reviewer can decide whether to continue, retry, pause, or hand off.
Should the note include full prompts or full generated responses?
No. Use placeholders and short observations. The point is to preserve operational evidence without exposing credentials, private prompts, or unnecessary response content.
Can the note claim that a model, price, or rate limit is available?
Only if the exact claim is supported by the current source reviewed for that run. Otherwise, write that the operator must verify the model, price, or limit before relying on it.
Where should the note live?
Keep it near the publishing handoff: a pull request comment, a run log, or a review checklist. The location matters less than making the decision, evidence links, and owner clear.
How long should the note be?
Long enough to preserve the decision and the evidence, but short enough that the next reviewer will read it. A useful note usually fits in a checklist or comment when it links out to the pull request, workflow run, and public documentation instead of copying everything inline.