agentleFS
dougcunhadougcunha/TokenHound/.agents/skills/sdd-snapshot/SKILL.md

sdd-snapshot

Skill3 starsChanged 36 days agoMITView on GitHub

SDD snapshot for writing, updating, or loading a session's distilled context in tasks/prd-[slug]/context-snapshot.md. Use when saving what the session learned before pausing or clearing the context, including when ContextBrake asks to record progress, or when resuming a feature that has a snapshot. Don't use for the flow checkpoint, task handoffs, or SDD artifacts.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Stabilize: Wait for explorers and processes to finish.

    line 55
  2. Distinctive:

    Output: no explorer or process running, and all unit state in a durable file.

    line 56
  3. Distinctive:

    Output: every entry has an ID, tier, triggers, source, and expiry, and none depends on this conversation to be understood.

    line 67

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

SDD snapshot

The snapshot carries what one session learned into the next, limited to what the next step needs. It is a routing table for context: a few inline facts that exist nowhere else, plus pointers that say when to load each durable source. It is a hint, never an authority: the PRD, TechSpec, manifest, task files, handoffs, reports, checkpoint, and code win on conflict, and the diverging entry is dropped.

BranchWhenFollow
WriteCalled alone, by another SDD skill's session pause, or when ContextBrake asks to record progressThe Write steps
LoadAn SDD skill starts or resumes work on a feature with context-snapshot.mdRead references/load.md in full and apply its protocol

Location

  • Skills scoped to one feature: tasks/prd-[slug]/context-snapshot.md. Every stage of that feature (planning, tasks, corrections, review) rewrites the same file.
  • Skills that span several features (sdd-orchestrate-prds, sdd-plan-audit): the folder of the next feature to work on, creating the folder with only the snapshot when it does not exist yet. The previous snapshot of the same run gets status: superseded and superseded_by, so only one stays active.

Structure

The template assets/context-snapshot.template.md has four parts, in reading order:

  1. Header: status (active, superseded, or closed), generated, stage (planning, tasks, corrections, review, or acceptance), stage_source (the manifest, report folder, or map the stage works from), covers_through (last completed unit of that stage: task ID, artifact, or report), authored_code (yes when the writing session changed code, which the review independence rule needs), git_head, worktree, next_step (skill and unit), and other_eligible.
  2. Load map: the tiers below, so the reader knows when each entry applies before reading entries.
  3. Next step brief: the now tier, written for next_step.
  4. Entries: one line each, in sections Decisions, Learnings, Code map, and Open threads, with this shape:

    - [ID] (when: tier: trigger; trigger) gist — src: path#section; until: condition

    • ID: D-NN decision, L-NN learning, M-NN code map, O-NN open thread. IDs stay stable across regenerations so other entries and handoffs can cite them.
    • when: the load tier plus its triggers. Triggers are task or finding IDs (T04, CR-03), path globs (src/TokenHound.Infrastructure/**), traceability IDs (DEC-04, FR-17), stages (review), commands (dotnet test), or events (on failure: MSB3027).
    • src: where the full detail lives, loaded only when the gist is not enough. — when the gist is the only record.
    • until: when the entry expires (T06 done, DEC-18 replaced, next session). Expired entries are dropped on the next write.

One line per entry keeps selective loading cheap: Grep on when:.*T04 or on a path fragment finds the entries for a unit without reading the rest.

Load tiers

TierLoad whenExamples
nowAt session start, before choosing workHeader, next step brief, open threads waiting on the user
on-selectAfter choosing the unit, if a trigger matches its ID, affected files, or traceability IDsA decision that constrains the ledger API for T04
on-editJust before editing or creating a path that matchesA WAL read-only quirk for src/TokenHound.Infrastructure/**
on-runJust before running a matching command, or right after it failsA new test project must join TokenHound.slnx before dotnet test runs it
on-demandOnly when a gist is insufficient; this applies to every src: pointerThe previous review's finding text

An entry without a matching trigger is not loaded for the unit. The reader decides per tier, not once: new triggers fire as the work reaches new paths, commands, or failures.

Write

  1. Resolve the file. Use the feature from --prd or the one the calling skill names. Called alone without an argument, use the feature this session worked on (a tasks/prd-* folder read or written in the conversation); without one, the only context-snapshot.md with status: active. With several candidates or none, ask which through the host's question tool (AskUserQuestion in Claude Code), offering the existing tasks/prd-* folders; a new slug creates the folder with only the snapshot. An existing file is updated; a missing one is created from the template, read in full. Output: one resolved path, and whether the write updates or creates it.
  2. Stabilize. Wait for explorers and processes to finish. Write with the unit recorded (artifact written, task moved, manifest or map consistent); with a unit in progress, the common case when ContextBrake asks, first record its partial state and open items in its handoff. Output: no explorer or process running, and all unit state in a durable file.
  3. Distill. Start from the previous snapshot, if any. Drop each entry that expired, was superseded, contradicts current sources, or was promoted to a durable file the next step will read anyway; keep the IDs of surviving entries. Add what this session produced, writing each gist so it is actionable without the conversation: the fact and its consequence, not the story.

    IncludeLeave out
    Decisions taken in the session that no durable file records yet, with a pointer to where they should liveAnything the PRD, TechSpec, task contract, report, or handoff already states
    Learnings: codebase conventions, environment quirks, commands that fail and why, approaches tried and discardedConversation transcript, reasoning narrative, or praise
    Explorer conclusions still useful for the next step, as path:symbol or path:line at the current Git headFile contents, code blocks, diffs, logs, or test output
    Open threads: pending items, reservation hits, blocks, and questions awaiting the userSecrets, credentials, or user data

    Prefer promoting a durable decision to its real home (the artifact being written, the task handoff, Problems and solutions in the manifest, or workflow.md under the flow) and keep only a one-line gist plus pointer here. Give each entry the narrowest tier and triggers that still catch every case where it matters: now is for what the next session must know before choosing; most entries belong to on-select, on-edit, or on-run. Keep the file under 8 KiB; when it grows past that, prune before adding. Output: every entry has an ID, tier, triggers, source, and expiry, and none depends on this conversation to be understood.

  4. Rewrite the brief and header. The next step brief says why it is next, the skill and unit, the minimal sources to read first, known change points, and the entry IDs that apply; when several units are eligible, name the recommended one and list the others. In the header, git_head is git rev-parse --short HEAD, worktree is clean or a short count with the changed top-level paths, and authored_code is yes if this session changed code since the last review, otherwise it carries the previous value until a review covers it. Output: header with current values and a brief written for next_step.
  5. Write and verify. Replace the whole file, then reread it to check the header and that every src: path exists. Finish by reporting path and size and printing the resume command; under the session pause, they go into its message, once. When the write answers a ContextBrake request, end the reply with [REQUEST_SESSION_RESET]. Output: the next session can pick the next unit, knows which entries apply to it and when, and has the command to start.

Resume command

Alone in a code block, ready to paste after /clear or in a new session: the host's invocation prefix (/ in Claude Code, $ in Codex), the skill, and the arguments of its argument-hint filled with current values, with no placeholders. The skill is sdd-orchestrate-flow when the feature folder has a checkpoint.json that is not completed; otherwise, the skill in next_step. Example: /sdd-orchestrate-flow --prd shop-01-checkout.

Failures

  • In the CRITICAL zone, ContextBrake asks for the snapshot immediately: write it right away, without finishing the unit in progress, after recording its partial state in its handoff.
  • A failed write leaves the previous version intact; report the error instead of announcing a ready snapshot.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.