Using Case Files

6 min readFor operatorsUpdated 2026-05-19

What you'll do

Build, inspect, and refresh per-task case files day-to-day. By the end you'll know how to tune discovery for one project or one run, what fields to review before authorizing work, and how to keep case-file context honest.

Prerequisites

• A registered project (see Project registry).
• A task created with craik task create. The case-file build pulls the task's objective and intent lock.

1 · Register the project with the right boundaries

Case files are only as good as the project they're built against. Tune discovery during registration:

Register a project with explicit boundaries

craik project add /path/to/repo \
  --name Example \
  --docs-path README.md \
  --docs-path docs/ \
  --immutable-path docs/adr/

When the default repository discovery rules need project-specific tuning, add --discovery-exclude / --discovery-include:

Exclude generated docs; keep archived release notes

craik project add /path/to/repo \
  --name Example \
  --discovery-exclude "docs/generated/**" \
  --discovery-include "docs/archive/current-release/**"

2 · Create the task

A reviewable task with explicit scope

craik task create \
  --project Example \
  --title "Review docs" \
  --objective "Review docs against implementation." \
  --mode review \
  --out-of-scope "ADR edits"

The --out-of-scope flag rolls into the intent lock, which the case file will reference.

3 · Build the case file

Default build

craik case build task_review_docs

For a single run, override discovery without changing the project:

One-off discovery override

craik case build task_review_docs --discovery-exclude "docs/drafts/**"

4 · Inspect what you got

Show by task id or case-file id

craik case show task_review_docs
craik case show case_review_docs

The output is structured JSON. Pipe it through jq or your editor. The fields you should always read before authorizing a run:

objective

The runtime's stated goal for the task. Match it against what you actually want.

policy_envelope_id

The policy that will gate execution. Confirm it matches the run's risk profile.

intent_lock_id

The scope contract — in/out-of-scope, stop conditions, allowed autonomy.

repo_state

Branch, head, clean/dirty status. Make sure you're on the branch you think you are.

docs

Mutable doc roots that will be loaded as context.

immutable_docs

ADRs and other immutable evidence — read but not editable.

evidence

Every piece of context with its provenance. Spot-check that the evidence supports the task.

assumptions

What the runtime couldn't find. Open assumptions are not bugs — they're honesty.

stale_risks

Markers calling out context the runtime believes may have moved since indexing.

context_budget

Deterministic per-section token allocations. context_budget.docs_excluded lists generated / dependency / build / cache / archive paths skipped before budgeting.

context_budget.docs_excluded is worth attention: if a path you expected to be included is listed there, you probably want a --discovery-include override for either the project or this specific build.

5 · Treat assumptions as first-class

Open assumptions mean the case file is useful but incomplete. The runtime is being honest about what it couldn't find — typically because a memory backend isn't configured, the GitHub adapter is off, or evidence expected from a prior handoff is missing.

Downstream agents should:

1. Keep assumptions visible in plans, findings, and handoffs.

2. Not promote assumptions to facts without evidence.

3. Surface unresolved assumptions in the eventual handoff's assumptions field so the next run inherits them.

Refreshing a case file

Case files are sealed once built — Craik won't silently rewrite one. To refresh context for a re-run, build a new case file. The old one stays addressable for audit:

Build a new case file for the same task

craik case build task_review_docs
craik case show task_review_docs   # shows the latest by default

Common patterns

"This case file looks thin."

• Check context_budget.docs_excluded — likely an over-aggressive default exclude.
• Confirm memory_backend is configured if you expected memory facts.
• Confirm the GitHub adapter is wired in if you expected issue/PR context.

"This case file is loading too much."

• Add a --discovery-exclude override for the project or this build.
• Mark vendored / generated paths as immutable so they're loaded as evidence (not as mutable docs).
• Check whether assumptions are blowing up the budget — they shouldn't, but pathological cases happen.

What's next

Do nextWrite a handoffClose the loop — turn the case-file context into a continuity record.ReadCase-file conceptThe typed-object view of what you just built.ReferenceLocal state layoutWhere case files persist on disk.