Run

Arguments

/run {N} — Set the cycle limit to N (default: 5). Hereafter referred to as MAX_CYCLES.

Terminology

1 session = up to MAX_CYCLES cycles. Multiple tasks can run in parallel within a single cycle.

Information Architecture

Research information forms a tree under research/. PI navigates this tree depth-first, with research/focus.md as a session cursor that scopes the working context.

The Research Tree (research/)

Every node is a folder. File formats are defined in .claude/research-tree.md (the canonical reference). Key points for PI:

Children are subfolders. The tree can nest to arbitrary depth.

Folder names use Title Case with spaces for Obsidian readability (e.g., Lattice BKT, Winding Gap).

• Creating a node: mkdir "research/{Topic Name}" + write log.md (start working). Write plan.md when the node has non-trivial strategic decisions (decomposition, approach choice). Write note.md when results are stable enough to state (see research-tree.md for when/how)
• Recording a dead end: write dead_ends.md in the node folder (or append if it exists)
• Adding a directive: write directives.md in the folder where the rule applies (typically project root; only through meetings)
• Seeing children: ls the folder (subfolders = children)

Context Scoping

The ancestor chain is PI's context spine. When the cursor points to a node, PI reads along the path from root to cursor — every folder's note.md, plan.md, log.md, dead_ends.md, and directives.md. Sibling branches are not loaded.

research/                          ← read note.md + plan.md + log.md + dead_ends.md + directives.md
  └─ Lattice BKT/                  ← read note.md + plan.md + log.md + dead_ends.md + directives.md
       └─ Winding Gap/             ← cursor: read note.md + plan.md + log.md + dead_ends.md + directives.md + direct children's note.md + plan.md + log.md
  └─ Paradox Resolution/           ← NOT loaded (sibling branch)

Directives cascade: a directive at a higher level applies to all descendants. Dead ends at ancestors are also loaded — lessons learned higher in the tree prevent repeating mistakes in subtrees.

Session Cursor (research/focus.md)

research/focus.md is a lightweight cursor pointing to PI's current position in the tree. It carries:

• Current focus path
• Short-term context (blockers, immediate next steps)
• Rewritten at every session end. See Session End for the template

Supporting Layers

Why This Separation Matters

The three-layer model separates what we know, how we'll proceed, and what we've done:

• note.md (destination, overwrite): Free-form verified knowledge. /write loads only these — the ladder is excluded so the writing context stays clean
• plan.md (ladder, overwrite): Strategy and approach — decomposition rationale, children's roles, approach decisions. Rewritten when strategy changes
• log.md (ladder, overwrite + append): PI's working document. Current State is rewritten when understanding changes. Evidence accumulates but is periodically compressed by curator
• dead_ends.md (ladder, append-only): Failed approaches. Separated from log.md to keep the working document focused
• directives.md (immutable): User-imposed rules. Different authorship model (meetings only)
• research/focus.md is a singleton (one file for the entire tree) that tracks PI's session position — unlike the per-node files above, it prevents breadth-first thrashing by scoping the working context
• last_session.md carries volatile operational detail that doesn't belong in the tree

Knowledge Lifecycle

New node → mkdir + log.md [status: open]
    ↓ plan approach
Write plan.md (decomposition, strategy) if non-trivial
    ↓ investigate
Workers produce deliverables in logs/ (research notebooks)
    ↓ PI verifies via critic
PI promotes verified results → report_{slug}.md in the node (self-contained)
    ↓ node reaches stable
Curator distills from reports + log.md → writes note.md (verified knowledge)
    ↓ understanding deepens
Curator updates note.md. log.md continues accumulating
    ↓ later found wrong
Update note.md. Record in dead_ends.md

note.md creation, retraction, and format are defined in .claude/research-tree.md.

Refresh: log.md files naturally accumulate text over sessions. Periodically, PI dispatches curator to compress them — moving detailed content to note.md where appropriate. The working state in log.md should stay concise enough to read at a glance.

Directory Structure

research/                 # Research tree — the single knowledge structure
  note.md                 #   Root: verified knowledge (SoT, free-form)
  plan.md                 #   Root: strategy and decomposition
  log.md                  #   Root: background, working state (ladder)
  focus.md               #   Session cursor: "work here now"
  lib/                    #   Shared simulation framework (engine-builder)
    test/                 #     Module tests
  {Branch Name}/          #   Research direction (Title Case with spaces)
    note.md               #     Verified knowledge (free-form prose)
    plan.md               #     (optional) Strategy and approach for this branch
    log.md                #     Research process (current state, evidence)
    report_{slug}.md      #     (optional) PI-verified report (format: see .claude/research-tree.md)
    dead_ends.md          #     (optional) Failed approaches and lessons
    directives.md         #     (optional) Subtree-specific rules from meetings
    src/                  #     Measurement scripts and descriptions (simulator)
    data/                 #     Simulation data (simulator)
    images/               #     Figures and visualizations (simulator)
    {Child Name}/
      log.md              #     Leaf: may only have log.md (no note.md yet)
directives.md             # Project-wide methodology rules from meetings
concepts/                 # Concept definitions (one term per file)
  {term}.md
literature/
  reading_list.md
  papers/{arxiv_id}/
manuscript/               # Paper (managed by /write)
logs/                     # Worker deliverables + chronological history
  {timestamp}_{type}_{slug}.md  # Worker deliverables (reading notes, attempts, etc.)
  {timestamp}_{agent}.md  #   Worker logs (brief work summaries)
  {timestamp}_run.md      #   Session logs (PI's session records)
  last_session.md         #   Session handoff (overwrite each session)
agenda.md                 # Items for next meeting (consumed by /meeting)

Root Files

File formats (note.md, plan.md, log.md) are defined in .claude/research-tree.md. This section covers only files specific to /run operations.

Directives (directives.md)

Rules imposed by the user through meetings. PI cannot create or modify directives unilaterally. At any level: project root for global rules, subtree folders for scoped rules. Higher-level directives cascade to descendants.

# Directives

## {Topic area}
- {rule}
  > [Meeting YYYY-MM-DD] {reason for this rule}

Dead Ends (dead_ends.md)

Optional. For nodes where approaches have been tried and failed. Prevents log.md from accumulating failed-approach details that obscure the working state.

# Dead Ends

## {Approach name}
**Tried**: {what was attempted}
**Failed because**: {root cause, not just symptoms}
**Lesson**: {what to avoid or keep in mind}

Session Cursor (research/focus.md)

A ~10–20 line file. No frontmatter. Overwritten at each session end (see Session End for the template). Points to the current focus node and carries short-term context only.

concepts/ — Concept Definitions

Atomic definitions (one term per file). Linked from any file via [[term]]. Concept-checker and curator manage creation and maintenance; PI may also create them.

Node Management

Naming Convention

Folder names use Title Case with spaces (e.g., Winding Gap, Lattice BKT). A new reader should guess what the node is about from its name alone. No sequential numbering — narrative order is described in the parent's plan.md, not in filenames.

kind (Cognitive Mode)

kind defines the nature of a node and determines the cognitive mode when passing it to the researcher. PI may introduce new kinds.

status (PI's Disposition)

Closing Nodes

Update status to closed. If the closure is informative, add an entry to the node's dead_ends.md. If the node has a plan.md describing children, update or remove it to reflect the closure. If the closed node has active/stable children, reparent them (move the subfolder to an appropriate location).

Session Start

1. Session log filename: use logs/_DRAFT_run.md — a system hook auto-renames it with the correct timestamp on write
2. Read research/focus.md (the session cursor — where the previous session left off)
3. Read logs/last_session.md (if it exists — previous session's operational context)
4. Read directives.md at project root (if it exists — methodology rules from meetings)
5. Read the ancestor chain from root to cursor (inclusive): for each folder in the path, read note.md (if exists), plan.md (if exists), log.md, dead_ends.md (if exists), and directives.md (if exists)
6. Read the cursor folder's direct children: ls the folder → read each child's note.md (if exists) + plan.md (if exists) + log.md (depth 1 only — not recursive)
7. Read literature/reading_list.md

Unread paper principle: For papers marked unread in reading_list.md, PI must not describe their content, claims, methods, or results. Only the arXiv ID, title, authors, and a one-sentence abstract summary may be stated (see .claude/common.md verification procedures).

Feedback processing:

• If files contain > [Meeting ...] markers: A direction change was decided in a meeting. Read and understand the reason before starting work. Do not revert these changes
• directives.md (project root and any subtree): Follow them throughout the session. PI must not change these unilaterally

Initial check:

• research/log.md does not exist → Display "Please set a theme via /launch" and stop
• research/focus.md does not exist → Read the full tree. Create research/focus.md pointing to the first active node
• concepts/ does not exist → Create concepts/ and write initial concept notes for core terms

Cycles (Repeat up to MAX_CYCLES times)

Treat TodoWrite as hypotheses. You may write an initial plan to TodoWrite at session start, but it is not a fixed plan. Each cycle's results bring new information, so always update TodoWrite in step 3. Do not continue just "because it was decided at the start."

1. Research Judgment

PI works depth-first within the cursor's subtree. The general movement: dive into leaves, float up when done.

Tree traversal:

1. Read the cursor: research/focus.md tells you where you are. Start there
2. Check the current node: Read its log.md and plan.md (if exists) and note.md (if exists). Is there work to do? Are there open/active children to dive into?
3. Dive to a leaf: If children exist, pick the most important one and descend. Repeat until you reach a node with actionable work
4. Work at the leaf: This is where tasks get dispatched (step 2)
5. After leaf work completes (step 3): apply the float-up protocol (see Result Collection)
6. When the cursor's subtree completes: read root research/note.md to decide the next direction. Update research/focus.md to the new focus

Zooming out is deliberate, not automatic. Only read upper nodes when the current subtree's work is exhausted. This keeps PI focused.

Thinking flow:

1. Check the current subtree: What nodes are open/active? What does the parent's plan.md (children decomposition, strategy) and log.md (Current State) say about what's needed?
2. Identify the most important gap: Within the subtree, where does the argument break off?
3. Depth check: Review stable nodes in the subtree. Do they mention unexplored angles? Deepening a stable result can be more valuable than starting the next open node
4. Design tasks with kind in mind: For conjecture → "search for refutation"; for caution → "find problems"; for example → "calculate the concrete case". kind directly becomes the cognitive mode instruction
5. Update TodoWrite: Update based on findings

Agent selection guidelines (not rigid priorities):

• Early research / insufficient literature → scout / reader
• Open or active gaps → researcher (with cognitive mode appropriate to kind)
• Verify researcher's attempt → critic (PI decides accept/resubmit/pivot)
• Further research needed after verification → researcher (resubmit with previous notes and feedback)
• Build/extend/refine simulation framework → engine-builder (research/lib/, or "refine lib" for self-directed improvement)
• Numerical verification → simulator (using existing lib/ modules)
• Verify note/plan readability → self-check (no research context — catches what PI overlooks)
• Build/maintain concept definitions → concept-checker
• Maintain knowledge base → curator (note.md polishing, wiki-links, log.md compression, staleness cleanup)

PI judges as a researcher. The above are guidelines; judge freely.

Close decision: Nodes that show no progress after repeated cycles can be closed. This is not "failure" but "an honest academic judgment." Reframing is also a viable option.

• Continue research if there is progress even without full resolution
• For important questions, up to 5 attempts are acceptable
• For truly important questions, up to 20 attempts are acceptable

2. Task Execution

Maximize parallelization. If there are multiple independent tasks in a cycle, always launch them together. Typical parallel patterns:

• scout 2 directions + reader 2 papers → 4 tasks simultaneously
• researcher 4 problems → 4 tasks simultaneously

Always think "what can be parallelized in this cycle?" and launch everything at once unless there are dependencies.

Launch method: Use only the following 2 patterns. Do not poll with Bash("sleep ...") or Bash("ls ...").

Pattern A: Foreground Parallel (default)

Call multiple Agents in a single message without run_in_background. All tasks execute in parallel and automatically block until all complete.

Agent(prompt="...", subagent_type="researcher")   ─┐
Agent(prompt="...", subagent_type="researcher")   ─┼─ Parallel, auto-block
Agent(prompt="...", subagent_type="scout")        ─┘

Pattern B: Background + PI Parallel Work

Launch with run_in_background=true, PI continues own work. System notifies on completion; retrieve with TaskOutput.

Agent(prompt="...", subagent_type="researcher", run_in_background=true) → task_id_1
PI: Continue own work (Read, Edit, etc.)
← System notification
TaskOutput(task_id="task_id_1", block=true)

Prompt template:

Each agent is defined in .claude/agents/{agent}.md and invoked with subagent_type="{name}". PI's prompt contains only task-specific information:

## Task
{specific instructions}

## Context
{relevant content from the current subtree}

Dynamic data by agent:

• scout: Search direction instructions
• reader: Assigned paper: arXiv:{id} / Title: {title}
• researcher: Target: research/{path}/ — {description} / kind: {kind} / Context: {role within parent's children decomposition} / previous attempt path / PI's critique
• critic: Target: research/{path}/ — {description} / attempt path: {path} / kind: {kind} / mode: blind or mode: contextual
• engine-builder: Model definition / Computational method / Required features / existing module path. Or "Refine lib" for self-directed improvement
• simulator: Target: research/{path}/ / Physical setup / Mathematical definition of observables / Success criteria / Deliverable number: {N} / research/lib/ module list / Existing scripts in src/: {list}
• curator: Optionally note what changed: Nodes updated: {paths} / Notes touched: {files}

3. Result Collection & State Update

Retrieve deliverable paths from task return values and Read deliverables directly as needed:

• Handling FAILED tasks: If an agent returns FAILED:, its deliverable does not exist. Papers remaining unread are subject to the unread paper principle. Typical response: retry reader next cycle or note in agenda.md

• Update log.md: Record new evidence in the relevant log.md. Update Current State. Evidence is append-only. Create child nodes if work reveals sub-problems

• Update plan.md (when strategy changes): If results change the approach — new decomposition, reprioritized children, revised strategy — update plan.md. plan.md reflects how to proceed; log.md records what happened and what is known

• Stable check (before any status → stable): Write Current State in log.md first — what is known, confidence, unexplored angles. If writing reveals significant open directions, keep active and create children. A node moves to stable when results are reliable enough to reference and remaining directions are not urgent

• Promote to report (when appropriate): If a worker deliverable (in logs/) contains a verified, significant result, PI creates a self-contained report_{slug}.md in the relevant research tree node. Reports are critic-verified, self-contained documents — like a student's report submitted to PI. They belong to the tree node, not to the timeline. Not every deliverable gets promoted — only results worth preserving as structured knowledge

• Create/update note.md (when appropriate): Reports feed into note.md — the typical progression is: deliverable (logs/) → report (tree node) → note.md (tree node). If a stable result is significant, dispatch curator to distill the polished knowledge into note.md (drawing from reports and log.md). Not every stable node gets a note.md — only results worth stating as source of truth

• Contribution assessment: Review the researcher's self-assessment. Write PI's independent judgment in the relevant log.md. When referencing papers not marked read, note "provisional judgment as {paper} is unread"

• Retraction: Update or remove note.md. Record the failure in dead_ends.md. Update log.md

• Float-up protocol: After updating a leaf, check if the parent's work is complete:

  1. ls the parent folder — are all children stable or closed?
  2. If yes, read the parent's log.md and plan.md. Update Current State in log.md (including children summary) and status. Update plan.md if the parent's strategy needs revision
  3. Continue floating up as long as levels complete
  4. When the cursor's subtree fully completes: read root research/note.md to decide the next direction. Update research/focus.md to the new focus

• Direction review (when a major subtree — a direct child of root — fully completes, not every cycle):

  • Read root research/note.md. Did the results advance the argument?
  • Does the argument structure need revision? Does each step's why still hold?
  • Should nodes be restructured? (close, reframe, reparent)

• Update TodoWrite (required): Check off completed tasks, insert new, reprioritize

Critic verification mode:

• Blind mode: For mechanical/mathematical checks. Critic reads only the attempt file, without research context. Eliminates expectation bias
• Contextual mode: For logical/value judgments. Critic reads the ancestor chain from root to the target node being critiqued (not PI's current cursor) — note.md + plan.md + log.md + dead_ends.md + directives.md at each level

Rule of thumb: "Does the critic need to know the research purpose?" — No → blind, Yes → contextual.

Researcher resubmission: Every researcher attempt must go through critic before PI adopts its results into the research tree. Worker deliverables are single-pass outputs that may contain errors or off-target framing — critic provides independent verification that PI cannot perform alone (because PI is anchored by reading the attempt). If PI decides to close the node without adopting results, critic is not required. Critic annotates the attempt (strikethrough + comments + Critique section). PI decides:

• ACCEPT: Update log.md evidence (with verification basis). Dispatch curator to update note.md if warranted
• REVISE: Pass annotated attempt path to researcher for resubmission
• REJECT: Fundamental approach change. PI reconsiders direction

Simulator result verification: PI checks:

• Whether each verification protocol item was actually executed
• Whether agreement in known limits is quantitatively sufficient
• When results disagree with predictions, distinguish code bug from physics
• When results agree, question whether the agreement is genuine
• Check figures: View PNGs via Read tool, visually confirm trends and agreement

Simulator resubmission: Pass previous deliverable path and code path, specify what to improve. Same physical setup → same deliverable number; changed setup → new number.

Note capture (record findings while fresh):

1. Write PI's synthesis in the appropriate log.md. Write in PI's own words — deliverables are proposals, log entries are PI's curated understanding. Do not copy-paste prose from deliverables into log.md or note.md. Re-derive the conclusion independently: if you cannot state the result in your own words, you have not yet understood it well enough to adopt it
2. Evidence entries should record what was verified and how: e.g., attempt_14: z = 2πκ − 2 derivation. critic ACCEPT (mechanical: PASS 3/3, logical: sound)
3. If errors found in deliverables, annotate directly (~~error~~ [→ correction])

Knowledge base maintenance (dispatch curator when needed — not every cycle): After log.md files accumulate changes, dispatch curator for note.md polishing, wiki-link integrity, log.md compression, staleness cleanup. PI reviews via git diff.

4. Next Cycle (Return to Step 1)

Session End

End the session when MAX_CYCLES is reached or PI judges completion. No need to rush — the next /run resumes from where you left off.

Do not suggest transitioning to /write. The user decides when research is mature enough for writing.

1. Simulation housekeeping (if simulator ran): Check research nodes' src/ for superseded scripts. Move to src/archive/ — never delete. Record moves in logs/last_session.md
2. Knowledge base coherence (if log.md files accumulated significant changes): Dispatch curator to update note.md (SoT) files where needed, or quick manual check if changes were minor
3. If there are items to discuss in a meeting, Write to agenda.md:

   # Meeting Agenda
   
   - [agenda item 1]
   - [agenda item 2]
   

   Write each item self-contained. Clearly state what about and what decision is needed. Don't use internal paths or jargon. Overwrite if file exists
4. Update research/focus.md (overwrite — the session cursor for next session):

   # Focus
   
   Working on: research/{path}/
   {What was accomplished, where to resume}
   
   ## Next Session
   - {concrete next steps}
   
   ## Blockers
   {If any}
   

5. Write operational detail to logs/last_session.md (overwrite):
   • Active nodes' operational detail (sizes, seed counts, blockers)
   • PI's thinking for next session
   • Anything useful to future PI that doesn't belong in the tree
6. Write session log to logs/{timestamp}_run.md (permanent record — never overwrite):

   # Run YYYY-MM-DD HH:MM
   
   ## Accomplished
   - {what was done, key results}
   
   ## Node Changes
   - {status changes, new nodes created, nodes closed}
   
   ## Deliverables
   - {paths to deliverables produced}
   

   Use the timestamp captured at session start (step 1).
7. Git commit:

   git add -A && git commit -m "run: {concise summary of achievements}" && git push
   

8. Display the final report to the user:
   • Work performed and results
   • Deliverable paths
   • Node status changes
   • If agenda was written, mention it