Docs · Reference
Case states
A case moves through a defined state machine. Each transition requires a condition. RESOLVED is the only terminal state — and it requires verified proof.
States
| State | Description | From | To |
|---|---|---|---|
OPEN | Case created. Problem described. | — | INVESTIGATING |
INVESTIGATING | Hypothesis forming. Code being traced. | OPEN | IMPLEMENTING, BLOCKED |
IMPLEMENTING | Fix being applied. Diff in progress. | INVESTIGATING | VERIFYING, BLOCKED |
VERIFYING | Tests run. Evidence collected. | IMPLEMENTING | RESOLVED, BLOCKED, IMPLEMENTING |
RESOLVED | Proof verified. Work closed. | VERIFYING | WATCHLIST, COMPRESSED |
BLOCKED | Waiting on external input or decision. | Any | Previous state |
NEEDS_USER_INPUT | Agent has a question. Execution paused until operator responds. | IMPLEMENTING, VERIFYING | Previous state |
NON_ISSUE | Confirmed not a defect. Closed without a code change. | INVESTIGATING | COMPRESSED |
WATCHLIST | Resolved Work kept warm. Monitored without an active session. | RESOLVED | OPEN (if re-opened) |
WONT_FIX | Intentionally dismissed. Known issue, no fix planned. | Any | — |
COMPRESSED | Memory summarized. Archived for long-term storage. | RESOLVED, NON_ISSUE | — |
State transitions
| From → To | Trigger | Proof required |
|---|---|---|
OPEN → INVESTIGATING | Planning session started | No |
INVESTIGATING → IMPLEMENTING | Plan approved | No — approval is operator intent |
IMPLEMENTING → VERIFYING | Fix applied, diff attached | No — diff is evidence, not yet proof |
VERIFYING → RESOLVED | Proof verified + outcome set | Yes — at least 1 verified proof required |
Any → BLOCKED | Operator marks BLOCKED | No |
BLOCKED → prior state | Operator unblocks | No |
RESOLVED is the only state transition that requires verified proof. All other transitions are operational.BLOCKED decisions
When a Work item is in the BLOCKED state, the operator chooses one of four paths. These are execution-path decisions, not status transitions — each one determines what happens to the run.
| Decision | What it means | Next state |
|---|---|---|
| Resume | Block resolved. Execution continues from prior state. No new session required. | Prior state |
| Skip | Operator explicitly skips the current run. Work item stays open, no session logs a conclusion. Use when a blocker is temporary and a later run should attempt the same work. | OPEN |
| Reject | Operator ends the current execution attempt. The session is logged as rejected. A new session must be started to continue. Use when the proposed plan was wrong or the problem statement needs revision. | OPEN |
| Mark Not Applicable | Operator determines the Work item should not be executed at all. Not the same as closing — the item is archived with a bounded outcome. Use when scope changes make the Work irrelevant. | RESOLVED (outcome: NotApplicable) |
Resume, Skip, and Reject do not require proof. Mark Not Applicable requires an operator note explaining why the Work is no longer relevant — this is stored in the session memory file.
Outcome classification requirement
Before a Work item can transition to RESOLVED, an outcome classification must be set. The outcome describes what was found — not just that the work is done. Valid outcome values:
| Outcome | When to use |
|---|---|
ConfirmedCodeBug | Root cause is a code defect. Fix was applied. |
ConfirmedConfigBug | Root cause is a configuration error. |
ConfirmedDataBug | Root cause is corrupt or unexpected data. |
ConfirmedEnvironmentIssue | External environment (infra, OS, dependencies) caused the issue. |
ConfirmedOperatorError | Issue was caused by operator action. |
ConfirmedHardwareSetupIssue | Hardware or peripheral configuration was the root cause. |
IntendedBehavior | System behaved correctly. Issue was misunderstanding. |
Duplicate | A prior Work item already covers this. |
Unreproducible | Could not reproduce after investigation. |
NeedsProductDecision | Resolution requires a product/design call. Escalated. |
NeedsUserInput | Resolution requires input from an external party. |
Outcome is set during the VERIFYING state, before proof is attached. A Work item with no outcome set cannot transition to
RESOLVED.Side states
Side states interrupt or modify the primary flow without replacing it. They can be entered from any active state and exit back to the prior state (or to a terminal state).
BLOCKED— Work is waiting on a human decision, external dependency, or product question. Operator chooses Resume, Skip, Reject, or Mark Not Applicable.NEEDS_USER_INPUT— agent has a question requiring operator input before continuing. Execution is paused; the run lock is held.
Terminal and archive states
Terminal states are the end of active execution for a Work item. Archive states reduce storage cost without changing the outcome.
| State | Meaning | Distinct from |
|---|---|---|
RESOLVED | Work closed with verified proof and outcome set. | — |
NON_ISSUE | Investigation concluded: the reported behavior is not a defect. No code change. Operator sets this directly after INVESTIGATING. | Distinct from RESOLVED (no proof required) and WONT_FIX (not a judgment call — the issue genuinely does not exist). |
WONT_FIX | The issue is real but the team has chosen not to fix it. Requires an operator note. No proof required. | Distinct from NON_ISSUE (issue exists, just dismissed) and RESOLVED (no fix was applied). |
WATCHLIST | Work was resolved but is kept under observation. Surfaced in the Inbox dashboard. Can be re-opened if a regression is detected. | Distinct from RESOLVED: Watchlist items are active monitors, not archived cases. |
COMPRESSED | Session logs summarized, detailed diffs removed. Entered from RESOLVED or NON_ISSUE. Internal state — not operator-triggered directly. | See Compression section below. |
Compression
Compression is triggered manually or automatically for cases resolved more than 90 days ago. Compressed cases retain final-classification.md and proof references, but detailed session logs are summarized to reduce file size.
Compression is planned — current behavior keeps full session logs. This section reserves the state and describes intended behavior.
API behavior
State transitions are validated server-side. The API returns HTTP
422 if a transition is not allowed.Related: Proof and evidence, Outcomes explained.