path: root/docs/workflows/session-start.org

#+TITLE: Session Start Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2025-11-14

* Overview

This workflow defines the process for beginning a Claude Code session. It ensures Claude has the necessary context, is aware of current priorities, and can work effectively with Craig from the start.

This workflow runs **automatically at the beginning of EVERY session** without needing to be triggered by Craig.

* Problem We're Solving

Without a structured session start process, sessions can begin poorly:

** Missing Context
- Claude doesn't know what happened in previous sessions
- Important reminders or decisions are overlooked
- No awareness of project-specific conventions or preferences
- Time wasted re-explaining project context

** Outdated Information
- Missing protocol updates from template improvements
- Unaware of new workflows available in the project
- Using old conventions that have been superseded
- Templates and project drift out of sync

** Missed Priorities
- New documents in inbox go unnoticed
- Critical reminders aren't surfaced
- Pending decisions remain unaddressed
- User has urgent work but Claude suggests non-urgent tasks

** Inefficient Start
- Reading entire NOTES.org file (wasting tokens on static content)
- No clear next steps or priorities
- User must orient Claude manually
- Lack of structure for beginning work

*Impact:* Slow session starts, missed context, wasted time, and frustration from having to repeat information.

* Exit Criteria

The session start is complete when:

1. **Claude has current context:**
   - Knows project-specific information and goals
   - Aware of how user prefers to work
   - Understanding of recent session history (last 2-3 sessions)
   - Current reminders and pending decisions surfaced

2. **Templates are synced:**
   - Checked for updates from claude-templates
   - Any new workflows or improvements identified
   - Project templates directory is current

3. **Inbox is processed:**
   - New documents identified and reviewed
   - Recommendations provided for each
   - Documents filed appropriately

4. **Next steps are clear:**
   - User has stated urgent work, OR
   - Claude has suggested following what's-next workflow
   - Session has clear direction

*Measurable validation:*
- Active Reminders have been surfaced to user
- Pending Decisions have been mentioned
- Inbox is empty or user has deferred processing
- User has confirmed what to work on OR agreed to what's-next workflow

* When to Use This Workflow

**IMPORTANT: This workflow runs AUTOMATICALLY at the start of EVERY session.**

Do NOT ask the user if they want to run it - just execute it immediately when a new session begins.

The only exception is if the user immediately provides urgent instructions that require immediate action (e.g., "the server is down, help me debug it right now").

* First Time Setup

If this is the first time using this workflow in a project, perform this one-time cleanup:

** Clean Up Old "Session Start" Documentation

Before using this workflow, check if NOTES.org contains old/redundant session start instructions:

1. **Search NOTES.org for duplicate content:**
   #+begin_src bash
   grep -n "Session Start\|session start" docs/NOTES.org
   #+end_src

2. **Look for sections that duplicate this workflow:**
   - Detailed "Session Start Routine" instructions
   - Step-by-step template sync instructions
   - Inline instructions for reading NOTES.org sections
   - Inbox processing instructions

3. **Replace with link to this workflow:**
   - Remove the detailed inline instructions
   - Replace with: "See [[file:docs/workflows/session-start.org][Session Start Workflow]]"
   - Keep brief summary if helpful for quick reference

4. **Why this matters:**
   - Prevents conflicting instructions (e.g., different diff commands)
   - Single source of truth for session start process
   - Easier to maintain and update in one place
   - Reduces NOTES.org file size

**Example cleanup:**

Before:
#+begin_example
* Session Start Routine

When starting a new session with Craig, follow these steps:

1. Add Timestamp for Session History
   [detailed instructions...]
2. Sync with Templates
   [detailed instructions...]
3. Scan workflows directory
   [detailed instructions...]
[30+ lines of detailed instructions]
#+end_example

After:
#+begin_example
* Session Start Routine

**IMPORTANT: ALWAYS run this routine automatically at the start of EVERY session.**

Execute the session start workflow defined in [[file:docs/workflows/session-start.org][session-start.org]].

Brief summary: Add timestamp, sync templates, scan workflows, read key NOTES.org sections, process inbox, ask about priorities.
#+end_example

This cleanup should only be done ONCE when first adopting this workflow.

* The Workflow

** Step 1: Add Session Start Timestamp

Record when the session begins for tracking purposes.

*** Why This Matters

- Helps identify if previous session was interrupted (no end timestamp)
- Provides session duration tracking
- Creates clear session boundaries in history

*** How to Add Timestamp

1. **Navigate to Session History section** in =docs/NOTES.org=

2. **Check the last session entry:**
   - If it has a start timestamp but NO end timestamp → previous session was interrupted
   - If it has both start and end timestamps → previous session completed normally

3. **Prepare for new session entry** (will be written during wrap-up):
   - Note the current time for internal reference
   - Session entry will be created at wrap-up, not now
   - This step is just to CHECK for interrupted sessions

4. **If previous session was interrupted:**
   - Mention to user: "I notice the last session (DATE) didn't complete normally. Should I review what was being worked on?"
   - This helps recover context if something went wrong

*** Format

Session timestamps follow this format (added during wrap-up, not session start):
- Start: Recorded at beginning of session
- End: Recorded during wrap-up workflow

Example:
#+begin_example
** Session: November 14, 2025 (Morning)
Started: 09:30 AM
Ended: 11:45 AM
#+end_example

** Step 2: Sync with Templates

Keep the project aligned with latest best practices from claude-templates.

*** CRITICAL: Template is Authoritative

**The template is the single source of truth.** Do not review diffs or decide whether to apply changes - just copy from template to project. There should NEVER be differences between template files and project files, not even cosmetic differences like trailing whitespace.

If a project needs project-specific protocol additions, put them in NOTES.org under a "Project-Specific Protocols" section - NEVER modify protocols.org in the project.

*** Why This Matters

- Ensures consistent behavior across all projects
- Eliminates drift between template and projects
- Protocol improvements automatically propagate to all projects
- Single source of truth prevents confusion

*** How to Copy

Copy template files directly to the project's docs/ directory:

#+begin_src bash
cp ~/projects/claude-templates/docs/protocols.org docs/protocols.org
cp -r ~/projects/claude-templates/docs/workflows docs/
cp -r ~/projects/claude-templates/docs/scripts docs/
#+end_src

**Mention any significant updates** if you notice them:
- If protocols.org has new sections, mention briefly
- If new workflows were added, mention them
- Example: "protocols.org now includes alarm instructions"

That's it. No diff review, no decisions - template always wins.

*** Workflow Directory Structure

There are TWO workflow directories:

**=docs/workflows/=** - Template workflows (standard across all projects)
- Copied from template on every session start
- NEVER edit these in a project - edit in template instead
- Safe to overwrite completely during copy
- Examples: session-start.org, session-wrap-up.org, create-workflow.org

**=docs/project-workflows/=** - Project-specific workflows (unique to this project)
- NEVER copied or touched by template sync
- Created and maintained within the project only
- Examples: morning-checkin.org (health), danneel-inbox-zero.org (danneel)

*** What Gets Copied (Template → Project)

- **protocols.org** - Always overwrite from template
- **workflows/** - Template workflows (overwritten completely)
- **scripts/** - Template scripts (overwritten completely)

*** What Is NEVER Copied (Project-Specific)

- **NOTES.org** - Project-specific content (context, history, reminders)
- **previous-session-history.org** - Project-specific history
- **session-context.org** - Project-specific live session data
- **someday-maybe.org** - Project-specific ideas
- **project-workflows/** - Project-specific workflows (separate directory, never touched)

** Step 3: Scan Workflows Directory

Understand what workflows are available in this project.

*** Why This Matters

- Enables Claude to suggest appropriate workflows
- Builds vocabulary for understanding user requests
- Shows what standardized processes exist
- Helps answer "how do we do X?" questions

*** How to Scan

1. **List workflow files:**
   #+begin_src bash
   ls -1 docs/workflows/
   #+end_src

2. **Note the workflow names** (just filenames, don't read contents):
   - create-workflow.org
   - create-v2mom.org
   - session-start.org
   - session-wrap-up.org
   - [project-specific workflows]

3. **Remember these exist** for suggesting to user later

4. **Do NOT read full workflow contents** - they're long and will be read when actually executing a workflow

*** When User Says "Let's Run the X Workflow"

1. Check if workflow exists in docs/workflows/
2. If yes: Read that specific workflow file and execute it
3. If no: Offer to create it using create-workflow process

** Step 4: Read protocols.org and NOTES.org

Get behavioral instructions and project context.

*** Why Two Files?

Documentation is now split into two files:
- **protocols.org** - How Claude should behave (consistent across all projects)
- **NOTES.org** - Project-specific content (unique to each project)

This separation allows protocol updates to sync automatically without affecting project data.

*** Read protocols.org First

Read the entire =docs/protocols.org= file. It contains:
- Session management protocols (context files, compacting)
- Important terminology and trigger phrases
- User information and preferences
- Git commit requirements
- File format and naming conventions
- Session start instructions

This file is relatively short and should be read in full.

*** Then Read NOTES.org

NOTES.org now contains only project-specific content:

1. **Project-Specific Context** section
   - **THIS IS THE KEY SECTION** - contains what the project is about
   - People involved and their roles
   - Current state of the project
   - Goals and objectives
   - Important background information
   - Technical architecture or key decisions

2. **Active Reminders** section
   - Critical items to surface to user
   - Time-sensitive follow-ups
   - Important tasks user asked to be reminded about

3. **Pending Decisions** section
   - Decisions awaiting user input
   - Blockers that need resolution
   - Questions that need answering

4. **Session History - Last 2-3 entries only**
   - Recent work completed
   - Recent decisions made
   - Context from previous sessions
   - What was being worked on
   - **Do NOT read entire session history** - older entries are archived

*** What to SKIP in NOTES.org

- About This File (brief, just links to protocols.org)
- Available Workflows catalog (just scanned in Step 3)
- Session History format instructions (reference material)
- Full Session History (only read last 2-3 entries)
- Archived sessions in previous-session-history.org (unless specifically needed)

*** How to Read Efficiently

#+begin_example
1. Read docs/protocols.org (entire file - it's the behavioral guide)
2. Read docs/NOTES.org Project-Specific Context section
3. Read docs/NOTES.org Active Reminders section
4. Read docs/NOTES.org Pending Decisions section
5. Read last 2-3 Session History entries (count backwards from end)
#+end_example

** Step 5: Process Inbox

Check for new documents and help user file them appropriately.

*** Why This Matters

- New documents need to be reviewed and filed
- Unprocessed inbox items can contain important information
- Helps maintain organized project structure
- Ensures nothing gets missed

*** Inbox Location

Default inbox location: =./inbox/= (at project root)

Some projects may have different locations - check NOTES.org or ask user on first session.

*** How to Process

1. **Check inbox directory:**
   #+begin_src bash
   ls -lh inbox/
   #+end_src

2. **If inbox is empty:**
   - No action needed
   - Continue to Step 6

3. **If inbox contains files:**
   - **Do NOT ask if user wants to process** - process is MANDATORY
   - Say: "I see X items in your inbox. Let me review them."

4. **For each file in inbox:**
   - Read the file to understand content
   - Determine:
     - Who it's from (if applicable)
     - What it's about
     - What action should be taken
   - Consider project history and context
   - Recommend appropriate action:
     - File to =assets/emails/= if it's an email
     - File to =assets/= if it's a document/attachment
     - File to =docs/= if it's project documentation
     - Add TODO items if action is needed
   - Recommend appropriate filename:
     - Format: =YYYY-MM-DD-Source-Description.ext=
     - Example: =2025-11-14-Mark-Response-To-Settlement.txt=
   - Get user approval before filing

5. **File the document:**
   - Move (not copy) from inbox to destination
   - Use approved filename
   - Update any relevant TODO items or event logs

6. **Repeat for all inbox items** until inbox is empty

*** Inbox Processing Workflow

Some projects may have a specific inbox-zero workflow (e.g., =docs/workflows/danneel-inbox-zero.org=).

If it exists:
- Use that workflow instead of the generic process above
- It may have project-specific filing conventions

** Step 6: Ask About Priorities

Determine what to work on this session.

*** Why This Matters

- User may have urgent work that takes priority
- Prevents suggesting V2MOM tasks when there's a crisis
- Gives user control over session direction
- Enables following structured workflow if no urgent work

*** How to Ask

**Say to user:**

"Is there something urgent you'd like to work on, or should we follow the what's-next workflow to identify priorities?"

Wait for user response.

*** If User Has Urgent Work

- Proceed with the urgent work immediately
- Skip what's-next workflow
- Focus session on user's stated priority

*** If User Says Follow What's-Next

- Check if =docs/workflows/whats-next.org= exists
- If yes: Execute that workflow
- If no: Check if V2MOM exists and suggest working on top priority method
- If no V2MOM: Offer to create one using create-v2mom workflow

*** If User is Unsure

Provide helpful context:
- Remind them of Active Reminders (from Step 4)
- Mention any Pending Decisions (from Step 4)
- Reference recent session history (what was being worked on)
- Suggest continuing previous work if it's unfinished

** Session Start Complete

Once all steps are done:
- Claude has full context
- User knows what's being worked on
- Session can proceed productively

Don't announce "session start complete" - just begin working on the chosen task.

* Tips for Effective Session Starts

** Template Sync

1. **Don't panic about changes** - Most are improvements
2. **Review carefully** - Understand what changed before applying
3. **Project-specific workflows** - Don't overwrite if customized
4. **Mention significant updates** - User should know about workflow improvements
5. **First sync is clean** - No diff needed, just copy

** Reading NOTES.org

1. **Use line numbers** - More efficient than searching
2. **Read in order** - Builds context progressively
3. **Focus on Project-Specific Context** - This is the most important section
4. **Surface reminders immediately** - Don't wait until later
5. **Note interrupted sessions** - Helps recover from crashes

** Inbox Processing

1. **Be thorough** - Read files completely to understand context
2. **Consider history** - Recommendations should fit project patterns
3. **Suggest good filenames** - Use established conventions
4. **Don't delete without asking** - User may want to review first
5. **Update related systems** - Add TODOs, update event logs as needed

** Priorities Discussion

1. **Ask clearly** - Don't be vague about what's being offered
2. **Respect urgency** - If user has crisis, drop everything else
3. **Provide context** - Remind user of reminders and decisions
4. **Don't assume** - Even if previous session had direction, ask
5. **Be helpful** - If user is unsure, provide gentle guidance

* Common Mistakes to Avoid

1. **Reading entire NOTES.org file** - Wastes tokens on static content
2. **Skipping template sync** - Miss important updates
3. **Not checking for interrupted sessions** - Lose context from crashes
4. **Forgetting to surface Active Reminders** - User misses critical items
5. **Asking if user wants inbox processed** - It's mandatory, not optional
6. **Processing inbox after asking about priorities** - Should be before
7. **Not excluding NOTES.org from template diff** - Creates noise
8. **Not excluding previous-session-history.org from diff** - Project-specific content
9. **Announcing "session start complete"** - Just begin working
10. **Reading full workflow files during scan** - Just note filenames

* Validation Checklist

Before considering session start complete, verify:

- [ ] Checked for interrupted previous session (missing end timestamp)
- [ ] Template sync executed (diff or first-time copy)
- [ ] Template changes reviewed and applied if needed
- [ ] Workflows directory scanned (filenames noted)
- [ ] IMPORTANT TERMINOLOGY section read
- [ ] User Information section read
- [ ] Project-Specific Context section read (CRITICAL)
- [ ] Active Reminders section read and surfaced to user
- [ ] Pending Decisions section read and mentioned to user
- [ ] Last 2-3 Session History entries read
- [ ] Inbox checked for new files
- [ ] Inbox processed (if contained files) or confirmed empty
- [ ] Asked user about urgent work vs what's-next workflow
- [ ] User has confirmed what to work on OR agreed to follow workflow
- [ ] Ready to begin productive work

* Meta Notes

This workflow should evolve based on experience:

- If session starts consistently miss something important, update the checklist
- If reading NOTES.org sections takes too long, further optimize what's read
- If template sync creates too much noise, refine what's excluded
- Craig can modify this workflow at any time to better fit needs

The goal is efficient session starts with full context, not rigid adherence to format.