lucidlabs-hq/session-end

Session End

Clean up and sync state before ending a development session.

Why Session End?

1. Time Tracking - Session-Dauer wird gespeichert
2. Linear Visibility - Team knows current status
3. Clean State - Next session can resume easily
4. Compliance Check - Catch issues before they accumulate
5. Reporting - Enable progress tracking and analytics

---

Session End Checklist

┌─────────────────────────────────────────────────────────────────┐
│                     SESSION END CHECKLIST                        │
├─────────────────────────────────────────────────────────────────┤
│  [ ] 0. Time Tracking - Session gespeichert                     │
│  [ ] 1. Git Status Clean                                        │
│  [ ] 2. Linear Ticket Updated                                   │
│  [ ] 3. Work Summary Added                                      │
│  [ ] 4. PROJECT-STATUS.md Updated                               │
│  [ ] 5. No Uncommitted Changes (or WIP commit)                  │
└─────────────────────────────────────────────────────────────────┘

---

Process

0. Time Tracking - Session speichern (ZUERST!)

0a. Stop Heartbeat (before anything else):

TIME_DIR="$HOME/.claude-time"
PROJECT_NAME=$(basename "$(pwd)")
SESSION_FILE="$TIME_DIR/sessions/$PROJECT_NAME.json"
CURRENT_SESSION="$TIME_DIR/current-session.txt"
HEARTBEAT_PID_FILE="$TIME_DIR/heartbeat-${PROJECT_NAME}.pid"
HEARTBEAT_FILE="$TIME_DIR/heartbeat-${PROJECT_NAME}.txt"

# Stop heartbeat background process
if [ -f "$HEARTBEAT_PID_FILE" ]; then
  HEARTBEAT_PID=$(cat "$HEARTBEAT_PID_FILE")
  kill "$HEARTBEAT_PID" 2>/dev/null
  rm -f "$HEARTBEAT_PID_FILE" "$HEARTBEAT_FILE"
fi

0b. Calculate session duration (epoch-based):

if [ -f "$CURRENT_SESSION" ]; then
  START_EPOCH=$(grep "^Started:" "$CURRENT_SESSION" | awk '{print $2}')
  END_EPOCH=$(date +%s)
  DURATION_SECONDS=$((END_EPOCH - START_EPOCH))

  # Cap at 8 hours for plausibility
  MAX_SESSION_SECONDS=28800
  if [ "$DURATION_SECONDS" -gt "$MAX_SESSION_SECONDS" ]; then
    DURATION_SECONDS=$MAX_SESSION_SECONDS
  fi

  DURATION_MINUTES=$((DURATION_SECONDS / 60))

  # Extract human-readable times
  START_ISO=$(grep "^StartISO:" "$CURRENT_SESSION" | awk '{print $2}')
  START_TIME=$(echo "$START_ISO" | cut -dT -f2 | cut -d: -f1-2)
  END_TIME=$(date "+%H:%M")
  SESSION_DATE=$(date "+%Y-%m-%d")
fi

0c. Save session and cleanup:

After saving the session entry to $SESSION_FILE (append to sessions array), clean up:

# Remove current-session marker
rm -f "$CURRENT_SESSION"

# Update developer.json aggregates
# Read current total, add DURATION_MINUTES, write back total_minutes_all_time

Session-Zusammenfassung anzeigen (KOMPAKT):

┌─────────────────────────────────────────────────────────────────────────────────┐
│  SESSION BEENDET                                              [project-name]    │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  BEARBEITETE TICKETS                              ZEIT: 3h 30min               │
│  ───────────────────────────────────────────────────────────────────────────── │
│  ✓ CUS-42   Login Feature implementieren          Delivery      2h 15min       │
│  ◐ CUS-45   Error Handling verbessern            In Progress    1h 15min       │
│                                                                                 │
│  COMMITS (4)                                                                    │
│  ───────────────────────────────────────────────────────────────────────────── │
│  abc1234  feat(auth): implement login flow                                      │
│  def5678  fix(api): handle edge cases                                           │
│  ghi9012  feat(prime): add ASCII banner                                         │
│  jkl3456  docs: update time tracking                                            │
│                                                                                 │
│  BUDGET: ████████████████████░░░░░░░░░░░░░░░░░░░░░ 48% (48h/100h)              │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Wichtig: Diese Zusammenfassung ist bewusst KOMPAKT gehalten. Details werden in Report-Datei gespeichert.

Session-Daten speichern:

Die Session wird in ~/.claude-time/sessions/[project].json gespeichert:

{
  "sessions": [
    {
      "date": "2026-01-28",
      "start": "14:00",
      "end": "17:30",
      "duration_minutes": 210,
      "linear_issue": "CUS-42",
      "commits": ["abc1234", "def5678", "ghi9012"],
      "synced_to_productive": false
    }
  ]
}

Frage nach Productive.io Sync:

Soll ich die Session zu Productive.io synchronisieren? [Y/n]

→ JA: /time-sync wird ausgeführt
→ NEIN: Session bleibt als "pending" markiert

---

1. Check Git Status

# Show current branch and status
git branch --show-current
git status --short

# Check for uncommitted changes
git diff --stat

If uncommitted changes exist:

• Ask: "Soll ich die Änderungen committen oder als WIP markieren?"
• Option A: Create proper commit with /commit
• Option B: Create WIP commit: git commit -am "WIP: [description]"

2. Verify Last Commit Compliance

# Show last commit
git log -1 --oneline

# Check commit message format
git log -1 --format="%s"

Verify:

• [ ] Conventional commit format (feat:, fix:, docs:, etc.)
• [ ] No AI attribution (no Co-Authored-By)
• [ ] Descriptive message

3. Run Quick Validation

cd frontend && pnpm run validate

If validation fails:

• Report issues but don't block
• Add to Linear ticket as blocker for next session

4. Update Linear Ticket

Query current active issue and update:

Use Linear MCP:
1. Get current issue (from PROJECT-STATUS.md or ask)
2. Update status if needed:
   - Still in Exploration? Stay there
   - Exploration complete? → Decision
   - Implementing? → Delivery
   - Ready for review? → Review
3. Add comment with work summary

Comment Format:

## Session Update - [Date]

### Completed
- [What was done]

### Next Steps
- [What needs to happen next]

### Blockers (if any)
- [Any issues blocking progress]

5. Update PROJECT-STATUS.md

# Project Status

**Last Updated:** [timestamp]
**Linear Issue:** [ABC-123]
**Status:** [Current status]

## Last Session
- [Summary of work done]

## Next Session
- [What to pick up]

## Active Plan
- File: `.agents/plans/[plan].md`
- Progress: [X/Y tasks]

---

Output Report

## Session End Report

### Git Status
- Branch: `feature/xyz`
- Last Commit: `abc1234 feat: implement feature`
- Working Tree: Clean ✓

### Validation
- TypeScript: ✓
- ESLint: ✓
- Build: [not run / ✓]

### Linear
- Issue: ABC-123
- Status: Exploration → Delivery
- Comment: Added work summary

### Ready for Next Session
- PROJECT-STATUS.md updated
- Linear ticket current
- No pending changes

**Quick Resume:** [One sentence for next session]

---

6. Improvement Analyzer (VOR Checkout!)

WICHTIG: Dieser Schritt analysiert die Session und gibt dem Entwickler konkrete Verbesserungsvorschläge.

6.1 Session-Analyse durchführen

Analysiere während der Session:

• Wie oft musste Claude nachfragen?
• Welche Informationen fehlten?
• Welche Anweisungen waren unklar?
• Wie effizient war die Zusammenarbeit?

6.2 Kompakte Ausgabe (im Terminal)

┌─────────────────────────────────────────────────────────────────────────────────┐
│  IMPROVEMENT ANALYZER                                                           │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  SESSION SCORE: ████████░░ 78/100                                              │
│                                                                                 │
│  TOP 3 VERBESSERUNGEN FÜR NÄCHSTE SESSION:                                     │
│  ─────────────────────────────────────────────────────────────────────────────  │
│                                                                                 │
│  1. [!] Mehr Kontext bei Feature-Requests                                       │
│     → Nächstes Mal: "Kontext: [Situation], Problem: [X], Ziel: [Y]"            │
│                                                                                 │
│  2. [!] Akzeptanzkriterien definieren                                          │
│     → Nächstes Mal: Was muss funktionieren, damit Feature "fertig" ist?        │
│                                                                                 │
│  3. [!] Scope klar eingrenzen                                                  │
│     → Nächstes Mal: "Nur X, nicht Y" explizit angeben                          │
│                                                                                 │
│  ─────────────────────────────────────────────────────────────────────────────  │
│  --> Vollständiger Report: ~/.claude-time/reports/[project]-[date].md           │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

6.3 Vollständiger Report (in Datei)

Speichere detaillierten Report in ~/.claude-time/reports/[project]-YYYY-MM-DD.md:

# Session Report: [project-name]
**Datum:** 2026-01-28
**Dauer:** 3h 30min
**Entwickler:** Adam

---

## Bearbeitete Tickets

| Ticket | Titel | Status | Zeit |
|--------|-------|--------|------|
| CUS-42 | Login Feature | ✓ Erledigt | 2h 15min |
| CUS-45 | Error Handling | ◐ In Progress | 1h 15min |

---

## Commits

- `abc1234` feat(auth): implement login flow
- `def5678` fix(api): handle edge cases
- `ghi9012` feat(prime): add ASCII banner
- `jkl3456` docs: update time tracking

---

## Improvement Patterns Analyzer

### Top Recurring Issues (diese Session)

| Pattern | Häufigkeit | Zeit-Impact |
|---------|------------|-------------|
| Missing Context | 3x | ~15min |
| Vage Anforderungen | 2x | ~10min |
| Fehlende Beispiele | 1x | ~5min |

### Detaillierte Analyse

#### 1. Missing Context (3x gefunden)

**Was passiert ist:**
- Anfrage ohne Hintergrund-Information
- Claude musste Rückfragen stellen

**Beispiele aus dieser Session:**
- ❌ "Mach das Feature fertig"
- ❌ "Fix den Bug"

**Besser nächstes Mal:**

✅ "Kontext: [aktuelle Situation] Problem: [konkretes Problem] Ziel: [gewünschtes Ergebnis] Einschränkungen: [falls vorhanden]"

**Geschätzter Zeitgewinn:** ~5min pro Anfrage

---

#### 2. Vage Anforderungen (2x gefunden)

**Was passiert ist:**
- Anforderungen waren interpretierbar
- Mehrere Implementierungen wären möglich gewesen

**Beispiele aus dieser Session:**
- ❌ "Mach die UI besser"
- ❌ "Optimiere das"

**Besser nächstes Mal:**

✅ "Ändere den Button von grau auf blau" ✅ "Reduziere die Ladezeit von 3s auf unter 1s"

**Geschätzter Zeitgewinn:** ~5min pro Anfrage

---

## Session-Metriken

| Metrik | Wert | Benchmark |
|--------|------|-----------|
| Nachfragen von Claude | 4 | < 2 ideal |
| Scope-Änderungen | 1 | 0 ideal |
| Rework nötig | 0 | 0 ideal |
| Effizienz-Score | 78% | > 85% ideal |

---

## Empfohlene Templates

### Feature Request Template

Kontext: [Was ist die aktuelle Situation?] Problem: [Was funktioniert nicht / fehlt?] Ziel: [Was soll am Ende rauskommen?] Akzeptanzkriterien:

• [ ] Kriterium 1
• [ ] Kriterium 2 Einschränkungen: [Was soll NICHT gemacht werden?]

### Bug Report Template

Erwartetes Verhalten: [Was sollte passieren?] Aktuelles Verhalten: [Was passiert stattdessen?] Reproduktion: [Schritte zum Reproduzieren] Relevanter Code: [Datei:Zeile oder Snippet]

---

*Report generiert: 2026-01-28 17:30*

6.4 Pattern-Tracking über Zeit

Die Improvement Patterns werden in ~/.claude-time/patterns/[project].json aggregiert:

{
  "project": "customer-portal",
  "patterns": {
    "missing_context": {
      "total_occurrences": 34,
      "sessions_affected": 12,
      "trend": "improving",
      "last_30_days": 8
    },
    "vague_requirements": {
      "total_occurrences": 26,
      "sessions_affected": 10,
      "trend": "stable",
      "last_30_days": 6
    }
  },
  "overall_score_trend": [72, 75, 78, 80, 78]
}

6.5 Was wird analysiert?

| Pattern | Erkennung | |---------|-----------| | Missing Context | Claude fragt "Was meinst du mit...?" oder "Kannst du mehr Kontext geben?" | | Vage Anforderungen | Mehrere Interpretationen möglich, Claude fragt nach Präferenz | | Fehlende Beispiele | Claude fragt "Hast du ein Beispiel?" | | Scope Creep | Anforderungen ändern sich während Implementierung | | Fehlende Akzeptanzkriterien | Unklar wann Feature "fertig" ist |

---

Automatic Triggers

Consider running /session-end when:

• User says "bye", "fertig", "Feierabend"
• Before switching to different project
• After completing a feature
• End of day

---

Skip Session End

If skipping (e.g., quick break):

⚠️ Skipping session-end. Remember to run it before long breaks!

---

Integration with session-closer Agent

This skill invokes the session-closer agent for:

• Git compliance verification
• Automated ticket updates
• Comprehensive status reporting

The agent runs automatically when /session-end is called.