/docs-save-context

Save Context - Pre-Compaction State Preservation

Preserve current conversation state and decisions before approaching token limit or natural break point.

Additional Instructions

$ARGUMENTS

---

Objective

Preserve conversation state before compaction or natural break points. Extract decisions made, document current progress, update context files for continuity.

Use when:

• Approaching token limit (compaction warning)
• Natural break point in complex work
• Before switching contexts
• After important architectural decisions

---

Execution

Phase 1: Analyze Current State

Extract from conversation:

Decisions made - What was decided and why, trade-offs considered, alternatives rejected, rationale for approach

Current progress - What's completed, partially done, blocked (and why)

Next steps - Immediate next actions, dependencies to resolve, open questions

Check if feature context already exists in features/[task-name]/ directory.

Gate: Present summary of extracted state to user.

Phase 2: Confirm Context Strategy

Present options based on whether context files exist:

Save context state?

□ Update existing - Append to features/[task-name]/ files
□ Create new - Start fresh context directory
□ Review first - Show extracted state before saving
□ Cancel

If creating new, ask for task name (kebab-case format).

Gate: User must confirm approach and provide task name if needed.

Phase 3: Update or Create Files

If updating existing:

• Append new decisions to context.md with timestamp
• Update "Next Steps" section
• Mark completed tasks in tasks.md
• Add new tasks if discovered

If creating new:

• Create features/[task-name]/ directory
• Generate context.md with current state and decisions
• Generate tasks.md with remaining work checklist

Note: plan.md not needed for context saves (only for feature-plan command).

Gate: All files updated or created successfully.

Phase 4: Report Results

Summarize what was saved: location of files, key decisions captured, tasks marked complete, next steps documented for resuming work

---

File Formats

context.md Format

# [Feature Name] - Context

**Last Updated:** [timestamp]

## Current State

[Where we are in implementation - 2-3 sentences]

## Recent Decisions

### [Decision Title]
**What:** What was decided
**Why:** Rationale and trade-offs
**When:** [timestamp]
**Impact:** What this affects

## Key Files

- `path/to/file.ts` - Purpose and current state
- `path/to/another.ts` - What was changed

## Next Steps

[When resuming work, start here - specific actionable items]

## Open Questions

- Question that needs resolution
- Blocker or dependency

tasks.md Format

# [Feature Name] - Tasks

**Last Updated:** [timestamp]

## Completed
- [x] Task that was finished
- [x] Another completed task

## In Progress
- [ ] Task currently being worked on (50% done)

## Blocked
- [ ] Task blocked by X dependency

## Todo
- [ ] Next task to do
- [ ] Subsequent task

---

Best Practices

• Be specific: Include file paths, function names, line numbers
• Capture why: Decisions without rationale lose value
• Update timestamps: Always update "Last Updated" field
• Mark progress: Move tasks from todo → in progress → completed
• Note blockers: Document what's preventing progress and why

---

Related Commands

• /shavakan-commands:docs-feature-plan - Create comprehensive feature plan from scratch
• /shavakan-commands:docs-update - Update existing context files