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.
In this repository26 other files it gives its agents.
- AGENTS.mdAGENTS.md
- ai-ready-fixSkill
- ai-ready-scoreSkill
- architectural-analysisSkill
- commitSkill
- deep-reviewSkill
- domain-modelingSkill
- dotnet-efficient-validationSkill
- herdr-orchestrationSkill
- no-workaroundsSkill
- repository-cli-efficiencySkill
- sdd-create-prdSkill
- sdd-create-techspecSkill
- sdd-execute-correctionsSkill
- sdd-execute-taskSkill
- sdd-orchestrate-flowSkill
- sdd-orchestrate-prdsSkill
- sdd-orchestrate-tasksSkill
- sdd-plan-auditSkill
- sdd-plan-correctionsSkill
- sdd-plan-refactoringSkill
- sdd-plan-tasksSkill
- sdd-review-codeSkill
- sdd-triageSkill
- update-nuget-packagesSkill
- writing-agents-mdSkill
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
- Distinctive: line 55
Stabilize: Wait for explorers and processes to finish.
- Distinctive: line 56
Output: no explorer or process running, and all unit state in a durable file.
- Distinctive: line 67
Output: every entry has an ID, tier, triggers, source, and expiry, and none depends on this conversation to be understood.
≈ “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.
Files
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.
| Branch | When | Follow |
| Write | Called alone, by another SDD skill's session pause, or when ContextBrake asks to record progress | The Write steps |
| Load | An SDD skill starts or resumes work on a feature with context-snapshot.md | Read 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 getsstatus: supersededandsuperseded_by, so only one staysactive.
Structure
The template assets/context-snapshot.template.md has four parts, in reading order:
- Header:
status(active,superseded, orclosed),generated,stage(planning,tasks,corrections,review, oracceptance),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(yeswhen the writing session changed code, which the review independence rule needs),git_head,worktree,next_step(skill and unit), andother_eligible. - Load map: the tiers below, so the reader knows when each entry applies before reading entries.
- Next step brief: the
nowtier, written fornext_step. Entries: one line each, in sections
Decisions,Learnings,Code map, andOpen threads, with this shape:- [ID] (when: tier: trigger; trigger) gist — src: path#section; until: conditionID:D-NNdecision,L-NNlearning,M-NNcode map,O-NNopen 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
| Tier | Load when | Examples |
now | At session start, before choosing work | Header, next step brief, open threads waiting on the user |
on-select | After choosing the unit, if a trigger matches its ID, affected files, or traceability IDs | A decision that constrains the ledger API for T04 |
on-edit | Just before editing or creating a path that matches | A WAL read-only quirk for src/TokenHound.Infrastructure/** |
on-run | Just before running a matching command, or right after it fails | A new test project must join TokenHound.slnx before dotnet test runs it |
on-demand | Only when a gist is insufficient; this applies to every src: pointer | The 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
- Resolve the file. Use the feature from
--prdor the one the calling skill names. Called alone without an argument, use the feature this session worked on (atasks/prd-*folder read or written in the conversation); without one, the onlycontext-snapshot.mdwithstatus: active. With several candidates or none, ask which through the host's question tool (AskUserQuestionin Claude Code), offering the existingtasks/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. - 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.
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.
Include Leave out Decisions taken in the session that no durable file records yet, with a pointer to where they should live Anything the PRD, TechSpec, task contract, report, or handoff already states Learnings: codebase conventions, environment quirks, commands that fail and why, approaches tried and discarded Conversation transcript, reasoning narrative, or praise Explorer conclusions still useful for the next step, as path:symbolorpath:lineat the current Git headFile contents, code blocks, diffs, logs, or test output Open threads: pending items, reservation hits, blocks, and questions awaiting the user Secrets, credentials, or user data Prefer promoting a durable decision to its real home (the artifact being written, the task handoff,
Problems and solutionsin the manifest, orworkflow.mdunder 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:nowis for what the next session must know before choosing; most entries belong toon-select,on-edit, oron-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.- 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_headisgit rev-parse --short HEAD,worktreeiscleanor a short count with the changed top-level paths, andauthored_codeisyesif 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 fornext_step. - 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
CRITICALzone, 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.
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
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.

