context-persistence

What this skill does

# Context Persistence Skill

## Purpose

Ensure Claude Code can resume work seamlessly after context resets, session interruptions, or long breaks by maintaining structured documentation of current work, decisions, and progress.

## When to Use This Skill

Automatically activates when you mention:
- Waypoint plans, waypoint planning
- Resuming work, continuing work
- Session survival, context reset
- Task handoff, progress tracking
- Long-running features or projects
- Need to document current state

## The Problem: Context Resets

**What happens during a context reset**:
- ❌ All conversation history lost
- ❌ Current task context forgotten
- ❌ Decisions and rationale gone
- ❌ Progress not tracked
- ❌ Have to re-explain everything

**With context persistence**:
- ✅ Current task documented
- ✅ Decisions and rationale preserved
- ✅ Progress clearly tracked
- ✅ Quick resume in < 1 minute
- ✅ Seamless handoff to future sessions

---

## Three-File Structure

The core pattern uses **three complementary files** in `plans/active/{task-name}/`:

### 1. `{task-name}-plan.md` - The Strategic Plan

**Purpose**: High-level strategy and approach

**Contains**:
- Feature/task overview
- Requirements and acceptance criteria
- Architecture approach
- Implementation phases
- Dependencies and constraints
- Risks and mitigations

**Update frequency**: Rarely (only when approach changes)

**Example**:
```markdown
# Authentication Implementation Plan

## Overview
Add JWT-based authentication to replace session cookies for mobile app support.

## Requirements
- JWT tokens with refresh mechanism
- Supabase Auth integration
- Protected API routes
- Mobile-friendly (stateless)

## Architecture
- Auth middleware in Edge Functions
- Token storage in httpOnly cookies (web) + AsyncStorage (mobile)
- Row-Level Security policies for data access

## Implementation Phases
1. Supabase Auth setup
2. Edge Function auth middleware
3. Frontend auth hooks
4. RLS policies
5. Migration from existing auth

## Dependencies
- Supabase setup complete
- Database schema finalized
```

### 2. `{task-name}-context.md` - Current State & Progress

**Purpose**: Living document of current state, decisions, and progress

**Contains**:
- SESSION PROGRESS (updated frequently)
- Key decisions made
- Important discoveries
- Current blockers
- Files modified
- Quick resume instructions

**Update frequency**: After each significant change or decision

**Example**:
```markdown
# Authentication Implementation Context

## SESSION PROGRESS (2025-01-15 14:30)

### ✅ COMPLETED
- [x] Supabase Auth configured
- [x] Created auth middleware for Edge Functions
- [x] Implemented login/signup pages
- [x] Added auth context provider

### 🟡 IN PROGRESS
- [ ] Implementing token refresh logic (CURRENT)
  - Working on: lib/supabase/auth.ts
  - Next: Handle token expiration gracefully

### ⏳ PENDING
- [ ] Add RLS policies
- [ ] Migrate existing users
- [ ] Add mobile auth flow
- [ ] Write auth tests

### 🎯 NEXT ACTION
Continue implementing refreshToken() function in lib/supabase/auth.ts
- Handle expired tokens
- Refresh transparently
- Redirect to login if refresh fails

## KEY DECISIONS

### Decision: JWT vs. Session Cookies (2025-01-12)
**Chose**: JWT tokens
**Rationale**: Need stateless auth for mobile apps
**Impact**: Requires token refresh mechanism

### Decision: Supabase Auth vs. Custom (2025-01-13)
**Chose**: Supabase Auth
**Rationale**: Built-in RLS integration, handles token refresh
**Impact**: Less custom code, tighter Supabase integration

## IMPORTANT DISCOVERIES

### Token Refresh Timing
Discovered tokens expire after 1 hour by default. Need to:
- Refresh proactively at 50 minutes
- Handle edge case of offline user
- Store refresh token securely

### RLS Row vs. Column Level
Supabase RLS is row-level only, not column-level.
For sensitive columns, need separate tables.

## CURRENT BLOCKERS

None currently. Auth flow is straightforward with Supabase.

## FILES MODIFIED

### Created
- lib/supabase/auth.ts (auth utilities)
- app/(auth)/login/page.tsx
- app/(auth)/signup/page.tsx
- components/auth/auth-provider.tsx

### Modified
- lib/supabase/client.ts (added auth hooks)
- middleware.ts (added auth middleware)

## QUICK RESUME

To continue this work:
1. Read this file (context.md) for current state
2. Check tasks.md for checklist
3. Refer to plan.md for overall strategy
4. Current file: lib/supabase/auth.ts
5. Next: Implement refreshToken() function
6. After that: Test token refresh flow
```

### 3. `{task-name}-tasks.md` - Actionable Checklist

**Purpose**: Granular, actionable tasks with acceptance criteria

**Contains**:
- Detailed task breakdown
- Acceptance criteria for each task
- Dependencies between tasks
- Task status (pending/in-progress/complete)

**Update frequency**: Daily or after completing tasks

**Example**:
```markdown
# Authentication Implementation Tasks

## Phase 1: Supabase Setup ✅

- [x] Create Supabase project (Acceptance: Project created, credentials stored)
- [x] Enable Email auth provider (Acceptance: Can sign up via email)
- [x] Configure redirect URLs (Acceptance: Auth callbacks work locally + prod)
- [x] Add auth schema to database (Acceptance: Users table exists)

## Phase 2: Backend Auth 🟡

- [x] Create auth utilities (Acceptance: getUser(), signIn(), signUp() functions work)
- [ ] Implement token refresh **(IN PROGRESS)**
  - Acceptance: Tokens refresh automatically before expiry
  - Dependencies: Auth utilities complete
  - Notes: Need to handle offline case
- [ ] Add auth middleware to Edge Functions
  - Acceptance: Protected routes return 401 if not authenticated
  - Dependencies: Token refresh working
- [ ] Create auth helper for server components
  - Acceptance: Can check auth in Server Components

## Phase 3: Frontend Auth ⏳

- [x] Create auth context provider (Acceptance: Auth state available app-wide)
- [x] Build login page (Acceptance: Can log in with email/password)
- [x] Build signup page (Acceptance: Can create account)
- [ ] Add protected route wrapper
  - Acceptance: Redirects to login if not authenticated
  - Dependencies: Auth context complete
- [ ] Add loading states
  - Acceptance: Shows loading spinner during auth checks

## Phase 4: Security 🔒

- [ ] Add RLS policies
  - Acceptance: Users can only access their own data
  - Files: supabase/migrations/xxx_rls_policies.sql
- [ ] Test auth edge cases
  - Expired tokens
  - Invalid tokens
  - Network failures
  - Concurrent sessions

## Phase 5: Migration 📦

- [ ] Create migration script for existing users
- [ ] Test migration locally
- [ ] Schedule maintenance window
- [ ] Execute migration in production
- [ ] Verify all users migrated successfully
```

---

## SESSION PROGRESS Pattern

The **SESSION PROGRESS** section is the most important part of context.md:

### Structure

```markdown
## SESSION PROGRESS (2025-01-15 14:30)

### ✅ COMPLETED
[What's done - be specific]

### 🟡 IN PROGRESS
[What you're working on RIGHT NOW]

### ⏳ PENDING
[What's coming next]

### 🚫 BLOCKED
[What's preventing progress - if any]

### 🎯 NEXT ACTION
[Specific next step with file + function]
```

### Best Practices

**DO ✅**:
- Update after each significant milestone
- Be specific about current file/function
- Include "NEXT ACTION" for easy resume
- Mark completed items immediately
- Note blockers as they arise

**DON'T ❌**:
- Leave stale progress (update regularly)
- Be vague ("working on auth" → "implementing refreshToken() in auth.ts")
- Forget to mark completed items
- Skip the NEXT ACTION (critical for resume)

### Update Frequency

| Event | Update SESSION PROGRESS? |
|-------|-------------------------|
| Completed a full task | ✅ Yes |
| Significant decision made | ✅ Yes |
| Discovered blocker | ✅ Yes |
| Changed approach | ✅ Yes |
| Switching to different task | ✅ Yes |
| Minor code change | ❌ No |
| Formatting/cleanup | ❌ No |
| Reading code | ❌ No |

---

## Quick Resume Instructions

Always include this section in contex