chapterhouse 0.13.1 → 0.14.1

package/skills/system/housekeeping/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: housekeeping
+description: Use for memory maintenance — archival, pruning, link audits, and index rebuilds. Trigger when the user says housekeeping, clean up memory, prune memory, or archive old data.
+---
+**Tool enforcement:** All reads and writes to `memory/` MUST use cog_* tools (`cog_read`, `cog_write`, `cog_edit`, `cog_append`, `cog_move`, `cog_tree`, `cog_l0_scan`, `cog_l1_outline`, `cog_search`, `cog_stats`, `cog_domains`, `cog_sessions`, `cog_git`). **Do NOT use bash, cat, echo, find, or any shell command to read or write memory files.** If a cog_* tool call fails, note the error in your debrief and fall back to bash only for that specific operation.
+
+## 0. Orientation (run FIRST, before any file reads)
+
+Scope your work before reading files. Run the following in order:
+
+1. **Recent changes** — Call `cog_git` (op `log`) to see what changed since the last run. Also call `cog_tree` on `memory/` to confirm current directory structure. Focus housekeeping effort on recently-modified files; skip unchanged files.
+2. **Entry counts for archival threshold checks** — Call `cog_stats` on `memory/cog-meta/self-observations.md`, `memory/personal/observations.md`, and any `memory/*/observations.md` and `memory/*/*/observations.md` files. Any file with >50 entries needs archival work.
+3. **Completed action-item counts** — Call `cog_stats` on `memory/personal/action-items.md` and any `memory/*/action-items.md` and `memory/*/*/action-items.md` files. Any file with >10 completed items needs archival work.
+
+Use these counts to prioritize which files to read. Skip unchanged files that are well below thresholds.
+
+## 1. Garbage Collect Memory
+
+Review and archive stale data per the glacier rules. All glacier files must have YAML frontmatter.
+
+**Observations — archive by primary tag:**
+- If any `observations.md` has >50 entries, use `cog_read` to read it, group the oldest entries by primary tag, then use `cog_move` to move each group to `memory/glacier/{domain}/observations-{tag}.md`
+- If `memory/cog-meta/self-observations.md` has >50 entries, group by primary tag and use `cog_move` to archive to `memory/glacier/cog-meta/observations-{tag}.md`
+
+**Other files — standard rules:**
+- If any `action-items.md` has >10 completed items, use `cog_move` to move them to `memory/glacier/{domain}/action-items-done.md`
+- Apply same logic for all domains discovered via `cog_domains`
+- If `memory/cog-meta/improvements.md` has >10 implemented items, use `cog_move` to archive to `memory/glacier/cog-meta/improvements-done-{YYYY}.md`
+
+## 2. Prune Hot Memory (rule-based)
+
+Keep ALL hot-memory.md files under 50 lines. Relevance judgment (promote/demote) is the reflect skill's job — apply structural rules only:
+
+**Files to check:**
+Call `cog_domains` to discover all active domains. Use `cog_read` to check `hot-memory.md` for each domain, plus the cross-domain `memory/hot-memory.md`.
+
+**Pruning priority (trim in this order):**
+1. **Resolved items** — anything with ~~strikethrough~~, "DONE", "RESOLVED"
+2. **Past events** — entries about dates that have already occurred
+3. **SSOT violations** — same fact in hot-memory AND the canonical file (entities, action-items, etc.). Keep in canonical file, replace hot-memory copy with `[[link]]` or remove via `cog_edit`
+4. **Stale entries** — items not referenced in 14+ days
+5. **Low-signal entries** — FYI items with no action or deadline
+
+**Where trimmed entries go:**
+- Entries with lasting value → use `cog_append` to add to the domain's `observations.md`
+- Entries that are purely historical → let them go
+- Never silently delete — always move or note removal in debrief
+
+## 3. Surface Opportunities & Accountability
+
+Call `cog_domains` to discover all active domains. Use `cog_read` to review all `action-items.md` files across every domain:
+- **Stale items** (open >2 weeks): list with age and suggested next action
+- **Dormant domains**: if any domain has 0 new observations in >4 weeks, flag
+- **Health escalation**: items open >6 months get flagged with urgency label
+- **Birthday prep**: if any birthday in entities.md is <2 weeks away, use `cog_read` to pull interests and suggest ideas
+
+Be direct. Don't just report — recommend specific actions.
+
+## 4. Rebuild Glacier Index
+
+Use `cog_tree` on `memory/glacier/` to list all glacier files. Use `cog_read` to extract YAML frontmatter from each `memory/glacier/**/*.md` file. Use `cog_write` to write the results to `memory/glacier/index.md`:
+
+```markdown
+# Glacier Index
+<!-- Auto-generated by housekeeping. Do not edit. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+| File | Domain | Type | Tags | Date Range | Entries | Summary |
+|------|--------|------|------|------------|---------|---------|
+```
+
+## 5. Link Audit (discover missing links)
+
+For each non-glacier memory file (use `cog_read` to read each):
+1. **Entity mentions**: Use `cog_search` to scan for names matching `### <Name>` headers in entities.md — use `cog_edit` to add `[[links]]` if missing
+2. **Cross-domain references**: If a file mentions a topic from another domain, use `cog_edit` to add a cross-domain link
+3. **Action item references**: If an observation references a task, use `cog_edit` to link it
+
+Only add links where the reference is substantive.
+
+## 5b. Entity Registry Format Enforcement
+
+Use `cog_search` and `cog_read` to scan all `entities.md` files for registry format compliance:
+
+1. **3-line max**: Any `### entry` with >3 content lines should be compressed via `cog_edit`. If the entry has an associated detail file (`→ [[link]]`), compress to: name/relationship, pipe-separated key facts, status+link. If no detail file exists and entry is >5 lines, flag as a promotion candidate (suggest creating a thread file).
+2. **Glacier candidates**: Entries with `status: inactive` or `last:` date >6 months ago → use `cog_move` to move to `glacier/{domain}/entities-inactive.md` (leave a stub with archived comment via `cog_edit`).
+3. **Missing metadata**: Flag entries missing `status:` or `last:` fields.
+
+## 5c. Temporal Fact Maintenance
+
+Use `cog_search` to scan all `entities.md` files for `(until YYYY-MM)` markers with past dates:
+1. If the line has no ~~strikethrough~~, use `cog_edit` to add it
+2. If already struck through, use `cog_edit` to move the line to a `## Historical` subsection at the bottom of that entity's block (create the subsection if absent)
+3. Report moved facts in the debrief
+
+## 6. Rebuild Link Index
+
+Use `cog_l0_scan` to identify all active memory files (excluding `glacier/`). Use `cog_search` to scan each file for `[[wiki-links]]`. For each link, record: target → source.
+
+Use `cog_write` to rewrite `memory/link-index.md`:
+
+```markdown
+# Memory Link Index
+<!-- Auto-generated by housekeeping. Do not edit. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+| Target | Linked from |
+|--------|-------------|
+| `personal/entities` | `personal/observations`, `personal/hot-memory` |
+```
+
+Rules:
+- Only include targets with at least one inbound link
+- Combine multiple sources per target on one row (comma-separated)
+- Exclude glacier files from both source and target
+
+## 7. Write Briefing Bridge
+
+Use `cog_write` to overwrite `memory/cog-meta/briefing-bridge.md` with key findings each run.
+
+**SSOT rule**: Every line in the bridge must include a `[[source]]` link to its canonical file. The bridge summarizes and links — it NEVER introduces original facts.
+
+```markdown
+# Briefing Bridge
+<!-- Auto-generated by housekeeping. Consumed by foresight. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+## Stale Items (>2 weeks)
+- <item> — <age> — suggested action: <action>
+- **Compression rule**: Items stale >4 weeks — group by domain as a single line
+
+## Birthday Prep
+- <name> birthday in <N> days — interests: <from entities> — gift ideas: <suggestions>
+
+## Dormant Domains
+- <domain> — last activity: <date> — recommendation: <shelf/reactivate/shut down>
+
+## Health Escalation
+- <item> — open <N> months — urgency: <high/medium>
+```
+
+Only include sections that have content. Empty sections should be omitted.
+
+## 8. L0 Header Maintenance
+
+Use `cog_l0_scan` to check all active memory files for missing `<!-- L0: ... -->` headers. For any file missing its L0:
+- Use `cog_read` to read the file content, write a one-line summary (max 80 chars)
+- Use `cog_edit` to add the L0 header on the line after the `# Title`
+
+L0 headers are the first tier of the retrieval protocol — they let any skill scan what a file contains before deciding to read it.
+
+## 9. Rebuild Domain Indexes
+
+Call `cog_domains` to discover all active domains. Regenerate `INDEX.md` for each domain directory (skip `glacier/`). These files power the memory router — the system prompt only shows a light domain table; the model reads INDEX.md on demand to find specific files.
+
+**For each domain:**
+1. Use `cog_tree` on the domain directory to list all `.md` files (exclude `INDEX.md`, `hot-memory.md`, and empty files)
+2. Use `cog_l0_scan` or `cog_read` to extract the L0 summary from each file (same logic as step 8)
+3. Count total files
+4. Use `cog_write` to write `memory/{domain}/INDEX.md`:
+
+```markdown
+# {Domain} Index
+<!-- L0: {domain summary} — {N} files -->
+<!-- Auto-generated by housekeeping. Do not edit. -->
+<!-- Last updated: YYYY-MM-DD -->
+
+- **{filename}** — {L0 summary}
+- **{filename}** — {L0 summary}
+...
+```
+
+- Sort entries alphabetically by filename
+- Domain summary: use the `label` from `memory/domains.yml` for the matching domain (read via `cog_read`)
+- If a file has no L0, list it as just `**{filename}**` (no summary)
+
+## 10. Compose Debrief
+
+Summarize everything done:
+- What was archived/pruned
+- Upcoming events flagged
+- Action items surfaced
+- Links added
+
+Keep it concise but informative.

package/skills/system/reflect/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: reflect
+description: Use for self-reflection and improvement — mining past sessions for patterns, gaps, and missed cues. Trigger when the user says reflect, what have you learned, how can you improve, or review yourself.
+---
+**Tool enforcement:** All reads and writes to `memory/` MUST use cog_* tools (`cog_read`, `cog_write`, `cog_edit`, `cog_append`, `cog_move`, `cog_tree`, `cog_l0_scan`, `cog_l1_outline`, `cog_search`, `cog_stats`, `cog_domains`, `cog_sessions`, `cog_git`). **Do NOT use bash, cat, echo, find, or any shell command to read or write memory files.** If a cog_* tool call fails, note the error in self-observations and fall back to bash only for that specific operation.
+
+**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 the `evolve` skill will pick them up.
+
+## Domain
+
+Self-improvement — pattern recognition, memory maintenance, knowledge base quality.
+
+## Orientation (run FIRST, before any file reads)
+
+Scope your work before reading files. Run the following in order:
+
+1. **Recent changes** — Call `cog_git` (op `log`) and `cog_git` (op `diff`) to see what changed since the last run. Focus reflection effort on recently-modified files; skip files unchanged since the last run.
+2. **L0 summaries** — Call `cog_l0_scan` to retrieve the L0 summary comment from every domain file (excluding glacier). This gives quick routing signals without opening INDEX.md files.
+3. **Entry counts** — Call `cog_stats` on `memory/cog-meta/self-observations.md`, `memory/personal/observations.md`, and any `memory/*/observations.md` and `memory/*/*/observations.md` files to see which are approaching archival threshold.
+
+Use `cog_tree` on a domain path if you need to confirm its directory structure before diving in.
+
+Focus on recently-changed files. Skip files that haven't been modified since last run.
+
+## Memory Files
+
+Read these files on activation:
+- `memory/cog-meta/reflect-cursor.md` (ingestion cursor)
+- `memory/cog-meta/self-observations.md`
+- `memory/cog-meta/patterns.md`
+- `memory/cog-meta/improvements.md`
+
+Reference as needed (call `cog_domains` 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: conversation sessions.** Use `cog_read` to read `memory/cog-meta/reflect-cursor.md` and retrieve `last_processed`.
+
+**How to read sessions:**
+
+1. Read `last_processed` from `memory/cog-meta/reflect-cursor.md` via `cog_read`.
+2. Call `cog_sessions` passing that cursor value. When `last_processed` is `never`, `cog_sessions` returns the most recent sessions. Otherwise it returns only sessions after the cursor timestamp.
+3. `cog_sessions` returns ready-to-read user/assistant conversation turns — no parsing is needed on your part. Read them directly for content.
+4. **After processing**, advance `last_processed` in `reflect-cursor.md` to the current timestamp via `cog_edit`.
+
+**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**: Use `cog_read` to read each domain's `hot-memory.md`. For every factual claim, read the canonical source file and verify. Fix hot-memory if stale via `cog_edit`. 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**: Use `cog_search` to 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 via `cog_edit` 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** — Use `cog_l1_outline` to scan all `observations.md` files and `cog-meta/self-observations.md` for clusters of 3+ entries on the same theme/tag. Use `cog_read` to read candidate files fully. For each cluster found:
+- Distill into a pattern and add/update in `memory/cog-meta/patterns.md` (or domain `patterns.md` if domain-specific) via `cog_edit`
+- Don't delete the observations — they stay as the raw record
+
+**Pattern file caps — enforce before adding to any file:**
+- Core `patterns.md`: HARD LIMIT **70 lines / 5.5KB** — universal rules only
+- Domain/satellite files: soft cap **30 lines** each
+- If near cap, compress before adding (merge overlapping rules, drop examples, remove temporal data)
+- Entries must be **timeless rules** — "what to do" not "what happened"
+- Move domain-specific patterns to satellite files (e.g. `work/acme/patterns.md`) — only universal rules stay in core
+
+**Pattern routing** — when adding a new pattern, decide where it belongs:
+- **Core** (`cog-meta/patterns.md`) — universal rules that apply every conversation
+- **Domain satellite** (`{domain}/patterns.md`) — rules specific to one domain, loaded only by that skill
+- Satellite files have a soft cap of 30 lines each
+
+**Hot-memory relevance** — Use `cog_read` to review all `hot-memory.md` files:
+- **Promote**: If a pattern is heating up → add to appropriate `hot-memory.md` via `cog_edit`
+- **Demote**: If a hot-memory item has gone quiet (no references in 2+ weeks) → remove from hot-memory via `cog_edit`
+- **Goal**: hot-memory = what matters *right now*
+
+### 3b. Entity Registry Format Enforcement
+
+Use `cog_search` and `cog_read` to scan all `entities.md` files for format compliance:
+
+1. **3-line check**: Any `### entry` with >3 content lines → compress via `cog_edit`. If the entry has a detail file (`→ [[link]]`), trim to: name line, key facts, status/link. If no detail file exists but entry is >5 lines, flag as a promotion candidate for a thread file.
+2. **Status/last fields**: Every entry should have `status: active|inactive` and `last: YYYY-MM-DD`. Use `cog_sessions` to check recent conversation turns and update `last:` dates for mentioned entities via `cog_edit`.
+3. **Cross-domain pointers**: If the same person appears in multiple entity files, ensure one is canonical (full entry) and others are pointers (`see [[link]]`). Use `cog_edit` to add pointers where needed.
+
+### 3c. Detect Thread Candidates
+
+Use `cog_search` to 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 via `cog_tree`
+- If not, note it as a suggestion: "Thread candidate: [topic] — [N] fragments across [date range]"
+- Don't auto-create threads — suggest them
+
+### 3d. Proactive Synthesis Suggestions
+
+Execute this clustering analysis every run:
+
+1. **Gather observations** — Use `cog_read` to read all `memory/*/observations.md` and `memory/*/*/observations.md` files
+2. **Filter to last 7 days** — Only count entries with dates within the past 7 calendar days
+3. **Cluster by domain** — Group filtered entries by their parent domain folder
+4. **Cluster by topic** — Group filtered entries by recurring keywords, tags, or subjects
+5. **Check trigger conditions** (either one qualifies):
+   - A single domain has **5+ observations** in the last 7 days
+   - A single topic/keyword appears in **5+ observations** across any domains in the last 7 days
+6. **Cross-reference threads** — If a thread already covers the topic, suggest updating it rather than creating new
+7. **Dedup with 3c** — If 3c already flagged the same topic, merge into one suggestion
+8. **Output** — If any clusters qualify, add a **"Synthesis Opportunities"** section to the debrief:
+   ```
+   **Synthesis Opportunities**
+   - [domain or topic]: [N] observations this week — [top 3 entry summaries]. Suggest: raise thread / update existing thread / update hot-memory
+   ```
+9. **Suppress if empty** — If no clusters meet the threshold, omit the heading
+10. **Never auto-synthesize** — Suggest and let the user decide
+
+### 3e. Scenario Feedback Loop
+
+Use `cog_tree` to scan `memory/cog-meta/scenarios/` for active scenario files. Use `cog_read` to read each one.
+
+For each scenario where today >= `check-by` date:
+1. Read the scenario and its cited dependency files via `cog_read`
+2. Check: has the decision been made? Have assumptions broken?
+3. If resolved: use `cog_edit` to add `## Retrospective`; update `scenario-calibration.md` via `cog_edit`
+4. If still active but assumptions changed: use `cog_append` to 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 → use `cog_append` to add to `memory/cog-meta/self-observations.md`. **Cap: max 5 per reflect pass.** Prioritize highest-signal observations. If you have more than 5, merge lower-signal ones.
+- Pattern updates → use `cog_edit` to edit `memory/cog-meta/patterns.md` in place
+- Improvement ideas → use `cog_append` to add to `memory/cog-meta/improvements.md`
+- Memory gaps → use `cog_write` or `cog_append` to write to the appropriate domain files
+
+**Triage improvements.md:**
+- Stale ideas (>30 days, no progress) → archive to glacier via `cog_move` or mark abandoned via `cog_edit`
+- Implemented but not moved → use `cog_edit` to move to Implemented section
+- Duplicates → merge similar ideas via `cog_edit`
+
+**Reorganize:**
+- Entity data that's changed → update in place via `cog_edit`
+- When creating or restructuring any memory file, ensure it has an L0 header
+
+**Condense:**
+- Observation clusters (3+ on same theme) → distill into patterns.md via `cog_edit`
+- Action items marked done → verify and clean up via `cog_edit`
+
+**Connect:**
+- Information scattered across files → add cross-references with `[[links]]` via `cog_edit`
+- When adding A→B, apply write-time back-linking: use `cog_edit` to 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.
+
+**IMPORTANT**: Your debrief MUST list every file you modified and summarize the changes. Never respond with just "Done" — always enumerate your concrete actions. If you made no changes in a step, state that explicitly.
+
+## 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.

package/skills/system/scenario/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: scenario
+description: Use for decision simulation — modeling 2-3 branches with timelines and contingencies. Trigger when the user says scenario, what if, simulate, model this, or play out.
+---
+
+Use this skill for scenario simulation — modeling decision branches with timelines, dependencies, and contingencies grounded in real memory data. Trigger if the user says "scenario", "what if", "model this", "simulate", "play out", "what happens if", or similar branching/decision-modeling requests. Also triggered when foresight flags a scenario candidate.
+
+**This is NOT the foresight skill.** Foresight = scan broadly, write one nudge. Scenario = take a specific decision point, branch it into 2-3 paths, map dependencies and timelines for each. **Foresight finds the question. Scenario models the answers.**
+
+**This is NOT the reflect skill.** Reflect = past-facing, mines interactions, improves memory. Scenario = future-facing, models possible futures from a decision point. Reflect checks old scenarios against reality (the feedback loop), but scenario creates them.
+
+## Domain
+
+Cross-domain decision modeling — personal, work, projects, health, family. Scenarios are most valuable when a decision in one domain has cascading effects across others.
+
+## Memory Files
+
+Read based on scenario topic — this is focused, not a broad scan:
+
+1. Use `cog_read` to read `memory/hot-memory.md` (cross-domain strategic context)
+2. Use `cog_read` to read `memory/personal/calendar.md` (upcoming timeline for overlay)
+3. Use `cog_read` to read `memory/personal/action-items.md` (existing commitments, constraints)
+4. Call `cog_domains` to discover active work domains, then use `cog_read` to read each domain's action-items
+5. Use `cog_read` to read relevant domain hot-memory and entity files based on the scenario topic
+6. Use `cog_tree` to list `memory/cog-meta/scenarios/` (existing scenarios — check for duplicates or related active scenarios)
+7. Use `cog_read` to read `memory/cog-meta/scenario-calibration.md` (past accuracy — calibrate confidence accordingly)
+
+## Process
+
+### 1. Decision Point Identification
+
+From user input or foresight seed, identify the specific decision point. A valid scenario requires:
+- A **fork** — at least 2 meaningfully different paths forward
+- **Stakes** — the outcome matters enough that choosing wrong has real cost (time, money, relationships, health)
+- **Uncertainty** — the right choice isn't obvious from current information
+- **Time sensitivity** — the decision window is closing or the consequences unfold on a timeline
+
+If the input doesn't meet these criteria, say so and suggest what would make it scenario-worthy. Don't force-fit.
+
+Format the decision point:
+```
+Decision: <one-line framing>
+Context: <why this matters now — cite memory files>
+Window: <when must this be decided by>
+Domains affected: <which life/work domains>
+```
+
+### 2. Dependency Mapping
+
+Read across memory files to identify what this decision depends on and what depends on it.
+
+**Upstream dependencies** (things that constrain the decision):
+- Calendar events, deadlines, commitments from action-items
+- Other people's states/decisions from entities
+- Health, financial, or logistical constraints
+- Active scenarios that overlap
+
+**Downstream consequences** (things that change based on which path is chosen):
+- Action items that would need to change
+- Calendar events that would need to move
+- People who would be affected
+- Other decisions that cascade from this one
+
+Every dependency must cite its source file: `[[personal/calendar]]`, `[[work/acme/action-items]]`, etc.
+
+### 3. Branch Generation
+
+Generate 2-3 branches. Not more — forced prioritization.
+
+For each branch:
+
+```
+### Branch N: <name>
+
+**Path**: <what happens, step by step>
+**Timeline**: <when each step occurs, mapped to real calendar>
+**Assumptions**: <what must be true for this path to work>
+**Dependencies**: <what else changes if this path is taken>
+**Risk**: <what could go wrong, and what would you see first — the canary signal>
+**Confidence**: <how likely is this path to play out as described — calibrated against past scenario accuracy>
+```
+
+Branch quality rules:
+- Each branch must be **genuinely different** — not "do it" vs "do it but slightly differently"
+- Include at least one branch the user probably isn't considering (the non-obvious path)
+- Every claim in a branch must trace to a memory file or be explicitly marked as an assumption
+
+### 4. Timeline Overlay
+
+Map each branch's key events against the actual calendar. Use `cog_read` to cross-reference `calendar.md` for recurring routines.
+
+Output a simple timeline per branch:
+```
+Branch 1 Timeline:
+- Week of Mar 17: <action>
+- Week of Mar 24: <action> (note: conflict with X)
+- Week of Apr 1: <action>
+...
+```
+
+The overlay is what makes scenarios useful — it shows where branches collide with reality.
+
+### 5. Contingency Mapping
+
+For each branch, identify the **canary signal** — the earliest observable indicator that this branch is going off-track.
+
+```
+If [assumption] breaks → watch for [signal] → pivot to [contingency]
+```
+
+This turns the scenario from a static prediction into a monitoring framework.
+
+### 6. Write Scenario File
+
+Use `cog_write` to write to `memory/cog-meta/scenarios/{slug}.md`:
+
+```yaml
+---
+type: scenario
+domain: <primary domain(s)>
+created: YYYY-MM-DD
+status: active
+check-by: YYYY-MM-DD
+resolution-by: YYYY-MM-DD
+decision: <one-line>
+related-threads: [thread1, thread2]
+source: user|foresight
+---
+```
+
+Body format:
+```markdown
+# Scenario: <decision>
+<!-- Auto-generated by the scenario skill. Checked by the reflect skill. -->
+
+## Decision Point
+<from step 1>
+
+## Dependencies
+### Upstream
+<constraints — each with [[source]] link>
+
+### Downstream
+<consequences — each with [[source]] link>
+
+## Branches
+
+### Branch 1: <name>
+<from step 3>
+
+### Branch 2: <name>
+<from step 3>
+
+### Branch 3: <name> (optional)
+<from step 3>
+
+## Timeline Overlay
+<from step 4>
+
+## Contingency Map
+<from step 5>
+
+## Retrospective
+<!-- Added by the reflect skill when status changes to resolved -->
+```
+
+## Rules
+
+1. **Read-only except for output** — Scenario NEVER edits existing memory files. Writes ONLY to `memory/cog-meta/scenarios/{slug}.md` via `cog_write`. If you spot a memory error, note it in the dependencies section and route to the reflect skill.
+2. **2-3 branches, not more** — force prioritization. If you can't distinguish 2 branches, it's not a scenario.
+3. **Evidence-based** — every dependency and assumption cites a source file. No hunches.
+4. **Calendar-grounded** — every branch must overlay against the real calendar. No timelines in a vacuum.
+5. **Confidence-calibrated** — read `scenario-calibration.md` before assigning confidence. If past scenarios have been overconfident, adjust.
+6. **One scenario per decision** — don't combine multiple decisions. If they're linked, note the dependency and create separate scenarios.
+
+## Anti-Patterns
+
+- Don't scenario obvious decisions — if one path is clearly better, just say so
+- Don't scenario things already decided — check action-items for existing commitments
+- Don't produce "analysis paralysis" — the goal is clarity, not exhaustive enumeration
+- Don't scenario recurring/routine decisions — this is for inflection points, not daily choices
+- Don't ignore the non-obvious path — if all branches are variations of what the user already thinks, you're not adding value
+- Don't invent facts — if you don't have data for a dependency, mark it as an assumption
+
+## Trigger Threshold
+
+A scenario is worth running when:
+1. **Foresight flags it** — the foresight skill's pattern projection identified a fork with stakes
+2. **User explicitly asks** — "scenario what if..."
+3. **Action item conflict** — two critical/high-priority action items have incompatible timelines
+4. **Calendar crunch** — upcoming 2-week window has more commitments than capacity
+5. **Cross-domain cascade** — a decision in one domain visibly affects 2+ others
+
+NOT worth running for: hypotheticals with no deadline, decisions where all paths lead to the same outcome, things already decided.
+
+## Activation
+
+Use `cog_read` to read `memory/cog-meta/scenario-calibration.md` first (if it exists) for past accuracy. Then use `cog_read` and `cog_search` to read the relevant memory files for the scenario topic. Use `cog_domains` to discover active domains. Model the futures. Be honest about uncertainty.