World State Tracking

World State Tracking

Keep a single dedicated state file that records the shape of the running task — the goal, the decisions, the blockers, the next step, the key paths. Unlike the conversation history, this file is structured, finite, and survives compaction. It is the agent's answer to "where are we?" when the context window is full.

When to use

Activate when any of these is true:

• The task is long enough that the agent has lost the thread at least once already.
• The user asks "where are we?", "what's the status?", "are we still on track?", or "remind me what we decided".
• You are about to apply context-pressure-compact (the state file is what survives it).
• The task has 3+ open decisions whose rationale you don't want to re-derive every turn.
• Multiple sub-agents (or the user and the agent) need a shared ground truth.

When NOT to use

• A short task (< 5 turns, no major decisions yet). The state file is overhead.
• The whole task fits in a todowrite. Use that instead — it is already structured state.
• The state would duplicate information that lives in source files (e.g. the migration plan already lives in docs/migrations/auth.md; do not restate it here).

Process

1. Pick a single, predictable path. Default: .minimax/state/<YYYY-MM-DD>-<short-id>.md (or, for repos without a working dir, a tmp file under /tmp/). The path is part of the contract — re-read it from the same place every turn.

2. Initialise the file the first time you activate this Skill. Use this exact shape:

   # World State — <short task name>
   
   **Started**: <ISO date>
   **Owner**: <agent name or "main">
   **Last updated**: <ISO timestamp>
   
   ## Goal
   
   <one paragraph, in the user's own words, copied from the original request>
   
   ## Current phase
   
   <one of: scoping | planning | executing | verifying | blocked | done>
   
   ## Decisions (with one-line rationale)
   
   - <decision> — <reason>
   - <decision> — <reason>
   
   ## Done
   
   - [x] <step + result + key file path or identifier>
   - [x] <...>
   
   ## In progress
   
   - [ ] <step + where you stopped + the next concrete sub-step>
   
   ## Blockers / open questions
   
   - <question that, if answered, would unblock the next step>
   
   ## Next concrete step
   
   <one verb-first sentence — "Edit X to add Y", "Run Z and report output", etc.>
   
   ## Key file paths
   
   - /abs/path/that/the/next/turn/will/need
   

3. Update the file at every meaningful boundary, not every turn. Boundaries are:

   • End of a todowrite step.
   • End of a sub-task handed to a task call.
   • Right before a context-pressure-compact.
   • Immediately after a user redirection. At each update: bump Last updated, move items between Done / In progress, add new Decisions, and refresh the Next concrete step.

4. On every new turn, read the file first (use read). It is your 30-line ground truth. Do not skim the conversation history to "get back up to speed" — read the state file.

5. At context-pressure-compact time, the state file is what survives — the noisy middle does not. The compact summary should reference the state file by path, not duplicate its contents.

Output contract

The user sees:

• The path to the state file (one line, at the top of any meaningful response).
• On request: a short, complete snapshot of the state (the file contents, optionally abbreviated).
• On update: a one-line "State updated: ".

Example

# World State — Auth refactor (OIDC alongside SAML)

**Started**: 2026-08-23
**Owner**: main
**Last updated**: 2026-08-23T23:55:00Z

## Goal

Refactor the auth subsystem to support OIDC as a first-class provider alongside the existing
SAML path, without breaking any of the 12 existing SAML tests.

## Current phase

planning

## Decisions (with one-line rationale)

- Keep SAML on the legacy code path; OIDC gets a parallel module. — SAML contract is frozen,
  no test budget to re-validate.
- Reject "generic Provider with config-driven dispatch" — too much config surface for
  marginal benefit.
- Use the `openidconnect` crate (not hand-rolled oauth2). — JWKS, PKCE, state, nonce all
  solved; saves ~400 lines.

## Done

- [x] Mapped current auth flow in `src/auth/`. Wrote findings to `.minimax/snapshots/auth-flow.md`.
- [x] Confirmed test coverage: 12 of 14 files have unit tests (2 missing: `logout`, `session`).

## In progress

- [ ] Drafting the `OidcProvider` trait. Stopped at: how to represent the provider enum
  vs the existing `IdP` interface. Three options on the table; see Open questions.

## Blockers / open questions

- Should the OIDC module own token storage, or reuse the existing session store?
- Does IT have a preferred OIDC library? (defaulting to `openidconnect`)

## Next concrete step

Draft the `OidcProvider` trait + one impl for `provider = "okta"`, then show the diff to
the user before touching `src/auth/callback.rs`.

## Key file paths

- /repo/src/auth/idp.rs
- /repo/src/auth/callback.rs
- /repo/tests/auth/
- /repo/docs/auth.md

Common pitfalls

• Do not put prose in the state file. Prose is what the conversation history is for. The state file is structured, finite, and machine-grepable.
• Do not update on every turn. Update at boundaries. A state file that changes every line is just a noisy transcript.
• Do not duplicate source-of-truth info. If the API contract lives in docs/api.md, the state file says "see docs/api.md", not "the API contract is ...".
• Do not let the state file grow unbounded. A 500-line state file is no longer a state file; it is a journal. If it grows past ~80 lines, split it (e.g. state.md + decisions.md) or compact.
• Do not forget the path. If you can name the path from memory every turn, the state file is doing its job. If you cannot, move it to a more obvious place.
• Do not use the state file as a substitute for todowrite. The state file is the long-form ground truth; todowrite is the short-form live checklist. They coexist.

Verification checklist

• Is the state file at a single, predictable path the agent can name from memory?
• Is it initialised with the full 9-section shape on first activation?
• Is it updated at boundaries (steps, sub-tasks, compactions, redirections), not every turn?
• Does every new turn start with read of the state file, not a conversation skim?
• Is the state file < ~80 lines? If not, split or compact.
• Does context-pressure-compact reference the state file by path, not duplicate it?
• Can a new sub-agent orient itself in < 30 seconds by reading only the state file?