stn.
Get Started Free

Episodes & bugs

Episodes and bugs capture the work itself — the arc of a task, and the bugs you hit along the way. Both are durable, team-visible memory, both are searchable forever, and both can be written by you or by your coding agent. They're the highest-reuse, least- recorded knowledge on most teams.

Episodes

An episode is the arc of one non-trivial unit of work: what you planned, what actually happened, the result, and the surprise — the gap between plan and reality, which is usually the real learning. Open one when you start something worth narrating; close it when it's done.

stn episode start "Migrate the job queue to Postgres advisory locks" \
    --plan "drop Redis; expect lower infra cost, unknown lock contention" --team TEAM
stn episode close ID --did "swapped the queue, kept Redis for pub/sub" \
    --result "infra bill down ~30%" --surprise "advisory locks needed a connection-pool tweak"
stn episode abandon ID            # stop an open episode — it stays private, never shared
stn episode show ID               # the full arc: plan → outcome → result → surprise
stn episode confirm ID            # confirm an agent-asserted outcome/result (clears pending)

List them:

stn episodes                      # a team's episodes, most recent first
stn episodes --open --mine        # only your open episodes
stn episodes --pending            # only episodes awaiting confirmation

Private until closed. While an episode is open it's working state, visible only to you (like a checkpoint). Closing it promotes it to durable, team-visible memory — the same shape as a decision. Abandoning it leaves it private; it never became shared memory.

It pulls work in. Checkpoints, decisions, and bugs you record while an episode is open auto-attach to it, so the episode reads as the whole story rather than scattered records. Reserve episodes for a genuine multi-moment arc — a one-off decision or bug stands on its own and simply links in.

Bugs

A bug is a first-class symptom → cause → fix → where record. It's the knowledge a teammate (or an agent) most wants months later — "did anyone hit this before, and how did they fix it?" — and the knowledge almost nobody writes down. Recording it once makes it searchable forever.

stn bug add "cp1252 UnicodeEncodeError when printing the feed on Windows" \
    --cause "console encoding not forced to utf-8" \
    --fix "wrap stdout in a utf-8 writer at startup" --where "cli/main.py"
stn bug add "..." --episode ID    # attach to an episode (defaults to the open one)
stn bug fix ID "the fix" --cause "the root cause"   # mark an open bug fixed
stn bug show ID                   # the full record: symptom → cause → fix → where
stn bug confirm ID                # confirm an agent-asserted cause/fix (clears pending)

List them:

stn bug list                      # a team's bugs, most recent first
stn bug list --open               # only unfixed bugs
stn bug list --episode ID         # only bugs from one episode
stn bug list --pending            # only bugs awaiting confirmation

Team-visible from the start. Unlike a private checkpoint, a bug is shared the moment you record it — the value is cross-person. Pass --fix and it lands fixed; omit it and it stays open until someone runs stn bug fix. --where is free text (a file, commit, or area) that also links the bug into the context graph.

The agent review loop

When a coding agent closes an episode or files a bug, the asserted parts — an episode's outcome and result, a bug's root cause and fix — can land pending under an org that requires review (the intent and the symptom always land live). Review what your agents recorded with stn episodes --pending or stn bug list --pending, then stn episode confirm ID / stn bug confirm ID to make it part of the team's permanent record. This is the same human-curates-agents loop as decisions.