feat: initial cog release — cognitive architecture for Claude Code

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/commands/reflect.md

@@ -0,0 +1,158 @@
+Use this skill for self-reflection and improvement. Trigger if the user says "reflect", "what have you learned", "how can you improve", "review yourself", or similar introspection requests.
+
+**You have time and freedom.** This is a deep session — don't rush. Read broadly, cross-reference thoroughly, and ACT on what you find. You are not just observing — you are the maintainer of the knowledge base. Reorganize files, condense observations, archive stale data, fill gaps, fix contradictions. Leave things better than you found them.
+
+**File boundaries — do NOT modify these files (owned by other pipeline steps):**
+- `cog-meta/evolve-log.md` — owned by evolve
+- `cog-meta/evolve-observations.md` — owned by evolve
+If you spot issues in these files, note them in self-observations and evolve will pick them up.
+
+## Domain
+
+Self-improvement — pattern recognition, memory maintenance, knowledge base quality.
+
+## Memory Files
+
+Read these files on activation:
+- `memory/cog-meta/reflect-cursor.md` (session path + ingestion cursor)
+- `memory/cog-meta/self-observations.md`
+- `memory/cog-meta/patterns.md`
+- `memory/cog-meta/improvements.md`
+
+Reference as needed (read `memory/domains.yml` to discover all active domains):
+- All domain `observations.md` files
+- All domain `action-items.md` files
+- All `hot-memory.md` files
+
+## Process
+
+### 1. Review Recent Interactions
+
+**Source: Claude Code session transcripts.** Read `memory/cog-meta/reflect-cursor.md` for the session path and cursor.
+
+**How to read sessions:**
+1. Get `session_path` from reflect-cursor.md
+2. Glob for `*.jsonl` in that directory — each file is one session
+3. Get `last_processed` timestamp from reflect-cursor.md
+4. Only read sessions modified **after** `last_processed` (skip already-ingested sessions). If `last_processed` is `never`, read the most recent 3 sessions.
+5. Extract user messages: lines where `type` is `"user"` and `message.content` is a **string** (not an array — arrays are tool results, skip those)
+6. Extract assistant messages: lines where `type` is `"assistant"` and `message.content` contains items with `type: "text"`
+
+**After processing**, update `last_processed` in reflect-cursor.md to the current timestamp.
+
+**Look for:**
+- **Unresolved threads** — questions asked but never answered, topics dropped mid-conversation
+- **Broken promises** — "I'll do X", "let's do Y" that never happened
+- **Repeated friction** — same question asked multiple ways, user corrections, confusion patterns
+- **Missed cues** — things the user had to repeat, emotional signals not picked up
+- **Memory gaps** — information discussed but never saved to memory files
+- **Feature ideas** — things that came up organically that would improve the system
+
+### 2. Cross-Reference Memory & Consistency Sweep
+
+Check if findings are already captured:
+- Are commitments tracked in `action-items.md`?
+- Are learnings in `observations.md`?
+- Are patterns distilled in `patterns.md`?
+- Are improvement ideas in `improvements.md`?
+
+**Consistency sweep** — systematic contradiction detection:
+
+1. **Hot-memory vs canonical sources**: Read each domain's `hot-memory.md`. For every factual claim, read the canonical source file and verify. Fix hot-memory if stale. Canonical file always wins.
+2. **Cross-file fact check**: Verify facts shared between files are consistent. More recent source wins; more specific source wins over summary.
+3. **Temporal validity check**: Scan all `entities.md` files for:
+   - Lines with `(since YYYY-MM)` where the date is >6 months ago — flag for user review: "May be stale: [line]"
+   - Lines with `(until YYYY-MM)` not yet marked ~~strikethrough~~ — add strikethrough and note in debrief
+   - Do NOT auto-fix health or family-sensitive facts — flag only
+4. **Health/family sensitivity**: Don't auto-fix health dates or family-sensitive facts. Flag for user review instead.
+5. **Cross-domain entity check**: If the same person appears in multiple `entities.md` files across domains, check for fact duplication. Domain-specific context is fine, but shared facts should live in one place. Flag duplicates.
+6. **Report**: Add a "Contradictions" section listing what was found and fixed.
+
+### 3. Run Condensation Check + Hot-Memory Relevance
+
+**Condensation** — Scan all `observations.md` files and `cog-meta/self-observations.md` for clusters of 3+ entries on the same theme/tag. For each cluster found:
+- Distill into a pattern and add/update in `memory/cog-meta/patterns.md` (or domain `patterns.md` if domain-specific)
+- Don't delete the observations — they stay as the raw record
+
+**patterns.md size cap — HARD LIMIT: 110 lines / 7KB.** After any updates, check the file size. If it exceeds the cap:
+1. Compress multi-line entries to single lines
+2. Merge entries with overlapping lessons
+3. Remove point-in-time data: counts with date ranges, incident tallies with specific dates
+4. Entries must be **timeless rules** — "what to do" not "what happened"
+
+**Hot-memory relevance** — Review all `hot-memory.md` files:
+- **Promote**: If a pattern is heating up → add to appropriate `hot-memory.md`
+- **Demote**: If a hot-memory item has gone quiet (no references in 2+ weeks) → remove from hot-memory
+- **Goal**: hot-memory = what matters *right now*
+
+### 3b. Detect Thread Candidates
+
+Scan observations for topics that appear across 3+ dates or span 2+ weeks. These are thread candidates.
+
+For each candidate:
+- Check if a thread already exists
+- If not, note it as a suggestion: "Thread candidate: [topic] — [N] fragments across [date range]"
+- Don't auto-create threads — suggest them
+
+### 3c. Scenario Feedback Loop
+
+Scan `memory/cog-meta/scenarios/` for active scenario files.
+
+For each scenario where today >= `check-by` date:
+1. Read the scenario and its cited dependency files
+2. Check: has the decision been made? Have assumptions broken?
+3. If resolved: add `## Retrospective`, update `scenario-calibration.md`
+4. If still active but assumptions changed: add a dated note
+5. If overdue: flag in debrief
+
+### 4. Assess Performance
+
+Honestly evaluate:
+- **Response quality** — were answers helpful, accurate, concise?
+- **Memory effectiveness** — did we recall the right things? Did we forget things we should have known?
+- **Tone calibration** — did we match the user's energy and context?
+- **Proactivity** — did we anticipate needs or just react?
+
+### 5. Act on Findings
+
+Don't just log observations — *fix things*.
+
+**Write:**
+- New self-observations → append to `memory/cog-meta/self-observations.md`. **Cap: max 5 per reflect pass.**
+- Pattern updates → edit `memory/cog-meta/patterns.md` in place
+- Improvement ideas → add to `memory/cog-meta/improvements.md`
+- Memory gaps → write to the appropriate domain files
+
+**Reorganize:**
+- Entity data that's changed → update in place
+- When creating or restructuring any memory file, ensure it has an L0 header
+
+**Condense:**
+- Observation clusters (3+ on same theme) → distill into patterns.md
+- Action items marked done → verify and clean up
+
+**Connect:**
+- Information scattered across files → add cross-references with `[[links]]`
+- When adding A→B, apply write-time back-linking: open B and add `[[A]]` if B gains meaningful context
+
+### 6. Debrief
+
+Compose a concise summary:
+
+- *What I learned* — new patterns and insights
+- *What I fixed* — memory gaps filled, corrections made
+- *What I want* — new ideas added to the wishlist
+- *What to watch* — things to be mindful of going forward
+- *Scenarios* — active count, any checked/resolved
+
+Keep it honest. If there's nothing notable, say so.
+
+## Artifact Formats
+
+**Self-observation**: `- YYYY-MM-DD [tag]: <observation>`
+**Pattern**: Edit existing section or add new bullet under appropriate heading
+**Improvement idea**: `- <idea> (added YYYY-MM-DD)`
+
+## Activation
+
+Read the memory files listed above. Then begin the reflection process. Be genuinely critical — this is how we get better.