# Knowledge Base

This directory contains project knowledge that accumulates over time.

## Structure

```
knowledge/
├── INDEX.md       # Start here — inventory of all knowledge
├── templates/     # Structural templates for each category
├── decisions/     # Architecture Decision Records (ADRs)
├── features/      # Complex feature documentation
├── notes/         # Technical discoveries and learnings
└── product/       # User research and product docs
```

## Templates

Use templates from `templates/` when creating new knowledge docs. Each template includes
a frontmatter block with required metadata fields.

### Required Frontmatter

All knowledge docs must include YAML frontmatter:

```yaml
---
title: "Descriptive title"
created: 2026-03-17
lastUpdated: 2026-03-17
relatedIssues: [FLY-123, FLY-456]
---
```

Additional fields vary by category — see the template for each type.

**Always update `lastUpdated`** when modifying an existing doc.

## When to Create Knowledge

### Decisions (`decisions/`)

Add an ADR when you make a significant technical choice:

- Choosing a framework or library
- Designing a system architecture
- Establishing a pattern that others should follow
- Rejecting an approach (document why, so others don't repeat the investigation)

**Format**: `NNN-title.md` (e.g., `001-use-convex.md`)
**Template**: `templates/decision.md`

### Features (`features/`)

Add feature documentation when:

- A feature is too complex for just a spec
- Multiple specs relate to one system
- Future developers will need deep context

**Format**: `feature-name.md` (e.g., `auth-system.md`)
**Template**: `templates/feature.md`

### Notes (`notes/`)

Add notes when you discover:

- API quirks or gotchas
- Performance optimizations
- Debugging techniques
- Third-party service behaviors
- Workarounds that aren't obvious from code

**Format**: `topic-name.md` (e.g., `stripe-webhooks.md`)
**Template**: `templates/note.md`

### Product (`product/`)

Add product docs for:

- User personas
- User flows and journeys
- Research findings
- Product requirements

**Format**: `document-name.md` (e.g., `personas.md`)

## When to Prompt for Knowledge Capture

Proactively suggest creating a knowledge doc when:

- An architectural decision was made during implementation
- A non-obvious workaround or debugging technique was discovered
- A third-party API or integration behavior was learned through trial and error
- A pattern was established that future work should follow
- A significant feature was completed that spans multiple issues

The `/knowledge` command provides a guided flow for creating docs.

## Always Update INDEX.md

When adding or modifying any knowledge document:

1. Add or update the entry in `INDEX.md`
2. Set the date to the current date (never leave as `YYYY-MM-DD`)
3. Write a concise description that helps agents assess relevance without loading the full doc

## Relationship to Specs

- **Specs** (in issue tracker) = What we're building now
- **Knowledge** (here) = What we've learned that persists

Specs reference knowledge. Knowledge grows from implementing specs.