altshiftstudio/context-snapshot

Context Snapshot

Create one handoff file with the highest-signal context from the current conversation.

Workflow

1. Choose output path

• If the user provides a path, use it.
• Otherwise create handoffs/context-<YYYY-MM-DD-HHMM>.md.
• Create the parent directory if it does not exist.

2. Map territory (MANDATORY)

• Inventory key domains before writing:
  • Goals and success criteria.
  • Decisions and rationale.
  • Constraints and non-goals.
  • Files/artifacts and command outcomes.
  • Risks, blockers, open questions.
• Capture exact wording for non-negotiable decisions and constraints.

3. Score friction and choose depth mode (MANDATORY)

Select one mode:

| Mode | Use when | Depth | | :--- | :--- | :--- | | quick | Estimated conversation size is small and task scope is single-track | Minimal bullets, highest-priority items only | | standard | Typical multi-step task with moderate context | Full template, balanced detail | | forensic | Large context, contradictions, or high-risk decisions | Full template plus contradiction/TODO tracking |

4. Respond by mode

Extract only what a new agent needs to continue safely:

• User goals and success criteria.
• Decisions and rationale.
• Constraints, assumptions, and non-goals.
• Files touched or referenced.
• Commands run and key outcomes.
• Open questions, risks, and blockers.
• Current status and next steps.

5. Write the handoff file

• Copy context-template.md into the output path.
• Fill every section.
• If a section has no data, write None.
• Add source: tags to major claims, decisions, blockers, and next steps.
• Example: - API key rotation blocked by IAM policy (source: command output, aws iam get-role)

6. Validate before finishing

• Keep facts concrete and traceable to the conversation.
• Keep paths, commands, and identifiers exact.
• Remove low-signal narrative and duplicate points.
• Ensure next steps are actionable and ordered.
• Mark uncertainty with TODO instead of guessing.
• Set confidence level: high, medium, or low.

Critical Rules (MANDATORY)

• Prioritize fidelity over prose.
• Preserve exact phrasing for decisions and hard constraints.
• Separate facts from assumptions using explicit labels.
• Include concrete dates when timing matters.
• Do not omit failed attempts if they affect next steps.
• Keep output concise but complete; use bullets.

Forbidden Behaviors

• Do not invent decisions, rationale, owners, or outcomes.
• Do not silently resolve conflicting statements.
• Do not omit blockers just because they are unresolved.
• Do not rewrite critical commitments into generic language.
• Do not output only narrative text when structured fields are required.

Confidence Gate

• high: No material contradictions; next steps are executable.
• medium: Minor uncertainty; TODO items are explicit.
• low: Major gaps or contradictions; list blocking questions before handoff.

Compression Heuristics

• Keep only information needed for safe continuation.
• Remove conversational filler and repeated explanations.
• Merge related updates into one state description.
• Preserve irreversible decisions and unresolved risks.