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. Case closed. | VERIFYING | — |
BLOCKED | Waiting on external input or decision. | Any | Previous state |
COMPRESSED | Memory summarized. Archived. | RESOLVED | — |
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.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
BLOCKED— case is waiting on a human decision, external dependency, or product question.NEEDS_USER_INPUT— agent has a question requiring operator input before continuing.COMPRESSED— resolved case memory has been summarized for storage efficiency.
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.