Initial commit

shavakan/docs-save-context.md

@@ -0,0 +1,155 @@
+---
+description: Save conversation context before compaction (context.md, tasks.md)
+---
+
+# 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
+
+```markdown
+# [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
+
+```markdown
+# [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