session-start

name

session-start

description

Restore full project context at the beginning of a new session. Use when the user says 'start session', 'restore context', 'new session', 'resuming', or starts a conversation on this research project without context — reads PROJECT_STATE.md, reloads phase-specific artifacts, checks for running experiments, and announces the current state before taking any action. Must be run before any pipeline work begins.

Session Start

Restore project context from disk and orient before acting. Follow these steps in order. Do not skip steps or reorder them.

Step 1 — Read the state file

Check whether PROJECT_STATE.md exists in the project root.

If it does not exist — this is the first session on a new research project. Copy .claude/skills/session-start/references/PROJECT_STATE.md to PROJECT_STATE.md at the project root. Then skip to Step 3 (no state to restore, no experiments to check). At Step 7, announce a new-project start instead of a session-restore summary:

## New Project — First Session

PROJECT_STATE.md initialized from template. No prior state to restore.

Read PROJECT_OVERVIEW.md to orient yourself, then ask the user:
"What research idea would you like to start with?"

If it exists — read it in full. Do not skim. Hold all eight sections in context before proceeding.

Step 2 — Check for running experiments (Section 2)

This is the highest-priority check. If Section 2 is non-empty:

1. Run the check command listed for each entry.
2. Report status to the user immediately: still running / completed / failed.
3. If still running: do not proceed to pipeline work. Inform the user and wait.
4. If completed: record the result location and queue the on finish action as the first item in Next Steps. Continue to Step 3.
5. If failed: report the failure. Do not attempt to re-run automatically — surface this to the user and wait for instruction.

Step 3 — Read the framework overview

Read PROJECT_OVERVIEW.md. This is mandatory even if you believe you remember the pipeline structure. It takes 30 seconds and prevents silent assumption errors.

Step 4 — Load phase-specific artifacts (Section 4)

Read each file listed in Section 4 (Key Artifacts). Load them in the order listed. Do not load the whole phase directory — only what Section 4 points to.

If a listed file does not exist:

• Flag it explicitly: "Key artifact path/to/file listed in PROJECT_STATE.md does not exist on disk."
• Do not proceed past this step until resolved. Either the path is wrong (fix PROJECT_STATE.md) or the file was never written (surface to user).

Step 5 — Review pending agent work (Section 3)

If Section 3 is non-empty, the previous session ended abruptly before acting on some delegated output. Present each item to the user and ask how to proceed. Do not auto-continue work that was left mid-delegation.

Step 6 — Surface open decisions (Section 5)

If Section 5 has unresolved items, present them clearly before announcing next steps. Open decisions block forward progress — they cannot be bypassed.

Step 7 — Announce state and confirm next steps

Output a structured orientation summary:

## Session Restored

**Phase:** [N] — [phase name]
**Active loop:** [none | Loop N, round N — trigger: "..."]
**Last completed step:** [one line]

**Running experiments:** [none | see above]
**Open decisions:** [none | N items — listed above]

**Planned next steps:**
1. [first item from Section 6]
2. [second item]
...

Proceed with step 1?

Wait for user confirmation before acting. The user may correct the state, redirect the next step, or provide additional context from outside the files.