doc-mirror-boot

name

doc-mirror-boot

description

WHAT: doc-mirror-boot — the MANDATORY first action of EVERY turn in this container. It primes the CORE LOOP, explains the doc-mirror STATE MACHINE (cursor + state-skills + transition hook), and routes you to the state your cursor names. You are ALWAYS inside this machine; no reading, querying, editing, answering, planning, or dispatching is valid until you have booted this session. WHEN: ALWAYS — UNCONDITIONALLY, BEFORE ANY OTHER ACTION. If `doc-mirror-boot` is not ALREADY in your context this session, you MUST use it NOW, first, before you do anything else — at the very start of every session, immediately after every compact/restart, and the instant you are about to do work (read, grep, query CartON, edit, answer the user, dispatch an agent, rehydrate) without having booted. Also when the transition hook says 'use the doc-mirror-boot skill', when you are unsure what state you are in, when you catch yourself freestyling/ad-hoc-querying/ad-hoc-reading, or when the user mentions doc-mirror, the cursor, the state machine, rehydrating, memory, or what to work on. If in doubt: BOOT. Never act before booting. This is not topical — it fires on EVERYTHING.

doc-mirror-boot — START HERE, every session

This is step 0. You read this first, always. It does three things: (1) PRIMES you with the core loop, (2) tells you how the doc-mirror state machine runs, (3) routes you to the state your cursor names. You never improvise — you read your cursor and call the state-skill it names, emitting a CoR that uses the core-loop priming.

1. THE CORE LOOP (the prime — how to understand every turn)

The core loop is the resident attention chain that primes you each turn. It is NOT a CoR you paste; it is the standing priming that your per-turn CoR then activates. Hold this as the shape of every turn:

use the doc-mirror-boot skill first thing when a session starts
→ journal as you go (think = a cross-cutting action, every state, the moment a thought occurs)
→ while there is work: enter the appropriate doc-mirror-{state} skill (your CURSOR names which)
→ if it is time to make an agent DO something: use doc-mirror-prompts
→ maybe docmirror-sleep.   NOTHING ELSE HAPPENS.

Each turn, primed by this, you EMIT a CoR that uses the priming — a said reasoning chain that names the state you're in, does that state's leg, advances the cursor, and names the next state. The core loop is the tag that primes you; your per-turn CoR is the token that activates it. (Do NOT mistake the core loop for "a CoR I paste" — it is the unsaid priming; the CoR is the said activation.)

2. THE STATE MACHINE (how doc-mirror runs)

The doc-mirror flow is a state machine: states = skills, transitions = each state's CoR + the cursor, enforcement = the transition hook, reification = the diagrams (STATE_GRAPH.md + SYSTEM.md + the always-on rule). You are always inside one state; you do its leg, advance the cursor, and call the next state — the machine loops itself.

Your place in the machine is the CURSOR — docmirror-cursor (persisted at <root>/.docmirror/cursor.json, survives compacts). It is the authority: your cursor's phase names the state-skill you call. The skill descriptions are discovery; the cursor is the deterministic router.

stateDiagram-v2
    [*] --> doc_mirror_boot: every session / post-compact / new turn
    doc_mirror_boot --> R_cursor: docmirror-cursor show  (read your phase)
    R_cursor --> ROUTE
    state ROUTE <<choice>>
    ROUTE --> state_init:    [phase==init]      call doc-mirror-init
    ROUTE --> state_seework: [phase==seework]   call doc-mirror-seework
    ROUTE --> state_change:  [phase==change]    call doc-mirror-change
    ROUTE --> state_prompt:  [phase==prompt]    call doc-mirror-prompts
    ROUTE --> WAIT_open:     [phase==open]      blocked on Isaac — re-echo open_fork, docmirror-sleep
    ROUTE --> SELECT:        [phase==orient/empty]  pick the state whose WHEN matches the situation
    SELECT --> ROUTE: set the cursor phase, then route
    state_change --> R_cursor: each state's CoR advances the cursor + calls the next state (the machine loops)
    note right of ROUTE
        STUCK anywhere = the only off-script exit:
        journal -t OPEN "<fork>"  ·  docmirror-cursor set --phase open  ·  docmirror-sleep (echoes to Isaac)
        IDLE: clean seam / queue empty -> self_compact & (👍) or docmirror-sleep (chunked).
    end note

3. THE STATES (= the skill list = the cursor phases)

phase	state-skill	what it is
boot	doc-mirror-init	mirror an unmirrored codebase the first time (enumerate→doc(m)+vision(m)→synthesize→layers→closure)
seework	doc-mirror-seework	the backlog VIEW (vision stats→project→diff) → pick the next gap → route to its state
change	doc-mirror-change	a module changed → re-derive doc(m) → doc-mirror-commit w/ ORIGIN → graduate vision→impl
prompt	doc-mirror-prompts	need an agent to DO a task → search/author a reliability-scored prompt-skill

Not states (no transition gate): think (journal-as-you-go) and harvest (noticed a reusable rule/skill) are CROSS-CUTTING actions inline in every state. idle and open are WAIT states — docmirror-sleep / self_compact (idle), or journal -t OPEN → sleep → Isaac (open). They live in this spine, not in their own skills.

Reference docs (not states): doc-mirror = THE LAW (the invariant all states operate under — 4 legal file kinds, deterministic addressing, doc(m) template, closure test, fork-on-change). make-ai-operating- system = the L2 architect for designing NEW systems of this class.

THE STATE-SKILL TEMPLATE (every doc-mirror-{state} skill is exactly this shape)

1. {the state's subgraph mermaid}         ← the shape (one canonical place for THIS subgraph)
2. {explanation}                           ← what this state is, the said/symbolic context
3. {CoR — the binding + the transition}:
   "Now that I've read {this state}, I will {the state's inner CoR — its concrete steps}, then I
    advance the cursor (`docmirror-cursor set --phase {next}`) and call `{next state-skill}`
    — or, if {branch condition}, call `{alt state-skill}` instead.
    If I hit a fork I cannot resolve (architecture / irreversible / needs Isaac): I `journal -t OPEN
    "<fork + why>"`, `docmirror-cursor set --phase open`, and `docmirror-sleep` — I call no next; I wait."

Three invariants the template enforces: conditional next (the CoR names the branch's successors), cursor-coupled (advance the cursor in the same breath as the call, so a compact can resume), and stuck = a defined exit (OPEN → sleep → Isaac), never freestyling.

THE TRANSITION HOOK (why you might land here mid-session)

A PreToolUse hook on the Skill tool checks that each state transition is sensical (per the LEGAL TRANSITIONS table in STATE_GRAPH.md). If you make a nonsensical jump it blocks you once with a warning and the line "To gain understanding of the compiler/state machine, just use the doc-mirror-boot skill." That is the catastrophe-surface guard letting you catch yourself — if you genuinely meant the jump (an emergent deviation), journal -t DECISION why ("swapped emergently to X because…") and RE-INVOKE the state-skill to force it through. If you forgot how the machine works, you're reading the right skill now.

What you need (confirm present)

• The CLIs on PATH: docmirror-cursor, journal, vision, plan, projects, doc-mirror-commit.
• The overview docs (the human map): STATE_GRAPH.md (full machine) + SYSTEM.md (the 4 glance diagrams).
• The repo root resolves (env DOCMIRROR_MONOREPO / ~/.docmirror_root / git toplevel). journal --where confirms it.

CoR (doc-mirror-boot's own binding — the priming, then the route)

Now that I've read doc-mirror-boot, I am PRIMED with the core loop, and I will ORIENT — read SYSTEM.md (the 4 diagrams), run docmirror-cursor show to read my phase, and then RECURSIVELY REHYDRATE via doc-mirror-memory-net (DMN) — this is MANDATORY and is NOT a single locate: I identify what I am working on, then call DMN OVER AND OVER (tree → drill the domain → #3 by subdomain/tag → #6 neighborhood), retrieving the ENTIRE set of entries about it in FULL TEXT (read the overflow file) and following related_to/part_of to adjacent coordinates, until the entries STOP being about my thing — proving to myself I have contextualized EVERYTHING (a vision = the recursive grouping of everything ever said about that feature; the decisions are already made and I make the vision REFLECT them) BEFORE I act. A thin peek + freestyling is the failure that destroys work. I NEVER ls/cat the flat docs/vision/ files — the graph IS the hierarchy; the ROOT progress-tracker names the active repo. I call the state-skill for that phase (per the table) and follow its CoR; if the cursor is empty I SELECT the state whose WHEN matches the situation and set the phase first. I emit a CoR each turn that USES the core-loop priming. I act ONLY on the named state's leg; I advance the cursor and journal as I go; on an unresolvable fork I journal -t OPEN and docmirror-sleep. I never freestyle — I am always inside one state of the machine.