state-management

name	state-management
description	Use when non-trivial work needs durable, bounded project memory across checkpoints or sessions.

State Management

Keep continuation state concise enough to load quickly and precise enough that /sc-status can resume without guessing. Announce use before changing durable memory.

Quick Reference

1. Search before load: read docs/STATE.md and .continue-here.md, then load only artifacts explicitly needed by Next Action.
2. Update Current Position, Next Action, active Blockers, Decisions, and Completed Work.
3. Dedupe before appending. Mark replaced guidance SUPERSEDED by <reference> instead of preserving competing truths.
4. Apply the archive gate: compact when Completed Work exceeds 20 entries, Decisions exceeds 30 entries, or STATE.md exceeds 300 lines; never archive active blockers or the next action.

When to Use

Use when starting, pausing, or completing non-trivial workflow work; recording a durable decision, blocker, deferral, or handoff; or finishing a feature, review, audit, or debugging session. Skip one-off questions, tiny edits, and throwaway experiments.

Route

• For file selection, state templates, errors, and learned conventions, load file contracts.
• For selective restoration, dedupe, superseded entries, quantitative archiving, and session-end compaction, load memory hygiene.
• Load only the branch needed for the current read or write.

Invariants

• Read before writing; keep entries short, dated, scoped, and linked to authoritative artifacts.
• Create only files the work needs. Do not copy BRD, PRD, FSD, issue, or solution contents into state.
• Decisions remain constraints until explicitly reopened. Blockers name owner and required input.
• .continue-here.md is a short pointer, not a second state database.
• Never store secrets, credentials, private data, or full sensitive payloads.
• Preserve useful history through archive links, not unbounded hot memory.

Red Flags

• “I’ll remember,” an ambiguous next action, duplicate entries, contradictory active decisions, or a handoff containing every detail.
• Loading all historical documents before identifying the current route.
• Archiving by intuition while active blockers or unresolved decisions are mixed with closed history.
• Append-only growth without search, consolidation, or provenance.

Integration

Pairs with context-engineering for selective loading, checkpoint-protocol for blockers, executing-plans and issue-workflow for progress, agentic-delivery for BRD→PRD→FSD→GOAL authority, todo-management for deferrals, and pause/status workflows for continuation.