state-architect

name

state-architect

description

Create, refactor, or maintain STATE.md per the STATE.md-architect doctrine. Use whenever the user says "create state", "update state", "save state", "/state", "refactor STATE.md", when memory-consolidate Phase 3 writes project state, or when session context must be captured as living project state (NOT a session handoff — that is context-transference's job). Writes to $SIA_STATE_PATH from config/env.conf.

State Architect

STATE.md = living project state, doctrine schema, overwritten in place at $SIA_STATE_PATH. NOT a carry-packet: packets (context-transference / imi-state output, in $SIA_PACKET_DIR) are one-shot session handoffs with a foreign-receive contract — consumed once, never maintained. Never merge the two.

Definitions (exact — do not blur)

Goal = the outcome defining success. Constraints = hard limits that must be followed. Preferences = guidance, not requirements. Tasks = concrete actions toward the goal. In-progress = started, unfinished. Blocked = cannot continue + stated reason. Key Decisions = choices already made that bind future work + why. Next Steps = immediate ordered actions. Critical = high-impact/urgent. Completed = finished. Verified = finished AND checked, with the evidence cited.

Procedure

1. Enumerate source intent before restructuring (conversation, packet, prior STATE.md).
2. Separate facts from assumptions; mark unresolved items [AMBIGUOUS: x] — ask only when ambiguity blocks progress (<50% clarity).
3. Sort every item into exactly one state category per the definitions.
4. Write the schema (below). No empty sections — omit a section only if genuinely empty, never fabricate to fill it.
5. Draft, then re-read as an independent pass; fix gaps before delivering.

Schema

# STATE.md
## Goal / ## Constraints / ## Preferences
---
## Tasks / ## In-progress / ## Blocked (— Reason:) / ## Key Decisions (— Reason:)
## Next Steps (numbered, done-conditions) / ## Critical / ## Completed / ## Verified (cite evidence)

Non-negotiables

Goal is an outcome, not a task list · Constraints ≠ Preferences · Blocked always has a Reason · Key Decisions always have a why · Completed NEVER implies Verified · Verified cites its artifact · Source intent preserved, never softened · Missing required info → ask, don't invent · Uncertainty marked, never masked with confidence.

Failure modes — do NOT use when

• The output is a session handoff for a fresh instance → context-transference/imi-state skill instead.
• Mid-task with no boundary — half-states are fiction.
• To log events — that's the ledger; STATE.md holds state, not history.

Full source doctrine (positional scaffold, technique gate, signal/activation matrix — navigator-layer material for prompt refactoring): references/doctrine.md. Read only when refactoring the doctrine itself or building prompts from it, not for routine state writes.