session-end

name	session-end
description	Persist current project state before ending a session or running /clear. Use when the user says 'save', 'wrap up', 'new session', 'ending here', or is about to run /clear. Writes all current state to PROJECT_STATE.md so the next session can resume without ambiguity. Must be run before any /clear or context reset.

Session End

Write the current project state to PROJECT_STATE.md before ending the session. PROJECT_STATE.md is a living document — every section is overwritten in full. Do not append to previous content; replace it.

Work through each section in order. Do not skip any section, even if it is empty.

---

Pipeline reference

The phase and loop vocabulary used throughout this skill:

Phase	Name	Enters when
0	Ideation	Raw idea received; Literature Scout + Refiner active
1	Method Design	Idea passed stress test; Architect + Confirmer active
2	Small-Scale Verification	Spec confirmed; Coder implements; first experiments run
3	Main Experiments	Phase 2 results OK; full framework implementation
4	Ablation	Runs in parallel with Phase 3; Ablation Designer active
5	Review	Paper draft complete; Reviewer active
6	Writing	Reviewer approved or Loop 4 resolved

Loop	Trigger	Action
Loop 1	User intervenes during ideation	User + Refiner iterate together with Main Agent
Loop 2	Tester finds major flaws	Return idea to Refiner
Loop 3a	Experiment fails — code bug	Coder fixes and resubmits
Loop 3b	Experiment fails — idea/design flaw	Return to Phase 0 or Phase 1
Loop 4	Reviewer raises major issues	Supplement experiments; revise paper

Use this table when filling in Section 1. If the current state does not map cleanly to one phase (e.g., mid-transition), write the phase you are leaving and note the transition in Last step.

---

Section 1 — Position

Write the current position in this exact format:

Phase:        [0–6] — [phase name]
Active loop:  [none | Loop N — trigger: "one-line description" — round N of N]
Last step:    [the last concrete action completed this session, one line]
Updated:      [today's date, YYYY-MM-DD]

Last step must be specific enough that the next session can see exactly where execution stopped. Not "worked on idea" — write "Refiner produced idea_v3.md in response to Tester's novelty critique."

---

Section 2 — Running Experiments

If no experiments are running: write <!-- EMPTY — no experiments currently running -->.

If an experiment was launched this session and is still running in the user's configured execution environment, write one block per experiment:

---
Script:    `[exact command that was run]`
Launched:  [YYYY-MM-DD HH:MM]
Environment: [short description — e.g., "local", "remote host <alias>", "SLURM on cluster X"]
Log:       `[path to the log file — must be locally readable per the run-experiment execution contract]`
Check:     `[shell command the next session can run to check completion — e.g., "test -f phase_2_verification/results/log_{n}.done"; exact form depends on the execution environment]`
Output:    `[local path where results will be written when done]`
On finish: [exact routing instruction — which agent receives the output, what file to produce]
---

The Check field must be a literal command the next session can run without reconstructing context. The On finish field must name a specific agent and output file, not a vague intention.

If an experiment that was listed as running has now completed, clear it from this section and add the results file to Section 4.

---

Section 3 — Pending Agent Work

If all delegations completed and were acted on: write <!-- EMPTY -->.

If any agent was delegated work and its output has not yet been acted on, write one entry per delegation:

- Agent: [agent name]
  Produced: `[output file path]`
  Waiting on: [what needs to happen next with this output]
  Next action: [concrete instruction for the next session]

A clean session-end should leave this section empty. Non-empty means something was left mid-flight — flag it clearly so the next session doesn't accidentally re-trigger the same delegation.

---

Section 4 — Key Artifacts

Write the current canonical file for each role. Only include roles that have a file; omit rows for roles that don't apply to the current phase. Use the exact path relative to the project root.

Role	Path	Notes
Current idea	[path or —]	[e.g., "Passed stress test"]
Method design	[path or —]	[e.g., "Confirmed by Confirmer"]
Experiment setup	[path or —]	[e.g., "Datasets + baselines locked"]
Active spec	[path or —]	[e.g., "Handed to Coder"]
Latest results	[path or —]	[e.g., "Partial — run still active"]
Latest analysis	[path or —]	[e.g., "Pending experiment completion"]

The Notes column carries the context that the path alone cannot — why this version is canonical, what state it is in. Write notes that would answer "why this file, not the previous version?"

---

Section 5 — Open Decisions

If no decisions are blocking: write <!-- NONE -->.

For each unresolved decision:

- [ ] [Short label for the decision]
      Context: [one or two sentences explaining what triggered this decision]
      Options: [list the concrete options, labeled (a), (b), ...]
      Blocking: [what cannot proceed until this is resolved]

Close any decisions that were resolved this session by removing them. Do not accumulate resolved decisions — that history belongs in _logs/decision_log.md.

---

Section 6 — Next Steps

Audience: the next session's agent. This section is a machine-readable execution queue. Write for an agent that will act on item 1 immediately after reading it — not for a human skimming for context.

Write a numbered, ordered list. Item 1 is what the next session should do first. Each item must be specific enough to act on without reading anything else first: name the agent, the input file, and the expected output.

If Section 2 is non-empty (experiment running), item 1 must always be: Check experiment status (§2) and route results per On finish instruction.

Otherwise, derive the queue from the current pipeline state. Three to five items is the right length — not a backlog, not a single vague intention.

Do not repeat narrative context here. Explanations of why belong in Section 8.

---

Section 7 — This Session

Write today's date, then a table of every file created or significantly modified this session. "Significantly modified" means the content changed in a way relevant to the pipeline — not a typo fix.

**Session date:** YYYY-MM-DD

| File | Change |
|------|--------|
| [path] | [one-line description of what changed and why] |

The Change column should say what changed and why, not just "updated." Not "edited idea_v3.md" — write "Refiner rewrote §2 to add gap-proof for claim 2 after Tester flagged weak novelty."

---

Section 8 — Handoff Note

Audience: the human researcher. This section is a narrative summary, not a structured list. Write for a person who will scan it in ten seconds before a meeting, after waking up, or before deciding whether to start a new session now. They have not read the other sections yet.

Write one paragraph that answers:

• What was the main work of this session — what problem was being solved, what was tried?
• What is the current state of the research itself (not the pipeline state — the intellectual state: what is working, what is uncertain, what changed in your understanding)?
• What does the next session need to watch out for or decide?

Do not repeat Section 6 verbatim. Section 6 says what to do; Section 8 explains why the project is in this state and what judgment calls lie ahead. A reader who only has time to read one section should read this one.

---

Final check

Before closing:

1. Confirm Section 2 accurately reflects the actual state of the execution environment. If you launched an experiment and are uncertain whether it started successfully, note that uncertainty explicitly in the Check field instruction.
2. Confirm Section 6 item 1 is consistent with Section 2 (running experiment → check first).
3. Confirm _logs/decision_log.md was updated if any significant decisions were made this session. If not, write the decisions there now before ending.