msd-core/get-shit-done/templates/state.md

State Template

Template for .planning/STATE.md - the project's living memory.

---

File Template

# Project State

## Project Summary
[IMMUTABLE - Copy verbatim from PROJECT.md on creation. Never edit this section.]

**Building:** [One-liner from project vision]

**Core requirements:**
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

**Constraints:**
- [Key constraint 1]
- [Key constraint 2]

## Current Position

Phase: [X] of [Y] ([Phase name])
Plan: [A] of [B] in current phase
Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
Last activity: [YYYY-MM-DD] - [What happened]

Progress: [░░░░░░░░░░] 0%

## Performance Metrics

**Velocity:**
- Total plans completed: [N]
- Average duration: [X] min
- Total execution time: [X.X] hours

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |

**Recent Trend:**
- Last 5 plans: [durations]
- Trend: [Improving / Stable / Degrading]

*Updated after each plan completion*

## Accumulated Context

### Decisions Made

| Phase | Decision | Rationale |
|-------|----------|-----------|
| - | - | - |

### Deferred Issues

[From ISSUES.md - list open items with phase of origin]

None yet.

### Blockers/Concerns Carried Forward

[From prior "Next Phase Readiness" sections - issues that affect future work]

None yet.

## Project Alignment

Last checked: [Date or "Project start"]
Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned]
Assessment: [One line summary]
Drift notes: [Details if drift detected, otherwise "None"]

## Session Continuity

Last session: [YYYY-MM-DD HH:MM]
Stopped at: [Description of last completed action]
Resume file: [Path to .continue-here*.md if exists, otherwise "None"]

STATE.md is the project's "short-term memory" that spans all phases and sessions.

Problem it solves: Information is captured in summaries, issues, and decisions - but not systematically consumed. Each phase plans in isolation. Sessions start without knowing accumulated context.

Solution: A single, small file that's:

• Always read first (every workflow)
• Always updated after work (every execution)
• Contains digest of all accumulated wisdom
• Enables instant context restoration

Creation: After ROADMAP.md is created (during init)

• Copy Project Summary from PROJECT.md (immutable after this)
• Initialize empty accumulated context sections
• Set position to "Phase 1 ready to plan"

Reading: First step of EVERY workflow

• progress: Present status to user
• plan: Inform planning decisions
• execute: Know current position
• transition: Know what's complete

Writing: After every significant action

• execute: After SUMMARY.md created
  • Update position (phase, plan, status)
  • Extract decisions → add to table
  • Extract new issues → update deferred list
  • Extract concerns → add to blockers
• transition: After phase marked complete
  • Update progress bar
  • Clear resolved blockers
• alignment-check: After verification
  • Update alignment status

Project Summary (Immutable)

Copied from PROJECT.md on project initialization. Never edited afterward. Provides constant reference to "what are we building" without re-reading full project doc.

Current Position

Where we are right now:

• Phase X of Y - which phase
• Plan A of B - which plan within phase
• Status - current state
• Last activity - what happened most recently
• Progress bar - visual indicator of overall completion

Progress calculation: (completed plans) / (total plans across all phases) × 100%

Performance Metrics

Track velocity to understand execution patterns:

• Total plans completed
• Average duration per plan
• Per-phase breakdown
• Recent trend (improving/stable/degrading)

Updated after each plan completion.

Accumulated Context

Decisions Made: Table of significant decisions with rationale.

• Extracted from SUMMARY.md "Decisions Made" sections
• Include phase number for traceability
• These constrain future phases (e.g., "use jose not jsonwebtoken")

Deferred Issues: Open items from ISSUES.md

• Brief description with ISS-XXX number
• Phase where discovered
• Effort estimate if known
• Helps phase planning identify what to address

Blockers/Concerns: From "Next Phase Readiness" sections

• Issues that affect future work
• Prefix with originating phase
• Cleared when addressed

Project Alignment

Tracks whether work matches original requirements:

• ✓ Aligned: On track
• ⚠️ Drift: Scope creeping or diverging
• ✗ Misaligned: Work doesn't serve project goals

Updated after each phase completion.

Session Continuity

Enables instant resumption:

• When was last session
• What was last completed
• Is there a .continue-here file to resume from

<size_constraint> Keep STATE.md under 150 lines.

It's a DIGEST, not an archive. If accumulated context grows too large:

• Summarize older phase decisions: "Phases 1-2: [key decisions]"
• Reference ISSUES.md instead of listing all: "12 open issues - see ISSUES.md"
• Keep only active blockers, archive resolved ones

The goal is "read once, know everything" - if it's too long, that fails. </size_constraint>

**When created:** - During project initialization (after ROADMAP.md) - Copy Project Summary from PROJECT.md (never edit this section after creation) - Initialize empty sections

When read:

• EVERY workflow starts by reading STATE.md
• Provides instant context restoration
• Shows current position and accumulated wisdom

When updated:

• After each plan execution (update position, extract decisions/issues/blockers)
• After phase transitions (update progress bar, clear resolved blockers)
• After alignment checks (update alignment status)

Size management:

• Keep under 150 lines total
• Summarize older decisions if table grows large
• Reference ISSUES.md instead of listing all issues
• Keep only active blockers, archive resolved ones

Sections:

• Project Summary: Immutable project overview
• Current Position: Where we are now (phase, plan, status)
• Performance Metrics: Velocity tracking
• Accumulated Context: Decisions, deferred issues, blockers
• Project Alignment: Are we on track with original vision?
• Session Continuity: Resume information