= STATE Usage Guide
:toc: left
:toclevels: 3
:source-highlighter: highlight.js

This guide explains how to use STATE for AI conversation continuity.

== Workflow Overview

The STATE system follows a simple download/upload cycle:

. *End of session:* Export STATE.scm and download it
. *Start of new session:* Upload STATE.scm to resume
. *During session:* STATE is tracked in memory
. *Repeat:* Export updated STATE at end

== Quick Reference

=== End of Conversation Commands

Tell Claude:

----
"Create STATE checkpoint for next session"
"Export my state file"
"Prepare handover for next conversation"
----

=== Start of Conversation

Upload your STATE.scm file and say:

----
"Continue from this state"
"Load my state and resume"
"Here's my STATE file, pick up where we left off"
----

== Editing STATE.scm Manually

STATE.scm is human-readable and can be edited in any text editor.

=== Safe to Edit

* `blockers` - Add new obstacles you've discovered
* `next` - Add immediate TODO items
* `context-notes` - Add reminders for next session
* `completion` - Update if you made offline progress

=== Avoid Editing

* `dependencies` - Complex relationships, let Claude manage
* `status` - State transitions have implications
* `metadata` - Auto-generated, don't modify

=== Example Edit

Before:

[source,scheme]
----
(blockers . ("LLVM backend not started"))
----

After:

[source,scheme]
----
(blockers . ("LLVM backend not started" "Need to research inkwell crate"))
----

== Query Examples in Guile REPL

Start Guile and load the state:

[source,bash]
----
guile
----

[source,scheme]
----
(load "STATE.scm")
(load "state-queries.scm")
(load "examples/example-state.scm")
----

=== Basic Queries

[source,scheme]
----
;; What's my current focus?
(query-focus state)
;; => "Oblibeny"

;; What projects are blocked?
(query-blocked-projects state)
;; => (("My Language Solo" "Waiting for Oblibeny parser") ...)

;; Get all in-progress projects
(get-in-progress-projects state)

;; Get critical next actions
(get-critical-next state)
----

=== Dependency Analysis

[source,scheme]
----
;; What depends on Oblibeny?
(query-dependents "Oblibeny" state)
;; => Projects that will unblock when Oblibeny is done

;; Full dependency chain
(transitive-dependents "Oblibeny" state '())

;; How many projects are blocked by Oblibeny?
(blocking-impact "Oblibeny" state)
;; => 3

;; Get prioritized project list
(prioritized-projects state)
----

=== Status Analysis

[source,scheme]
----
;; Projects nearly complete (>= 80%)
(query-nearly-complete state)

;; Projects just started (<= 20%)
(query-just-started state)

;; Get projects by category
(query-by-category "language" state)

;; Average completion across all projects
(total-completion state)
----

=== Reports

[source,scheme]
----
;; Generate full status report
(generate-status-report state)

;; Check if checkpoint needed
(should-checkpoint? state)
;; => #t if messages running low
----

== File Organization

Recommended directory structure for STATE files:

----
~/claude-sessions/
   STATE.scm              <- Current/latest state
   archive/
     STATE_2025-12-05.scm <- Previous sessions
     STATE_2025-12-04.scm
     STATE_2025-12-03.scm
----

== Troubleshooting

=== "Claude doesn't seem to remember my state"

Make sure you:

. Downloaded STATE.scm at end of previous session
. Uploaded it at start of new session
. Told Claude to load/continue from the state

=== "STATE.scm won't parse"

Common issues:

* Mismatched parentheses - count `(` and `)`
* Missing dots in pairs - should be `(key . value)`
* Unescaped quotes in strings

Fix: Load in Guile to see error message:

[source,bash]
----
guile -c '(load "STATE.scm")'
----

=== "My completion percentages are wrong"

Claude estimates completion during conversations. To correct:

. Edit STATE.scm manually
. Update `(completion . XX)` for affected projects
. Upload corrected version next session

=== "I lost my STATE.scm"

Recovery options:

. Check browser downloads folder
. Look for handover documents (HANDOVER.md, etc.)
. Start fresh - describe your projects to Claude, ask to regenerate STATE

== Best Practices

=== Daily Workflow

. Upload STATE.scm at conversation start
. Work on projects, make progress
. Every major milestone: ask Claude to update state
. End of session: export and download STATE.scm
. Store in organized folder with date

=== Weekly Review

. Load STATE.scm in Guile REPL
. Run `(generate-status-report state)`
. Check blocked projects
. Review priorities with `(prioritized-projects state)`
. Update completion estimates manually if needed

=== Project Hygiene

* Mark abandoned projects as `"abandoned"` not just paused
* Keep `blockers` list current
* Update `next` actions after completing tasks
* Clear `files-created-this-session` at week start

== Integration with Other Tools

=== Git Hooks

Add STATE.scm to .gitignore if it contains personal data.
Or version control it to track project evolution:

[source,bash]
----
git add STATE.scm
git commit -m "Session checkpoint 2025-12-06"
----

=== Automation Ideas

[source,bash]
----
# Backup STATE after each conversation
cp STATE.scm ~/claude-sessions/STATE_$(date +%Y-%m-%d_%H%M).scm

# Quick status check
guile -c '(load "STATE.scm") (display-focus state)'
----

== Schema Reference

Full schema for STATE.scm sections:

=== metadata

[source,scheme]
----
(metadata
  (format-version . STRING)     ;; "1.0"
  (schema-version . STRING)     ;; Date-based version
  (created-at . TIMESTAMP)      ;; ISO 8601
  (last-updated . TIMESTAMP)
  (generator . STRING))         ;; What created this file
----

=== user

[source,scheme]
----
(user
  (name . STRING)
  (roles . (LIST))
  (preferences
    (languages-preferred . (LIST))
    (languages-avoid . (LIST))
    (tools-preferred . (LIST))
    (values . (LIST))))
----

=== session

[source,scheme]
----
(session
  (conversation-id . STRING)
  (started-at . TIMESTAMP)
  (messages-used . NUMBER)
  (messages-remaining . NUMBER)
  (token-limit-reached . BOOLEAN))
----

=== focus

[source,scheme]
----
(focus
  (current-project . STRING)
  (current-phase . STRING)
  (deadline . STRING|#f)
  (blocking-projects . (LIST)))
----

=== projects (each entry)

[source,scheme]
----
((name . STRING)
 (status . "in-progress"|"blocked"|"paused"|"complete"|"abandoned")
 (completion . 0-100)
 (category . STRING)
 (phase . STRING)
 (dependencies . (LIST))
 (blockers . (LIST))
 (next . (LIST))
 (chat-reference . STRING|#f)
 (notes . STRING))
----

=== critical-next

[source,scheme]
----
(critical-next
  (ACTION-STRING ...))
----
