| 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
- Enumerate source intent before restructuring (conversation, packet, prior STATE.md).
- Separate facts from assumptions; mark unresolved items
[AMBIGUOUS: x] — ask only when ambiguity blocks progress (<50% clarity).
- Sort every item into exactly one state category per the definitions.
- Write the schema (below). No empty sections — omit a section only if genuinely empty, never fabricate to fill it.
- 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.
