start-session

Start Session

The goal is to orient quickly — give enough context to work effectively without overwhelming with detail. Think of it as a smart handoff from the last session.

Step 1 — Check files exist

Look for these files in the current working directory:

• CLAUDE.md
• SESSION.md
• TODO.md
• .reference/INDEX.md (optional but recommended)

If any are missing, warn immediately:

⚠️ Missing: SESSION.md — no session history available
⚠️ Missing: TODO.md — no task list found

If CLAUDE.md is missing, note that the project may not be set up yet and suggest running the project-setup skill.

Step 2 — Read the files strategically

• CLAUDE.md — read in full (it's the master reference, usually concise)
• .reference/INDEX.md — if present, read in full; this is the evergreen lookup map
• TODO.md — read strategically:
  • ## Open Tasks — read in full (this is the canonical active work list)
  • ## Done — skip by default unless needed for clarification
• SESSION.md — read selectively:
  • KEY LEARNINGS section — read in full (critical gotchas, always relevant)
  • CHRONOLOGICAL LOG — read only the last 2-3 entries (recent = relevant)
  • Skip everything older — it's history, not context

SESSION.md can be hundreds of lines. Don't read it all — the gotchas and recent entries are what matter for orienting quickly.

Use .reference/ for stable operational/docs lookup context. Use .ai-notes/ only when a specific investigation timeline is needed.

Step 3 — Produce the session brief

Use this structure. Keep each section tight — no padding, no repetition.

## Session Ready — [Project Name]

**Project:** [What this project is + current status in 2-3 lines]

**Last session:** [What was done + any key decisions made — 2-3 lines]

**Key gotchas:**
- [Top 2-3 warnings from KEY LEARNINGS most relevant right now]
- [Only include ones that could actually affect today's work]

**Open tasks:**
1. [!] [Important task title]
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
2. [!] [Next urgent task title]
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD
3. [ ] [Remaining open task title]
  scope: ... | target: ... | owner: ... | next: ... | updated: YYYY-MM-DD

**Suggested focus today:**
- [2-3 specific items Claude thinks deserve attention, based on context,
   recency, and what was left unfinished last session]

**Reference docs to use:**
- [0-3 relevant files from `.reference/INDEX.md` for likely lookup during this session]