# Decision: Use SQLite for local cache (not Redis)

## Context
Need persistent cache for API responses to reduce latency.
Considering SQLite vs Redis for local deployment.

## Decision
SQLite with 5-minute TTL.

## Rationale
- No external dependencies (Redis requires separate process)
- Sufficient performance for ‹10k entries
- File-based: easy backup/debugging
- Built-in expiration via DELETE trigger

## Alternatives Considered
- Redis: Better performance but operational complexity
- In-memory dict: No persistence across restarts
- File cache: No query capability, manual expiration

## Consequences
- If cache grows ›10k entries, revisit Redis
- Backup strategy: copy .db file (no dump/restore needed)
- Testing: Use :memory: db for unit tests

## Tags
#architecture #caching #sqlite #decisions

Date: 2026-02-15
Session: ag-2047

decided to use sqlite for caching because it's simpler

# Failed Approach: Token-based auth for WebSocket

## What We Tried
Pass JWT in WebSocket URL query parameter for authentication.

## Why It Failed
- Query params logged in plaintext (security issue)
- URL length limit ~2000 chars (tokens can be 500+)
- Browser history captures full URL (leak risk)

## Observable Symptoms
- Auth failures for long-lived tokens
- Security scanner flagged query param secrets
- Tokens visible in server access logs

## What We Did Instead
Use Sec-WebSocket-Protocol header for token (RFC 6455).
Client sends token in header, server validates before upgrade.

## Lessons
- Never put secrets in URLs (even over HTTPS)
- WebSocket headers are the blessed path for auth
- Test with production-sized tokens, not "test123"

## Tags
#websocket #authentication #failures #security

Date: 2026-02-15
Session: ag-2048

tried query params but didn't work, used headers instead

# Pattern: Retry with Exponential Backoff

## Where Used
- `api/client.go`: External API calls
- `queue/consumer.go`: Message processing
- `db/migrations.go`: Schema updates

## Structure
```go
func withRetry(fn func() error, maxAttempts int) error {
    for attempt := 1; attempt <= maxAttempts; attempt++ {
        err := fn()
        if err == nil {
            return nil
        }
        if !isRetryable(err) {
            return err
        }
        backoff := time.Duration(math.Pow(2, float64(attempt))) * time.Second
        time.Sleep(backoff)
    }
    return fmt.Errorf("max retries exceeded")
}

**Why this works:**
- New code can follow the pattern
- Gotchas prevent common mistakes
- When NOT to use prevents misapplication
- Related patterns guide next steps

**Bad version:**

Where? How? When should I use it? When shouldn't I?

### Good Extraction: Mental Models and Gotchas

The most valuable extractions are mental models (how to think about the system) and integration gotchas (where reality diverges from documentation).

**Mental model example:** Don't just note "the pipeline is kind of like a state machine." Document the states, transitions, why this framing helps, and how to apply it when adding new stages. A good mental model extraction transforms how people think about the code.

**Integration gotcha example:** Don't just write "watch out for GitHub rate limits." Document the official story vs actual behavior, how you got burned, the fix with code, and observable symptoms. Future developers need specifics to avoid repeating your mistakes.

### The Extraction Workflow

**At session end:**

1. **Trigger extraction** - `/post-mortem`, `/retro`, or manual review
2. **Answer extraction questions:**
   - What did I decide and why?
   - What approaches failed and why?
   - What patterns did I discover?
   - What gotchas should others know?
   - What mental model helps here?

3. **Create structured artifacts:**
   - Decision records
   - Failure logs
   - Pattern documentation
   - Mental model guides
   - Integration gotcha notes

4. **Tag and file appropriately:**
   - Add to knowledge base
   - Link from related code
   - Update project docs
   - Feed to AgentOps flywheel

5. **Make it searchable:**
   - Descriptive titles
   - Relevant tags
   - Observable symptoms for debugging
   - Keywords future you will search for

**Time investment:** 5-15 minutes per session
**ROI:** Prevents hours of duplicate work

### Extraction Formats

Different knowledge types need different formats:

| Knowledge Type | Format | Example |
|---------------|---------|---------|
| Decisions | Decision record | "Why we chose X" |
| Failures | Failure log | "Why approach Y failed" |
| Patterns | Pattern catalog | "How we handle Z" |
| Gotchas | Gotcha documentation | "API quirk W" |
| Mental models | Model guide | "Think of it as..." |

Use templates so extractions are comparable and searchable. Pick a system and use it consistently — inconsistent extraction is only marginally better than no extraction.

### Extraction Smells

Bad extraction has tells: vague summaries ("had some trouble but figured it out"), no decisions documented, only happy path covered, no observable symptoms, and solutions without context.

**Good extraction answers:** What? Why? How? When? When not? What else did you try? What should someone watch out for?

### The Discipline

Extraction is not natural. After solving a hard problem, your brain wants celebration, not documentation. This is why extraction must be part of the workflow — not optional, not "when you have time."

**Extract from every session.** Small extractions are fine. One decision record. One failure note. One pattern observation. If the session was valuable, the extraction is mandatory.

Note that extraction differs from documentation. Documentation describes how the system works ("call function X with parameter Y"). Extraction describes how it came to work this way ("we chose X over Y because Z"). Documentation enables usage. Extraction enables change. You need both.

### Organizational Impact

Extraction quality compounds. Month 1: you stop repeating your own mistakes. Month 3: new teammates find answers without asking. Month 6: common patterns are cataloged and decisions are traceable. Year 1: architectural evolution is documented and mistakes are not repeated across teams.

**Without extraction:** Every session starts from zero. The organization has no memory. **With extraction:** Knowledge accumulates. The organization gets smarter over time.

---

## Examples

### Example: Bad Session (No Extraction)

**Three months later:** Someone hits the same bug in a different service. Spends 4 hours debugging. Finds the merged PR but not the rationale. Implements a different fix. Now two services solve the same problem differently.

**Cost of missing extraction:** 4 hours duplicate work + inconsistent patterns

### Example: Good Session (With Extraction)

func validateToken(token string) error {
    tokenType := extractTokenType(token)
    key := getKeyForType(tokenType) // Different keys!
    return verifySignature(token, key)
}

**Three months later:** Someone working on refresh tokens searches for "refresh token." Finds this extraction. Understands the token type system. Implements new feature correctly. No bugs. No duplicate debugging.

**Value of extraction:** 4 hours saved + consistency maintained

See the "What Good Looks Like" section above for additional extraction formats: decision records, failure logs, and pattern catalogs.

---

## Without Tooling

You don't need a knowledge flywheel or extraction CLI. You need five minutes at the end of every session.

### The End-of-Session Ritual

Before closing any work session, answer four questions in a text file:

1. **What did I decide?** — Any non-obvious choices, with the reasoning
2. **What failed?** — Approaches that didn't work, and why
3. **What pattern did I discover?** — Reusable insights about the codebase or tools
4. **What will trip up the next person?** — Gotchas, edge cases, surprising behavior

### Where to Put Extractions

Create a `learnings/` directory in your project. One file per session:

### The Minimum Viable Extraction

Even a three-line commit message body is better than nothing:

That's extraction. Three lines. Thirty seconds. The next person who hits the same race condition finds this in `git log` and saves an hour.

### Building the Habit

- **Set a timer** — when your session hits 90 minutes, pause and extract
- **Extract before committing** — make it part of your commit workflow
- **Review your own extractions** — they should be useful to someone who wasn't in the session
- **Keep them searchable** — use consistent headings so grep works

---

## The Bottom Line

**You are responsible for two outputs:**

1. **The work product** - Code, features, fixes
2. **The knowledge product** - What you learned doing it

Most teams only care about #1. They ship code and forget the process. Six months later they can't remember why they made the decisions they made. They repeat mistakes. They re-explore dead ends. They lose institutional knowledge with every personnel change.

**Elite teams extract from every session.**

They document decisions when they make them. They catalog patterns as they discover them. They record failures so others won't repeat them. They build mental model guides that transform how people think.

**The discipline is simple:**

At the end of every session, before you close the tab, ask:
- What did I decide?
- What failed?
- What pattern emerged?
- What will trip up the next person?

Then create structured artifacts answering those questions.

Five minutes of extraction can save five hours of duplicate work.

**A session you didn't extract from is a session the organization forgot.**

Don't let your knowledge evaporate. Extract it. Structure it. Make it searchable.

Your future self will thank you. Your teammates will thank you. Your organization will accumulate knowledge instead of resetting to zero with every personnel change.

**Extract from every session. No exceptions.**