Skip to content
changeloop

/investigate

Audience: coding agents and integration operators. CLI commands and schemas below are system reference, not a user checklist. Users can follow Quickstart.

In plain words: Investigate is an optional research step for when you cannot yet say what should change. You describe the question or the decision you are stuck on. The agent reads the code (it edits nothing in your product) and the harness records what was checked. You get a short report that separates confirmed facts from guesses and ends with one of three verdicts: ready for /change, needs your decision, or not worth changing. If the request is already clear, skip this step and go to /change.

For agents and integrators

Section titled “For agents and integrators”
/investigate <problem or decision> [--compare]

Use this only when you do not yet know enough to write a reliable change agreement. It is the one optional step in the loop, and reaching for it by reflex just adds latency.

Typical reasons to use it:

  • an unknown root cause
  • several approaches with materially different tradeoffs
  • unclear compatibility or migration constraints
  • an unfamiliar brownfield code path
  • an external API whose versioned documentation, success path, or failure behavior has not been read yet

Start from the uncertainty

Section titled “Start from the uncertainty”

Phrase the input as the decision you cannot make, not as a request to implement something:

/investigate why profile updates occasionally overwrite newer data

For an existing change, include its ID and the new question:

/investigate add-profile: should updates use last-write-wins or optimistic locking?

What it produces

Section titled “What it produces”

The agent reads the relevant code and separates its output into:

  • verified, code-grounded facts
  • hypotheses that are not yet proven, each optionally naming the experiments (experimentKeys) that will test it as its next check
  • constraints and affected boundaries
  • options with tradeoffs
  • unknowns that still require a decision from you

That separation is the whole value. A finding presented as a fact and a finding presented as a hunch lead to very different changes, and collapsing them is how bad agreements get written.

It ends with exactly one of:

ready for /change
needs user decision
not worth changing

not worth changing is a legitimate, useful outcome.

The agent starts from claude-foundation investigate --template, keeps the record at openspec/investigations/<id>.json, and runs claude-foundation investigate <record.json> after each evidence batch. The harness discovers and hashes relevant sources, validates fact, hypothesis, and recommendation links, persists compact metrics and no-progress state, and returns EDIT, ASK_USER, or DONE with an exact resume route. Newly discovered sources are acknowledged automatically and stay hashed for freshness; every fact must cite an inventoried source, and the report lists discoveries no fact cites. Open decisions make the conclusion needs user decision, and a settled record with a change intent concludes in the same run. Repeated no-progress asks you only when the repeated step was your decision; sandbox or discovery failures go to the harness.

Each batch produces a readable openspec/investigations/<id>.report.md with the conclusion, reasons, source links, tested hypotheses, alternatives, unknowns, and next decision. The agent writes in your language and shares a short summary with the report link. The JSON record remains compatible. Generated reports are not investigation sources; reporting never starts Change. If report generation fails, research is preserved and the agent resumes generation without presenting an old report as current.

For an investigation prompted by an existing Build or Prove workspace, set the record’s optional activeChange field to that change ID. Source paths then resolve against the active isolated workspace, and the handoff binds its source root, base, and identity. A missing, stale, or unreadable sandbox is the harness’s repair (repair-harness) on the first run, with the same exact record command; it never silently reads the main checkout.

What it may write

Section titled “What it may write”

Investigation is read-only with respect to product code and formal change packets. Its only ordinary agent-owned writes are the JSON record and an optional note under openspec/investigations/; the harness alone writes its state under .foundation/investigations/ and the generated <id>.report.md. Existing authored <id>.md notes are preserved.

Comparison mode

Section titled “Comparison mode”

For genuinely unresolved experience, API, or architecture alternatives, add --compare:

/investigate dashboard filter interaction --compare

This produces 3–5 lightweight, disposable alternatives under .foundation/prototypes/<id>/. In this mode the agent may additionally write only inside that prototype directory — never product code or a formal change packet.

The investigation record uses mode: "compare": each option carries its findings, trade-offs, sources, and prototypePaths, and the agent writes prototypes only at those declared paths. Once concluded, the record’s selection names the chosen option, the reason, and why each other option was rejected; the generated report shows it. When the evidence cannot decide, it asks you rather than picking.

Continue into the agreement with the selection attached:

/change <intent> --prototype-selection <selection-path>

/change summarizes that decision into the proposal and design. It does not treat the selection or its artifacts as evidence. A ready-for-change runtime result also emits a digest-bound handoff. The agent copies it into the semantic draft’s investigation field; Change rejects the binding if the investigation state or any selected source has changed. For an integration, the investigation note records the exact documentation source and version. /change then requires linked success and failure scenarios; an unread or unversioned API is a research boundary, never a guessed contract.