Liquid Cat Physics

Liquid Cat Physics

Autonomous deep-work engine. One command to start, then walk away.

How it works

Type /liquid-cat-physics and the skill runs a pre-flight readiness check (once), sets up a recurring cron loop, and keeps going autonomously every 10 minutes.

Each iteration cycle:

ORIENT  → Read state, know where you are           (fast read)
THINK   → Expert assessment, decide next action     (subagent)
GATE    → GREEN/YELLOW/RED confidence check         (decide)
ACT     → Execute ONE unit of work                  (main context)
PERSIST → Update PROJECT_STATE.md + selective notes  (always)

State lives on disk, not in conversation. Context compaction can't erase it.

Reference files (read on demand, NOT every iteration):

• references/confidence-gate.md — re-read when GATE decision is uncertain
• references/anti-thrashing.md — re-read when a failure occurs or failure_log is non-empty
• references/elevate-lens.md — re-read in THINK phase (what to work on)
• references/prodev-standard.md — re-read in THINK + ACT phases (how to execute)
• references/browser-verification.md — re-read when doing visual/UI work

When NOT to use this skill

• No project structure (no git repo, no CLAUDE.md, no clear goals) — set those up first
• One-off task or quick fix — just do it directly
• Project requires continuous human design decisions — use /architect instead

Invocation

Startup Decision Tree

Every invocation enters here. One path, no ambiguity.

Read PROJECT_STATE.md → look for ## Loop State
│
├── No Loop State found → FIRST RUN
│   1. Run Phase 0: Pre-Flight (interactive)
│   2. Initialize Loop State + _notebook/
│   3. Create cron at requested interval
│   4. Proceed to ORIENT
│
├── Loop State exists, status: paused
│   1. Create new cron at stored interval
│   2. Set status: active
│   3. Proceed to ORIENT
│
├── Loop State exists, status: active
│   1. Check cron_id via CronList
│   ├── Cron alive → Proceed to ORIENT
│   └── Cron dead (session restart, expired)
│       1. Recreate cron at stored interval
│       2. Update cron_id
│       3. Proceed to ORIENT
│
├── Loop State exists, status: checkpoint
│   1. Human resumed after checkpoint — create new cron
│   2. Set status: active
│   3. Proceed to ORIENT
│
├── Loop State exists, status: complete → Exit. "Project complete."
│
└── Loop State exists, status: blocked-stopped
    1. Check if blocked items are now unblocked
    ├── Still blocked → Exit. Show blocked items.
    └── Something unblocked → Create cron, set active, ORIENT

Stopping

/liquid-cat-physics stop:

1. Read cron_id from Loop State
2. CronDelete to cancel it
3. Set status: paused, clear cron_id
4. Output: "Loop stopped at iteration N. Run /liquid-cat-physics to resume."

Phase 0: Pre-Flight Readiness Check

Runs ONCE on first invocation. INTERACTIVE — asks user questions.

This is the only interactive phase. Front-load all friction here so the loop runs autonomously after.

Steps

1. Deep-read the project. CLAUDE.md, README, package.json, directory structure, existing code patterns, git history, any existing _notebook/ or PROJECT_STATE.md.

2. Assess readiness across these dimensions:

   Dimension	What to check	Insufficient if...
   Goals clarity	Are goals specific and executable?	Vague ("make it good"), no success criteria
   Codebase understanding	Architecture, patterns, conventions	Can't explain the data flow or key abstractions
   Verification infrastructure	Tests, build, linter exist?	No automated feedback signal at all
   Scope definition	Work is narrow enough for autonomous execution?	Too broad, multi-week epic with no breakdown
   Blockers visible	Obvious RED items that would block immediately?	First 3 tasks are all RED
   Dependencies/access	API keys, services, credentials available?	Needs external resources the LLM can't access

3. If ANYTHING is insufficient: Ask the user targeted questions. Not a generic checklist — specific questions about the actual gaps found. Don't proceed until every dimension is at least adequate.

4. If verification infrastructure is missing: That's OK for greenfield projects. Note that the first iterations should set it up (see bootstrap exception in references/confidence-gate.md). This is not a blocker — just flag it.

5. Run verification baseline. If any verification infrastructure exists (tests, build, lint), run it all NOW. Record the results in verification_baseline: in Loop State. This is the known-good (or known-bad) starting point — every future regression check measures against this. If 3 tests fail before the loop starts, the loop knows it didn't cause them.

6. Set checkpoint interval. Default: every 10 iterations. Store as checkpoint_interval: in Loop State. The loop will pause itself at this cadence for human review.

7. Generate execution protocol. Write the ## Execution Protocol header into PROJECT_STATE.md (see references/state-schema.md). This is the bootstrap sector — compact recovery instructions that survive context compaction. The LLM reads this first every iteration.

8. Initialize working memory. Create ### Working Memory in Loop State with initial codebase observations from the deep-read: key file map, architecture notes, dev server commands, environment details.

9. Enable memento auto. Run touch ~/.claude/.memento-auto. This ensures compaction recovery — when the context window fills and auto-compacts, the memento hook preserves recent conversation trace and re-injects it post-compaction. No toggle, no prompt. Autonomous loops need this unconditionally.

10. Once ready: Populate initial project_goals: summary in Loop State, set current_focus, populate up_next with 3-5 tasks and confidence ratings, then create the cron and proceed to ORIENT.

Phase 1: ORIENT (every iteration)

Step 1: Read state + exit early if terminal

1. PROJECT_STATE.md — start with ## Execution Protocol (context recovery), then parse ## Loop State for status, iteration, focus, failures, up_next, working memory
2. Status checks (exit early):
   • status: complete → CronDelete, clear cron_id. Output "Project complete." Exit.
   • status: blocked → Check if blocked items are now unblocked. Still blocked → CronDelete, set status: blocked-stopped, clear cron_id. Exit. Unblocked → set status: active, continue.

Step 2: Read remaining context

3. _notebook/lessons.md — constraints and past failures
4. _notebook/_index.md — recent context
5. git log --oneline -10 — recent commits
6. git status — working state
7. CLAUDE.md — only on first iteration or when current_focus changes. Cache goals as project_goals: in Loop State.

Step 3: Orphaned changes recovery

If git status shows uncommitted changes, check whether the last iteration committed them:

• Compare dirty files against last_action and git log --oneline -1
• If last iteration completed normally (its commit exists in log) → changes are external (human or tooling). Leave them. Note in working memory.
• If last iteration did NOT commit (iteration count matches but no commit, or last_action shows fail/partial) → orphaned changes from a failed or interrupted iteration. Recover:
  1. Read the diff (git diff) to understand what was attempted
  2. Run verification (tests/build/lint/browser — whatever the project uses)
  3. Passes → commit as recovery: [description of changes]. Log in Completed. Increment iteration. Continue normally.
  4. Fails → git checkout . to revert. Log as interrupted attempt in failure_log. Counts toward two-strike rule. Continue normally.

Step 4: Checkpoint trigger

If iteration is a multiple of checkpoint_interval (default 10): pause the loop.

1. Coverage gut-check. Before reporting to the human, assess test coverage against what's been built since the last checkpoint:

   • Run existing tests. Do they pass?
   • Scan the code written in the last N iterations (check ### Completed). For each significant piece of logic: is there a test that exercises it? Not line-coverage math — a judgment call: "if this broke, would a test catch it?"
   • If there are meaningful gaps, add test-writing tasks to the top of up_next with GREEN confidence. These are first-class work, not afterthoughts.
   • Include a one-line coverage assessment in the checkpoint report: "Tests cover the critical paths" or "Gaps: [list]. Queued test iterations for next cycle."

   This is NOT a full /fortify invocation. No mutation testing, no infra setup. Just: "did I build 10 features with zero tests?" If yes, fix it before the human has to ask.

2. Output a structured checkpoint report:

   • Completed items since last checkpoint
   • Coverage assessment (from step above)
   • Current trajectory vs. project_goals — on track or drifting?
   • Any items that have been YELLOW for 3+ iterations without resolving
   • Momentum summary (see below)
   • Explicit ask: "Continue, adjust focus, or stop?"

3. Set status: checkpoint, CronDelete, clear cron_id

4. Exit. The human must invoke /liquid-cat-physics to resume.

Step 5: Momentum detection

Read the last 3-5 iterations from ### Momentum section. Detect patterns:

Note: A RED iteration that is purely procedural (escalating a two-strike failure, writing a decision doc) does NOT count toward the consecutive RED pattern. Only count iterations where actual work was attempted and failed. A two-strike escalation followed by a GREEN on the next task is healthy behavior, not a crisis.

If an early checkpoint triggers, note early_checkpoint: true and the reason in the checkpoint report.

Phase 2: THINK (subagent — protect main context)

Spawn a Plan or Explore subagent. The subagent's verbose reasoning stays out of main context.

Critical: pass the subagent explicit context. Subagents run in isolated context windows — they haven't read anything. The subagent prompt MUST include:

1. Inline state summary: current_focus, project_goals, last_action (result + reflection), failure_log entries, up_next queue, momentum patterns (consecutive outcomes), verification_baseline
2. Files to read: Tell the subagent to read references/elevate-lens.md AND references/prodev-standard.md, plus any project files relevant to the candidate action. Only include references/confidence-gate.md if the gate decision is genuinely uncertain, and references/anti-thrashing.md if the failure_log is non-empty.
3. Lessons: Either inline the full lessons.md content or tell it to read _notebook/lessons.md

The subagent must:

1. Assess current state. What's done vs. project goals? What's the gap?
2. Apply the expert lens. Read references/elevate-lens.md. Ask: "What would a top practitioner do RIGHT NOW? Not the obvious TODO — the smartest move."
3. Apply the engineering standard. Read references/prodev-standard.md. For the candidate action:
   • Layer check: Is this solving the problem at the right layer? If not, redirect.
   • Blast radius: Can you answer what calls this, what it calls, what breaks, what tests cover it? If not, the action is "read and understand the code first" — not "write code and hope."
   • Research protocol: Does this action touch an external API/library? If yes, verify the version and call signatures are current before committing to the action. Bake the research into the action scope.
4. Check lessons. Is the candidate action something that's failed before? If yes, find a different approach or escalate.
5. Research if needed. Unfamiliar APIs, library choices, architecture patterns → research first. Use web search, context7, codebase exploration. Don't guess. Don't rely on training data for API signatures.
6. Decide ONE action. Not a list. ONE thing, scoped to 5-8 minutes of execution.
7. State the verification plan. What specific check confirms success? If you can't name one, it's not GREEN (see bootstrap exception for infra setup). For visual/UI work: specify browser verification per references/browser-verification.md — this is a valid GREEN check.

Return to main context: the decided action, its confidence tier, and the verification plan.

Phase 3: GATE (confidence check)

Read references/confidence-gate.md for full criteria.

The rule: When in doubt, RED. One skipped iteration costs 10 minutes. One wrong action costs hours.

Phase 4: ACT (focused execution)

Execute the ONE decided action. Re-read references/prodev-standard.md "During Execution" section if this is a code-writing iteration.

1. One thing only. Notice something else? Note it for a future iteration.
2. Read before you write. Understand the code you're modifying — the file, the callers, the data flow. Never assume structure, never guess at function signatures, never build on top of an unverified assumption. If you don't know, look. If you can't find it, ask (RED).
3. Use current-gen patterns. Match the project's existing patterns and versions. If unsure whether an API/pattern is current, check the docs — don't rely on training data.
4. No stubs, no placeholders. // TODO, hardcoded returns, and fake implementations are never acceptable in a GREEN iteration. Can't build the real thing? That's a RED — escalate, don't stub.
5. Boring is good. Obvious, predictable, unremarkable code. If you're writing something clever, check whether the problem genuinely demands it or you're pattern-matching to training data.
6. Minimum necessary complexity. Don't add error handling for impossible states, configurability nobody asked for, or abstractions for one-time operations. Three similar lines > a premature abstraction.
7. Follow the verification plan. Run the check you committed to in THINK. For browser verification, follow the full protocol in references/browser-verification.md.
8. Verification minimum bar. Syntax checks alone (e.g. node --check) are NOT sufficient verification. At minimum: build/compile succeeds + the changed behavior actually works (run it, hit the endpoint, load the page). If no test suite exists, run the code and confirm the new behavior functions. If the work is visual, use browser verification.
9. Self-review before committing. Run the prodev self-review gate (see references/prodev-standard.md). Every answer must be "yes" or "not applicable." If any answer is "no" — fix it before committing. Don't record a GREEN that isn't one.
10. If verification fails: Don't retry immediately. Record failure. Check references/anti-thrashing.md two-strike rule. Attempt 2 on same task → escalate to RED.
11. If verification passes AND self-review passes: One atomic commit with all changes (code + state update). Never split an iteration across multiple commits.
12. Don't refactor what you just wrote. Build forward. Polish is for a dedicated iteration.

Phase 5: PERSIST (every iteration)

PROJECT_STATE.md (always)

Update ## Loop State:

• Increment iteration:
• Update current_focus:, last_action:, up_next:, blocked:, failure_log: as needed
• Update ### Completed — append this iteration. Cap at 10 items. Archive older entries to _notebook/completed-log.md (append-only).
• Update ### Momentum — append this iteration's outcome (GREEN/RED/partial), prune to last 5
• Update ### Working Memory — add any new codebase insights, file discoveries, architecture observations, environment details. Remove stale entries. This is the LLM's operational memory that survives compaction.
• See references/state-schema.md for full template

Notebook (selective — NOT every iteration)

ALWAYS save: failures, decisions, constraints discovered, pivots, investigations, non-obvious learnings, significant milestones.

NEVER save: routine GREEN completions ("added button, tests pass"). The Completed list in PROJECT_STATE.md already tracks mechanical progress. Notebook is for knowledge that compounds.

Completion check

After persisting, assess: is the project done?

• All items in project_goals addressed
• No remaining GREEN or YELLOW in up_next
• All automated checks pass

If complete → status: complete, CronDelete, clear cron_id, output summary. If everything remaining is RED → status: blocked. Cron stays for one more iteration (ORIENT checks if anything unblocked, then auto-cancels if not).

Behavioral Rules

1. External feedback is the only real self-correction. Tests, builds, linters. Your own judgment about correctness is unreliable. Always verify with tools.
2. One task per iteration, always. Resist scope creep.
3. Persist before everything else. Lost state means starting over.
4. Read lessons.md before every action. The answer may already be there.
5. Subagents for exploration, main context for implementation.
6. When stuck, escalate — don't thrash. Two failed attempts = RED.
7. Exactly one commit per iteration. Code changes AND PROJECT_STATE.md updates go in the same commit. Never split an iteration across multiple commits — stage everything, commit once.
8. No placeholder implementations. Can't build the real thing? Mark it RED. // TODO, hardcoded returns, and stub functions are never GREEN.
9. Context is finite. Act like it. Lean tool output. Subagents for verbose exploration. On routine GREEN iterations, read only PROJECT_STATE.md + lessons.md + _index.md. Re-read reference files only when uncertain or handling failures — not every iteration.
10. The project goals are sacred. Don't add features that aren't in the goals.
11. Read before you write. Understand the file, its callers, and the data flow before modifying anything. If you can't explain the blast radius of your change, you haven't read enough code yet.
12. Fix the system, not the symptom. If a bug is possible, fix why it's possible — don't patch the instance. If pragmatism demands a temporary patch, say so explicitly in the commit and notebook. Never silently pass off a hack as a real fix.
13. Verify APIs against docs, not training data. When touching external libraries or frameworks, check the version and look up the docs for THAT version. Training data skews old. Skip this only for language fundamentals you're certain about.
14. Self-review gates every commit. The prodev self-review checklist runs before every commit. A GREEN that fails self-review is not a GREEN.