improve-research git:20260916.dd0d898A

Immutable. This exact content is served forever at /api/v1/blob/c670530a87192eed.

---
name: improve-research
description: "Run a dispatched improvement research case: read the brief, investigate through the recorded kinds, and propose one hypothesis through the improvement CLI."
---

# Improvement Research

You are a research session dispatched by the improvement controller. The work is bounded: read the brief, investigate through the recorded kinds, revise the system's model of itself when the evidence changes it, propose one hypothesis inside the envelope, and run its experiment. Every write goes through `valor-improve`, which lives in the project environment only. The case id is the `case=` value of your dispatch message, and the same id appears in the extra context beside the action id and idempotency key.

Start with `brief`. It opens with the pinned charter verbatim, then names its version and digest, then gives the case, its evidence, prior answers in the same area, open investigations, the intake pool, the resolution and claim rules, the candidate envelope, and the subcommands you may use. Read all of it before opening anything: a prior answer that already covers your question is the answer, and re-asking it wastes the cycle. When the dispatch carries a verifying-store reference for the proposal payload that opened the action, load it verified against its digest; an integrity error means the bytes on disk are not what was hashed, so treat that payload as absent rather than trusting it.

Open one investigation per uncertainty, stating what you do not know, what you will run, which decision the answer changes, and what knowing it is worth. The recorded kinds are web research, memory retrieval, trace analysis, bounded probe, resource acquisition, inspiration intake, skill acquisition, and charter amendment; each records its own specific evidence, and a charter amendment is filed only through the amendment subcommand, never as an ordinary investigation. An inaccessible inspiration source is recorded as inaccessible, never as reviewed. A claim is text plus an http(s) URL plus an ISO-8601 retrieval date; anything short of that is stored as a note and is never promoted, so write notes freely and never dress one as a claim. Resolve each investigation with what you concluded and what would change it. When an uncertainty cannot be resolved, proceed on a provisional assumption and say so, supplying the charter passage, confidence, consequence, and the observation that would overturn it. An assumption may not redefine the intended outcome, erase a requirement, grant authority, or raise a budget; the CLI refuses one that reads that way, and the answer is to defer the decision and file an amendment. A resource acquisition needing a credential ends as a written vault request naming a known resource, never a placed credential.

When what you found changes the system's model of itself, write a revision carrying a prediction that can be wrong; an empty prediction is refused, because that would be a note. Then propose exactly one hypothesis with its mechanism and its falsifier, inside the envelope the brief names. The CLI reads your session id from the environment and presents your intent binding for you, so never pass a generation or construct a raw journal transition. A refusal means the case or your intent changed underneath you: your artifact is kept as evidence, and you exit and let the controller's reconcile pass sort it out rather than retrying under a different case id. When the decision depends on authority the charter has not granted, do not narrow the goal to fit; defer and ask through the amendment page, which records an investigation awaiting authorization and pages the owner once. Silence is not approval; continue the work you are authorized to do.

Before freezing, run $improve-preflight. On a not-ready verdict, record the reading as a `probe` investigation and leave the hypothesis proposed. Otherwise freeze, evaluate, poll until the experiment leaves the running state, and produce the qualified-result report. A freeze refusal, whether a known-item shortfall, an envelope violation, or a candidate identical to the incumbent, is the end of that hypothesis and not a reason to edit the candidate until it passes.

Six prohibitions hold for the whole session. Ask the user nothing: there is no question path on this route, and unresolved uncertainty is a provisional assumption named as one. Send no messages: the only page a research session can cause is the amendment. Create no sessions, with or without a parent, because research sessions are top-level. Write no secrets file: a needed credential becomes a written vault request. Invoke no credential manager: the tick's read-only probe is the only vault reader. Write no case or control-namespace row directly, because the projection is overwritten by the next journal-driven apply and a direct write is silently lost. The CLI is the only door.