Session Management

STEP 1: Load Handoff
  → Check for .claude/handoff.md
  → If found: read and summarize pending work
  → If not found: note "No handoff file — starting fresh"

STEP 2: Load Memory
  → Check for MEMORY.md (project root or .claude/)
  → If found: scan for rules relevant to the likely task
  → If not found: note "No memory file — will create on first learning"

STEP 3: Load Instincts
  → Check for .claude/instincts.md
  → If found: load instincts at 0.7+ into active context
  → If not found: note "No instincts file — will create on first observation"

STEP 4: Detect .NET Solution
  → Search for .slnx files in current directory
  → If not found, search for .sln files
  → If not found, search parent directories (up to 3 levels)
  → If not found, search child directories (1 level)
  → If found: confirm MCP tools are connected
  → If not found: warn "No solution detected — MCP tools unavailable"

STEP 5: Present Summary
  "Session context loaded:
   - Last session: [summary from handoff or 'no previous session']
   - Pending tasks: [list from handoff or 'none']
   - Active rules: [count from MEMORY.md]
   - Active instincts: [count at 0.7+]
   - Solution: [solution name and path, or 'not detected']
   Ready to continue. What would you like to work on?"

STEP 1: Review Accomplishments
  → List everything completed this session with file paths
  → Include line numbers for significant changes

STEP 2: Check for Uncommitted Changes
  → Run git status
  → If uncommitted changes exist:
    "You have uncommitted changes. Want me to commit before wrapping up?"
  → If clean: note "All changes committed"

STEP 3: Write Handoff
  → Write .claude/handoff.md using the Handoff File Template (see below)

STEP 4: Extract Learnings
  → Review session for corrections from the user
  → Generalize corrections into rules (via self-correction-loop)
  → Write to MEMORY.md under appropriate category

STEP 5: Update Instincts
  → Review any new patterns observed during the session
  → Update confidence scores in .claude/instincts.md
  → Promote any instincts that reached 0.9 (via instinct-system)

STEP 6: Confirm
  "Session wrapped up:
   - Handoff written to .claude/handoff.md
   - [N] learnings added to MEMORY.md
   - [N] instincts updated
   Next session will pick up right where we left off."

SEARCH ORDER:
1. Current directory: *.slnx, *.sln
2. Parent directory: *.slnx, *.sln (common in src/ subdirectory layouts)
3. Grandparent directory: *.slnx, *.sln (up to 3 levels)
4. Child directories: */**.slnx, */**.sln (1 level deep)

PREFERENCE:
- .slnx over .sln (modern format)
- If multiple solutions found, prefer the one matching the directory name
- If still ambiguous, list all and ask the user

AFTER DETECTION:
- Confirm MCP connection by running get_project_graph
- If MCP returns "loading", wait briefly and retry (solution may be initializing)
- Cache the solution path for the session — don't re-detect on every tool call

FILE                    SCOPE       LIFETIME        PURPOSE
.claude/handoff.md      Session     Overwritten      Pass state between sessions
MEMORY.md               Project     Permanent        Store confirmed rules
.claude/instincts.md    Project     Evolving         Track emerging patterns
Git commits             Code        Permanent        Preserve code state

FLOW:
  Session N ends → writes handoff.md, updates MEMORY.md, updates instincts.md
  Session N+1 starts → reads handoff.md, MEMORY.md, instincts.md
  Result: zero context loss between sessions

# Session Handoff

> Generated: 2025-07-15 | Branch: feature/order-validation

## Completed
- [x] Added FluentValidation to CreateOrder command
  - File: `src/Orders/Features/CreateOrder.cs` (lines 15-35)
  - Validator: non-empty CustomerId, at least 1 item, positive quantities
- [x] Fixed N+1 query in GetOrderDetails
  - File: `src/Orders/Features/GetOrderDetails.cs` (line 28)
  - Added `.Include(o => o.Items)` to the query

## Pending
- [ ] Add validation to UpdateOrder command (same pattern as CreateOrder)
  - Start from: `src/Orders/Features/UpdateOrder.cs`
  - Reference: CreateOrder validator for the established pattern
- [ ] Run full test suite — last run had 2 unrelated failures in Catalog module

## Learned
- FluentValidation validators must be registered in the module's DI setup
- The N+1 in GetOrderDetails was hidden because test data seeds only 1 item per order

## Context
- Branch: feature/order-validation
- Last commit: "Add CreateOrder validation + tests"
- Uncommitted changes: no
- Solution: src/MyApp.slnx

SESSION RESUME FLOW:
1. Read .claude/handoff.md
2. Summarize concisely:
   "Last session (2025-07-15) on branch feature/order-validation:
    - Completed: CreateOrder validation, N+1 fix in GetOrderDetails
    - Pending: UpdateOrder validation, test suite failures
    Shall I continue with the UpdateOrder validation?"
3. Wait for user direction — never auto-start pending work
4. If the user wants something different, acknowledge and proceed
   "Got it, setting aside the pending tasks. What would you like to work on?"

BOOTSTRAP PROTOCOL:
1. No handoff.md → "No previous session found. Starting fresh."
2. No MEMORY.md → "No project memory found. I'll create one when we discover
   project-specific rules."
3. No instincts.md → "No instincts file. I'll start tracking patterns
   as we work together."
4. Detect solution → Run full detection, report findings
5. Offer convention scan:
   "This is our first session. Want me to scan the codebase to learn
    the project's conventions? (Uses the convention-learner skill)"

ENHANCED HANDOFF (add when multiple developers use Claude on the project):

## Decisions Made
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Validation library | FluentValidation | Already used in Catalog module |
| Error format | ProblemDetails | RFC 7807, consistent with API standard |

## Open Questions
- Should we validate product existence at command level or handler level?
  - Current: handler level (after DB lookup)
  - Trade-off: invalid product IDs return 500 instead of 400

## Dependencies
- Requires FluentValidation 11.x NuGet package (already referenced)
- No new infrastructure dependencies