| 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:
- Run the
check command listed for each entry.
- Report status to the user immediately: still running / completed / failed.
- If still running: do not proceed to pipeline work. Inform the user and wait.
- If completed: record the result location and queue the
on finish action as the
first item in Next Steps. Continue to Step 3.
- 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.
