Trace an incident to the prompt

An incident record naming the commit, PR, session and prompt hash, fixed before the story changes.

Who this is for

Engineering platforms, SRE teams and coding-agent vendors.

The problem

After an outage, the account of what caused it shifts as people revise notes. An incident record fixes what was known and when, and links the cause to the agent session and prompt behind it.

How it works

• The incident bundle stays private; its hash becomes the record's artifact.
• incident carries id, time, title and severity. attribution carries commit, PR, session, prompt hash and model.
• Find it by incident id later.

Routes it uses

• POST /v1/records: append a signed record; the answer carries its digest and inclusion proof.
• GET /v1/records?ref={ref}: every record carrying a handle such as a PR, incident or case id.

Set it up

Step 1. Publish the incident

Post an incident record: incident: { id, occurred_at, severity } and attribution: { commit, pr_ref, session_id, prompt_hash, model }. developer is a handle or hash, never personal data.

BODY='{ ...record }'
SIG=$(printf %s "$BODY" | ./sign-ed25519)   # base64url signature over these exact bytes
curl -s -X POST 'https://aisourceoftruth.com/v1/records' \
  -H "Authorization: Bearer $AISOT_TOKEN" \
  -H "X-AISOT-Key-Id: $AISOT_KEY_ID" \
  -H "X-AISOT-Signature: $SIG" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/vnd.aisot.record+json' \
  --data-binary "$BODY"

Check: The record is findable by the incident id.

Step 2. Link the cause

Put the PR's provenance record digest in lineage, so the incident sits downstream of the change that caused it.

BODY='{ ...record }'
SIG=$(printf %s "$BODY" | ./sign-ed25519)   # base64url signature over these exact bytes
curl -s -X POST 'https://aisourceoftruth.com/v1/records' \
  -H "Authorization: Bearer $AISOT_TOKEN" \
  -H "X-AISOT-Key-Id: $AISOT_KEY_ID" \
  -H "X-AISOT-Signature: $SIG" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/vnd.aisot.record+json' \
  --data-binary "$BODY"

Check: The PR record's lineage lists the incident.

Step 3. Find it later

Query by incident id.

curl -s -H 'Accept: application/json' 'https://aisourceoftruth.com/v1/records?ref={ref}'

Check: Every record for the incident comes back.

Publishing needs a publisher key and a token. The one-time setup is on /agents and in the plan's design.md.

Wire it into your agent

Publish from the incident tool when the incident is declared, then again with attribution when the cause is known. Both records stay.

MCP: add https://aisourceoftruth.com/mcp to the agent's MCP servers. Tools used: publish_record, search_records. Read tools need no token.

With the PromptReports products, or alone

• RepoOps: RepoOps links incidents to the agent session and agent version that made the change, which supplies the attribution block.
• CommitOps: CommitOps can show which customer promises an incident put at risk.
• Alone: every step above uses only AI Source of Truth.

Expected outcomes

• Each incident has a fixed public timeline and a link to its cause.

What it does not prove

• Attribution is your statement. The record fixes when you made it, not that it is right.

The OpenSpec plan for your agent

Your coding agent fetches the plan and writes it into your repo as openspec/changes/integrate-aisot-incident-records/:

curl -H 'Accept: application/json' 'https://aisourceoftruth.com/use-cases/incident-to-prompt/openspec?lang=python&with=repoops,commitops'

• proposal.md: why, what changes in your product, impact.
• design.md: where the calls sit in your agent, with code for each call.
• tasks.md: checkable tasks, each step paired with a check against the live registry.
• specs/incident-records/spec.md: the requirements and scenarios.

Read it here: OpenSpec plan. Back to all use cases or the documentation library.