Skill: structuring state for AI agent decisions

Write the state snapshot every agent decision reads, with goal, evidence and gaps, and write each action's real result back before the next call.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

Every decision in a Jev Engineering build reads the same thing: the current state. In the creator's loop, state is the text or JSON describing the agent's current situation, and the decision model evaluates that state against typed questions and returns decisions with probabilities. Whether the question is which worker to pick, whether a tool call is risky, or whether to escalate, the answer can only be as good as the snapshot it was asked about. This skill is about writing that snapshot well and keeping it true.

The canonical guidance is short: to define a decision, write the current state, including the goal, the work already completed, the available evidence, and the missing information. Each field earns its place. The goal lets a question judge relevance instead of guessing intent. Completed work stops the agent from repeating steps it already took. Evidence gives the decision something concrete to ground on. Missing information makes uncertainty explicit, so a decision can choose to gather more or escalate rather than fill the gap with a confident guess.

This is a different habit from feeding a model the whole conversation. A write-up of Diogo Almeida's design notes criticises how existing agent architectures lean on append-only interaction history, and argues for making system state explicit and typed, with context assembled dynamically through a visibility ladder. In practice that means state is a maintained record with named fields, rebuilt or updated by code, not a transcript that grows until it is too long to reason over.

The second half of the skill is freshness. After a tool runs, the system should record what the tool actually did, including failures, and update the state before the next decision. Leaving state stale after an action is a named mistake in the same source, because the next decision then reasons about a world that no longer exists.

The outputs you should have when you finish are concrete: a schema for the snapshot, a function in code that builds it from your task record and tool results, and a write-back step that runs after every action. You can tell the structure is failing when decisions repeat work already done, contradict the last tool result, or cannot be explained by reading the snapshot they were given. If a reviewer needs the chat log to understand why a decision went the way it did, the snapshot is missing something.

How It Works

State sits at the centre of the loop the creator recommends reusing: State, Questions, Action, Verify. The fuller operational sequence in the same source is to capture state, ask independent questions, route work from the answers, apply an action gate, execute the action, verify the result, and write the result back into state. The snapshot is both the input to the first step and the thing the last step updates, which is why it behaves like a cycle rather than a pipeline.

flowchart LR
  A[Capture state] --> B[Ask questions]
  B --> C[Route and gate]
  C --> D[Execute action]
  D --> E[Verify result]
  E --> F[Write back to state]
  F --> A

Capture. Code assembles the snapshot from sources of truth: the task record, the goal as the user or upstream system stated it, prior tool results, and any retrieved documents. The model does not remember state between calls; the harness owns it. The core fields are the four named in the canonical guide: goal, completed work, evidence, and missing information. Add identifiers and whatever flags your action gate needs, such as the current permission scope.

Ask. One snapshot can feed several questions at once. The creator notes that one state snapshot can support routing, risk, and relevance decisions. That only works if the snapshot carries everything each of those questions needs, so design the schema against the full set of decisions that read it, not the first one you wrote.

Gate and execute. The decision returns a typed answer and a probability, and application code checks permissions and validates arguments before invoking a tool. State matters here too: the gate reads fields such as the actor's scope or the target resource from the snapshot, so a wrong or missing field becomes a wrong gate outcome.

Verify and write back. After execution, code records what the tool actually did, not what was proposed, including errors and partial results, and updates the snapshot before the next decision. Completed work grows, evidence gains the new result, and missing information shrinks or changes. If verification fails, that failure is itself evidence and belongs in state.

Scope what each decision sees. The design-note write-up describes assembling context through a visibility ladder rather than exposing everything to every call. A practical reading is to keep one canonical state record and derive per-decision views from it: the routing question sees the goal and summary evidence, while a risk question also sees the exact arguments of the proposed call. The canonical record stays complete; the views stay small.

Keep it replayable. An evaluation round works best when its input is the observed state snapshot together with the questions, permitted choices, threshold, and versions. Storing each snapshot next to the decision it produced lets you replay a bad call exactly, which is only possible if state is an explicit object rather than a scattered history.

Step-by-Step Guide

Step 1: Inventory the decisions that read state

List every decision point in one agent run: worker or tool choice, retry versus stop, risk checks, escalation. For each, write down what a careful human would need to see to answer it. The union of those lists is the first draft of your snapshot schema. Decisions that need information you do not currently capture are the gaps to fix first.

Pro tip: Do this from a real logged run rather than from memory, since decisions hidden inside prompts are easy to forget.

Step 2: Define the core schema

Create a typed structure with the four canonical fields: goal, completed work, available evidence, and missing information. Add stable identifiers for the task and run, and any fields the action gate reads, such as permission scope or target resource. Give each field a type and a short description so both code and reviewers know what belongs there. Keep free text for places where meaning genuinely varies, and use enums or lists where values are known.

Pro tip: Write the missing-information field as a list of specific unknowns, for example 'customer plan tier' rather than 'more context needed'.

Step 3: Build the snapshot in code from sources of truth

Write a function that assembles the snapshot from the task record, tool results and retrieved documents each time a decision is due. The harness owns this function; no model is asked to recall or reconstruct state. Pull values from the system that is authoritative for them, such as the ticket store for status or the tool log for what ran. This makes the snapshot reproducible and keeps a hallucinated summary from becoming the ground truth.

Step 4: Derive scoped views for each decision

Keep one canonical record, then produce a smaller view for each decision that shows only the fields it needs. A routing question may need the goal and a summary of evidence, while a risk question needs the exact proposed arguments. Smaller views are easier to audit and less likely to distract the decision with irrelevant detail. Document which fields each view includes so changes to the schema do not silently starve a decision.

Pro tip: If several independent questions share the same view, send them against one snapshot so they agree on the facts.

Step 5: Write the real result back after every action

After a tool runs, record what it actually did: output, errors, partial success, and the verification outcome. Append that to completed work and evidence, and update the missing-information list. Do this before the next capture step, not in a background job that might lag. A failed call is recorded as a failure, not dropped, because the next decision needs to know the approach did not work.

Pro tip: Write back the executed arguments, not the proposed ones, since the gate may have rejected or altered them.

Step 6: Store snapshots with their decisions

Persist each snapshot alongside the questions asked, the answers and probabilities returned, the threshold applied, and the model and question versions. This lets you replay a single bad decision with exactly the input it saw. It also lets you check later whether a wrong decision came from the model or from a snapshot that was wrong or incomplete. Without this record, debugging falls back to guessing from chat logs.

Pro tip: Hash or version the schema itself so you can tell which snapshot shape a stored decision was made against.

Best Practices

• Treat the snapshot as a maintained record, not a transcript. Rewriting fields as facts change keeps it short and current, while appending every turn buries the current situation under history, which is the pattern the design-note write-up warns against.
• Make missing information explicit and specific. When unknowns are named, a decision can choose to gather data or escalate; when they are absent, the decision tends to assume the gap away and answer confidently.
• Let code, not a model, own state updates. A model may draft a summary that goes into the evidence field, but the harness decides what is written and when, so the record stays tied to what tools actually did.
• Design the schema against every decision that reads it. Because one snapshot can feed routing, risk and relevance questions together, a field added for one question often unblocks another; designing per question leads to several drifting snapshots.
• Record failures as first-class evidence. A retry-versus-stop or change-approach decision cannot work if the snapshot only lists successes.
• Keep gate inputs in structured fields. Permission checks and argument validation run in application code, so the fields they read should be typed values, not phrases buried in free text.

Common Mistakes

• Leaving state stale after an action, so the next decision reasons about a world that no longer exists, a failure the creator calls out directly.: Run the write-back step synchronously after every execution and before the next capture. Add a check that refuses to ask a question if the snapshot is older than the last recorded action.
• Writing back the proposed action instead of what actually ran, which hides gate rejections, altered arguments and partial failures.: Record the executed call, its real output and any error from the tool runner. The proposed action can be logged separately for analysis but should not stand in for the outcome.
• Passing the full conversation history as state and hoping the decision finds the relevant parts.: Extract the goal, completed work, evidence and missing information into named fields as the canonical guide describes. Keep the transcript in storage for audit, not in the decision input.
• Omitting the missing-information field, so every snapshot looks complete and decisions never choose to gather more or escalate.: Require the field, allow it to be an empty list only when you have checked, and write unknowns as concrete items the agent could look up.
• Letting each decision build its own ad hoc context, so routing and risk checks disagree about basic facts.: Build one canonical snapshot per step and derive scoped views from it. Independent questions then read the same facts and their answers can be compared.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: Jev Engineering

Related Skills

• Benchmarking and Observing Agent Loops
• Formulating Atomic Decision Questions
• Separating Generation from Decision-Making
• Designing Routing and Ranking Policies
• Batching and Parallelizing Decisions
• Enforcing Deterministic Execution Boundaries
• Calibrating Confidence Thresholds and Escalation Paths

Sources

• What is Jev Engineering?
• Tony Bai
• Jev demos and threads on X: 239 posts with video
• Where does Jev fit in an AI agent loop? - Vercel

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.