# Session Summaries & Playbooks

> Document what was done so future agents (or future you) can pick up without rework. Turn one-off work into repeatable playbooks.

## When to Use

- After completing a significant body of work (new module, migration, security hardening)
- When the same process should be applied to other repos
- When handing off work to another person or AI tool
- As part of a post-mortem or retrospective

## The Pattern

Two document types:

| Type                  | Purpose                                                   | Audience                          |
| --------------------- | --------------------------------------------------------- | --------------------------------- |
| **Session Summary**   | What was done, why, and what's left                       | Future agents continuing the work |
| **Reusable Playbook** | Step-by-step checklist for applying the pattern elsewhere | Any agent working on any repo     |

## Session Summary Template

````markdown
# Session Summary: [Title]

> **Date:** YYYY-MM-DD
> **Repo(s):** <repo names>
> **Scope:** <what was accomplished>

## What Was Built

### 1. [Component/Feature Name]

- File: `path/to/file.ts`
- What: <brief description>
- Tests: <count> passing

### 2. [Component/Feature Name]

- ...

## Architecture Decisions

- **Decision:** <what was decided>
- **Reason:** <why this approach>
- **Alternative rejected:** <what was considered and why it was rejected>

## What's Pending

- [ ] <Remaining task 1>
- [ ] <Remaining task 2>

## Key Commits

| Hash    | Message                                  |
| ------- | ---------------------------------------- |
| abc1234 | feat(auth): add JWT refresh token flow   |
| def5678 | fix(auth): handle case-insensitive email |

## Verification

```bash
# Commands to verify everything works
npm test          # X tests passing
npm run typecheck # Clean
npm run build     # Succeeds
```
````

````

## Reusable Playbook Template

```markdown
# Playbook: [Process Name]

> **Apply to:** Any repo that needs [X]
> **Estimated time:** [X] hours
> **Source:** Developed during [session/project]

## Prerequisites

- [ ] <Tool or access needed>
- [ ] <Dependency installed>

## Checklist

### A. [Phase 1 Name]

- [ ] Step 1 with exact command or action
- [ ] Step 2
- [ ] Step 3

### B. [Phase 2 Name]

- [ ] Step 4
- [ ] Step 5

### C. Verification

- [ ] All tests pass
- [ ] Build succeeds
- [ ] Manual smoke test

## Quick Commands

```bash
# Most-used commands for this process
<command 1>
<command 2>
````

## Common Issues

| Problem   | Fix        |
| --------- | ---------- |
| <Issue 1> | <Solution> |
| <Issue 2> | <Solution> |

````

## Real-World Examples

### Session Summary: Telemetry Implementation

```markdown
# Session Summary: Cross-Platform Telemetry

## What Was Built
1. Platform-service telemetry module (34 tests)
   - Cosmos containers: telemetry_events, telemetry_error_clusters, telemetry_collection_policies
   - Endpoints: POST /events (batch), GET /query, GET /config, policy CRUD

2. iOS keyboard client (LysnrTelemetry.swift)
   - App Group offline queue, X-Install-Token auth
   - Instrumented at 10+ points

3. Desktop Python client (platform_telemetry.py)
   - Threading flush timer, persistent install_id

4. Browser client (telemetry.ts)
   - sendBeacon + fetch fallback, 30s flush

## Pending
- Phase 3: Error clustering alerts, geo enrichment, policy builder UI
````

### Reusable Playbook: Secrets Hygiene

```markdown
# Playbook: Secrets Hygiene (Apply to Any Repo)

### A. Inventory Secrets

- [ ] List all secrets the repo uses
- [ ] Identify which are in Key Vault vs hardcoded

### B. Add Guardrails

- [ ] scripts/secret-scan-staged.sh (commit blocker)
- [ ] scripts/secret-scan-repo.sh (push blocker)
- [ ] .husky/pre-commit → runs staged scan
- [ ] .husky/pre-push → runs repo scan
- [ ] .gitignore: .env, .env.local, _.pem, _.p12, \*.key

### C. Create Templates

- [ ] .env.example with placeholders (no real values)
- [ ] Document all env vars in AGENTS.md

### D. Rotate Compromised Secrets

- [ ] If any secret was ever in git history → rotate it NOW
```

## Where to Store

| Document Type      | Location                                | Committed?                         |
| ------------------ | --------------------------------------- | ---------------------------------- |
| Session summaries  | `docs/WINDSURF/` or `docs/sessions/`    | Yes                                |
| Reusable playbooks | `docs/playbooks/` or in session summary | Yes                                |
| Progress files     | `progress.md` (root)                    | Optional (gitignored if temporary) |
| Agent memories     | Editor memory system                    | No (editor-specific)               |

## The Playbook-to-Workflow Pipeline

When a playbook is used 3+ times, promote it to a workflow:

```
Playbook (docs/playbooks/secrets-hygiene.md)
  → Used successfully across 3 repos
  → Promote to workflow (.windsurf/workflows/security-audit.md)
  → Now any agent can run `/security-audit`
```

## Anti-Patterns

- **No documentation at all** — Next session starts from scratch
- **Documenting everything** — Focus on decisions and non-obvious steps
- **Session summaries without "what's pending"** — The most useful section for continuity
- **Playbooks without verification steps** — How do you know it worked?
- **Playbooks in agent memory only** — Memories are editor-specific; committed docs are universal

## Related Skills

- [03 — Memory Management](./03-memory-management.md)
- [06 — Multi-Session Continuity](./06-multi-session-continuity.md)
- [04 — Workflow Definitions](./04-workflow-definitions.md)
