state-management skill

lastupdated: 2026-03-02T14:30:00Z sessioncount: 12 current_milestone: v1.0

Project State

Current Work

• Phase: 72
• Task: Implement OAuth2 login flow
• Status: executing
• Plan: PLAN-1.md (task 3 of 5)

Completed Phases

• [x] Phase 70: Project setup and scaffolding
• [x] Phase 71: Database schema and migrations

Blockers

• [ ] [HIGH] API key for OAuth provider not configured (@user, 2026-03-01)

Decisions

Quick Tasks

### 2. Update Individual Fields

Update a single field without affecting the rest of the document:

update currentphase -> 73 update currenttask -> "Build API endpoints for user management" update status -> "planning"

Use `Edit` tool to perform surgical updates on specific lines.

### 3. Append to List Fields

Add items to list-type fields:

append completed_phases -> "Phase 72: OAuth2 authentication" append decisions -> { date: "2026-03-02", decision: "Use JWT tokens", rationale: "Stateless auth for API" } append blockers -> { severity: "MEDIUM", description: "Need design mockups", owner: "@designer" }

### 4. Remove from List Fields

Remove items when resolved:

remove blocker -> "API key for OAuth provider not configured"

Mark blockers as resolved rather than deleting (change `[ ]` to `[x]`).

### 5. Quick Tasks Table Management

Add, update, and query quick tasks:

addquicktask -> { number: 3, task: "Update README", status: "pending" } updatequicktask -> { number: 2, status: "done" } queryquicktasks -> { status: "in-progress" }

### 6. Cross-Session Memory

STATE.md persists across context resets. On session start:
1. Read STATE.md to restore project context
2. Increment `session_count` in frontmatter
3. Update `last_updated` timestamp
4. Report state summary to orchestrator

### 7. Decision Log

Structured decision tracking with timestamps and rationale:

### 8. Blocker Tracking

Track blockers with severity and ownership:

• [ ] [HIGH] API key not configured (@user, 2026-03-01)
• [x] [MEDIUM] Design mockups needed (@designer, 2026-02-28) - resolved 2026-03-01

Severity levels: `HIGH` (blocks current work), `MEDIUM` (blocks future work), `LOW` (inconvenience).

## Tool Use Instructions

### Reading State
1. Use `Read` to load `.planning/STATE.md`
2. Parse frontmatter for metadata (last_updated, session_count, current_milestone)
3. Parse markdown sections into structured fields
4. Return parsed state object

### Updating a Field
1. Use `Read` to load current STATE.md
2. Locate the target field/section
3. Use `Edit` with precise old_string/new_string to update only the target
4. Verify edit succeeded by reading the section back

### Appending to Lists
1. Use `Read` to find the end of the target list section
2. Use `Edit` to insert new item at the correct position
3. For tables, append new row before the section break

### Resolving Blockers
1. Use `Read` to find the blocker text
2. Use `Edit` to change `- [ ]` to `- [x]` and append resolution date

## Process Integration

This skill is used by most GSD processes:

- `execute-phase.js` - Update current_task as each task completes, track position
- `verify-work.js` - Add/resolve blockers based on verification results
- `audit-milestone.js` - Read completed_phases for coverage analysis
- `prog

{ "operation": "read|update|append|remove", "field": "currentphase|completedphases|blockers|decisions|quick_tasks", "status": "success|error", "previousValue": "...", "newValue": "...", "stateSnapshot": { "currentPhase": 72, "currentTask": "Implement OAuth2", "completedPhases": [70, 71], "activeBlockers": 1, "quickTasksTotal": 3, "quickTasksPending": 1 } }

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `stateFile` | `.planning/STATE.md` | Path to STATE.md |
| `autoTimestamp` | `true` | Auto-update last_updated on write |
| `autoSessionCount` | `true` | Auto-increment session_count on read |
| `blockerSeverityLevels` | `HIGH,MEDIUM,LOW` | Valid blocker severities |

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| `STATE.md not found` | Planning directory not initialized | Run gsd-tools init first |
| `Section not found` | Unexpected STATE.md format | Rebuild STATE.md from template |
| `Edit collision` | Non-unique text match for edit | Provide more context in old_string |
| `Frontmatter parse error` | Malformed YAML frontmatter | Fix YAML syntax or regenerate |
| `Concurrent modification` | Multiple processes editing state | STATE.md is not lock-protected; serialize access |

## Constraints

- STATE.md must remain human-readable markdown at all times
- Never delete historical entries (blockers, decisions); mark as resolved instead
- Frontmatter must be valid YAML
- Quick task numbers must be sequential
- All timestamps must be ISO 8601 format
- Decision lo