Context debt

2 min readReferenceUpdated 2026-05-19

What you'll find here

The craik.context_debt_record contract — how Craik makes known gaps in the context an agent used explicit, so future agents can decide whether to continue, refresh, or stop for more information.

Make omissions explicit.

The structured records are persisted separately so callers can track owner, source links, next action, carry-forward state, and resolution.

What records can represent

Omitted documentation

Excluded docs

By discovery rules.

Stale instruction constraints

Unresolved assumptions

Missing external state

Such as GitHub.

Missing memory facts

Active instruction constraints carried forward

Missing case files

Other explicit context gaps

Lifecycle rules

State

Required field

Notes

Open or carried-forward

next_action

Must be set so the resuming agent knows what to do.

Resolved

resolved_at · resolved_by_receipt_id

Must include the resolution timestamp and the operator receipt that closed the debt record.

Resolution

resolve_context_debt is a store-backed transition helper. It loads the debt record, mints or links an operator receipt, writes the updated record, and returns the persisted resolved form. Operators can exercise the same path from the CLI:

craik knowledge resolve-context-debt context_debt_task_docs_missing_external_state_github \
  --summary "GitHub state was refreshed."

The command requires an active operator session. The output includes resolved_by_receipt_id, and the receipt is persisted in the local store for later operator review.

Handoff summary

Handoffs continue to expose a deterministic context_debt summary list for runner readability. The structured records persist separately.

What's next

GuideContext budgetingHow case-file omissions become debt.ReferenceEvidence and assumption viewThe operator surface where unresolved debt surfaces.ReferenceSchema referenceThe context_debt_record shape.