Update Knowledge Base

Capture architectural context, design rationale, and non-obvious patterns learned during this session into .claude/knowledge/ files.

Determine Target Location

First, detect where to write knowledge files:

Check if we’re in a git repository with git rev-parse --show-toplevel
If yes (repo context): write to <repo-root>/.claude/knowledge/. Update the Knowledge Base table in the repo’s CLAUDE.md if you create new files.
If no (no repo, spike, ad hoc session): write to ~/dev/claude/.claude/knowledge/. These are cross-project insights. Update ~/dev/claude/.claude/knowledge/INDEX.md if you create new files (create the index if it doesn’t exist).

Create the target .claude/knowledge/ directory if it doesn’t exist yet.

Review the conversation for insights that would be valuable in future sessions:
- Design decisions and their rationale (know-why)
- Non-obvious patterns, gotchas, or procedural sequences (know-how)
- Architectural constraints or trade-offs
- Integration quirks with external services
- Edge cases and failure modes discovered
Check existing knowledge files in the target directory to avoid duplication
Update or create knowledge files:
- If an existing file covers the topic, update it with new insights
- If no file covers it, create a new one with a descriptive name
- Use kebab-case filenames (e.g., auth-flow-gotchas.md)
- Trim stale content that no longer applies

Keep files focused and scannable:

# Topic Title

## Section
Concise explanation of the pattern, gotcha, or rationale.
Include code snippets only when they clarify the point.