arscontexta 0.6.0

package/skill-sources/learn/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: learn
+description: Research a topic and grow your knowledge graph. Uses Exa deep researcher, web search, or basic search to investigate topics, files results with full provenance, and chains to processing pipeline. Triggers on "/learn", "/learn [topic]", "research this", "find out about".
+user-invocable: true
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, mcp__exa__web_search_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, WebSearch
+context: fork
+model: opus
+---
+
+## EXECUTE NOW
+
+**Topic: $ARGUMENTS**
+
+Parse immediately:
+- If topic provided: research that topic
+- If topic empty: read `self/goals.md` for highest-priority unexplored direction and propose it
+- If topic includes `--deep`/`--light`/`--moderate`: force that depth, strip flag from topic
+- If no topic and no goals.md: ask "What would you like to research?"
+
+**Steps:**
+
+1. **Read config** — tool preferences, depth, domain vocabulary
+2. **Determine depth** — from flags, config default, or fallback to moderate
+3. **Research** — tool cascade: primary → fallback → last resort
+4. **File to inbox** — with full provenance metadata
+5. **Chain to processing** — next step based on pipeline chaining mode
+6. **Update goals.md** — append new research directions discovered
+
+**START NOW.** Reference below explains methodology.
+
+---
+
+## Step 1: Read Configuration
+
+```
+ops/config.yaml             — research tools, depth, pipeline chaining
+ops/derivation-manifest.md  — domain vocabulary (inbox folder, reduce skill name)
+```
+
+**From config.yaml** (defaults if missing):
+```yaml
+research:
+  primary: exa-deep-research      # exa-deep-research | exa-web-search | web-search
+  fallback: exa-web-search
+  last_resort: web-search
+  default_depth: moderate          # light | moderate | deep
+pipeline:
+  chaining: suggested             # manual | suggested | automatic
+```
+
+**From derivation-manifest.md** (universal defaults if missing):
+- Inbox folder: `inbox/` (could be `journal/`, `encounters/`, etc.)
+- Reduce skill name: `/reduce` (could be `/surface`, `/break-down`, etc.)
+- Domain name and hub MOC name
+
+---
+
+## Step 2: Determine Depth
+
+Priority: explicit flag > config default > `moderate`
+
+| Depth | Tool | Sources | Duration | Use When |
+|-------|------|---------|----------|----------|
+| light | WebSearch | 2-3 | ~5s | Checking a specific fact |
+| moderate | mcp__exa__web_search_exa | 5-8 | ~10-30s | Exploring a subtopic |
+| deep | mcp__exa__deep_researcher_start | Comprehensive | 15s-3min | Major research direction |
+
+---
+
+## Step 3: Research — Tool Cascade
+
+Output header:
+```
+Researching: [topic]
+
+  Depth: [depth]
+  Using: [tool name]
+```
+
+Try tools in config priority order. If a tool fails (MCP unavailable, error, empty results), fall to next tier. If ALL tiers fail:
+```
+FAIL: Research failed — no research tools available
+
+  Tried:
+    1. [primary] — [error]
+    2. [fallback] — [error]
+    3. WebSearch — [error]
+
+  Try again later or manually add research to [inbox-folder]/
+```
+
+### Tool Invocation Patterns
+
+**exa-deep-research:**
+```
+mcp__exa__deep_researcher_start
+  instructions: "Research comprehensively: [topic]. Focus on practical findings, key patterns, recent developments, and actionable insights."
+  model: "exa-research-fast" (moderate) | "exa-research" (deep)
+```
+Poll with `mcp__exa__deep_researcher_check` until `completed`. Output during wait:
+```
+  Research ID: [id]
+  Waiting for results...
+```
+
+**exa-web-search:**
+```
+mcp__exa__web_search_exa  query: "[topic]"  numResults: 8
+```
+
+**web-search (last resort, also used for light depth):**
+```
+WebSearch  query: "[topic]"
+```
+
+On completion: `Research complete — [source count] sources analyzed`
+
+---
+
+## Step 4: File Results to Inbox
+
+**Filename:** `YYYY-MM-DD-[slugified-topic].md` — lowercase, spaces to hyphens, no special chars.
+
+**Write to** the domain inbox folder (from derivation-manifest, default `inbox/`). Create folder if missing.
+
+### Provenance Frontmatter
+
+Every field serves the provenance chain. The `exa_prompt` field is most critical — it captures the intellectual context that shaped the research.
+
+```yaml
+---
+description: [1-2 sentence summary of key findings]
+source_type: exa-deep-research | exa-web-search | web-search
+exa_prompt: "[full query/instruction string sent to the research tool]"
+exa_research_id: "[deep researcher ID, omit for web search]"
+exa_model: "[exa-research-fast | exa-research, omit for web search]"
+exa_tool: "[mcp tool name, omit for deep researcher]"
+generated: [ISO 8601 timestamp — run: date -u +"%Y-%m-%dT%H:%M:%SZ"]
+domain: "[domain name from derivation-manifest]"
+topics: ["[[domain-hub-moc]]"]
+---
+```
+
+Include only the fields relevant to the tool used:
+- Deep researcher: `source_type`, `exa_prompt`, `exa_research_id`, `exa_model`, `generated`, `domain`, `topics`
+- Exa web search: `source_type`, `exa_prompt`, `exa_tool`, `generated`, `domain`, `topics`
+- WebSearch: `source_type`, `exa_prompt`, `exa_tool`, `generated`, `domain`, `topics`
+
+### Body Structure
+
+Format for downstream reduce extraction — findings as clear propositions, not raw dumps:
+
+```markdown
+# [Topic Title]
+
+## Key Findings
+
+[Synthesized findings organized by theme, not by source. Each finding
+should be a clear proposition the reduce phase can extract as an atomic insight.]
+
+## Sources
+
+[List of sources with titles and URLs]
+
+## Research Directions
+
+[New questions, unexplored angles, follow-up topics. These feed goals.md.]
+```
+
+---
+
+## Step 5: Chain to Processing
+
+Read chaining mode from config (default: `suggested`).
+
+```
+Research complete
+
+  Filed to: [inbox-folder]/[filename]
+
+  Next: /[reduce-skill-name] [inbox-folder]/[filename]
+```
+
+Append based on mode:
+- **manual:** (nothing extra)
+- **suggested:** `Ready for processing when you are.`
+- **automatic:** Replace "Next" line with `Queued for /[reduce-skill-name] -- processing will begin automatically.`
+
+---
+
+## Step 6: Update goals.md
+
+If `self/goals.md` exists AND the research uncovered meaningful new directions:
+
+1. Read goals.md, match existing format
+2. Append under the appropriate section:
+   ```
+   - [New direction] (discovered via /learn: [original topic])
+   ```
+
+Skip silently if goals.md missing or no meaningful directions found. Do not add filler.
+
+---
+
+## Output Summary
+
+Clean output wrapping the full flow:
+```
+ars contexta
+
+Researching: [topic]
+
+  Depth: [depth]
+  Using: [tool name]
+  [Research ID: abc-123]
+
+  Research complete -- [N] sources analyzed
+
+  Filed to: [inbox-folder]/[filename]
+
+  Next: /[reduce-skill-name] [inbox-folder]/[filename]
+    [chaining context]
+
+  [goals.md updated with N new research directions]
+```
+
+---
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| No topic, no goals.md | Ask: "What would you like to research?" |
+| Exa MCP unavailable | Fall through cascade to WebSearch |
+| All tools fail | Report failures with FAIL status, suggest manual inbox filing |
+| Deep researcher timeout (>5 min) | Report timeout, suggest `--moderate` |
+| Empty results | Report "No results found", suggest refining topic |
+| Config files missing | Use defaults silently |
+| Inbox folder missing | Create it before writing |
+
+---
+
+## Skill Selection Routing
+
+After /learn, the self-building loop continues:
+
+| Phase | Skill | Purpose |
+|-------|-------|---------|
+| Extract insights | /[reduce-name] | Mine research for atomic propositions |
+| Find connections | /[reflect-name] | Link new insights to existing graph |
+| Update old notes | /[reweave-name] | Backward pass on touched notes |
+| Quality check | /[verify-name] | Description quality, schema, links |
+
+/learn is the entry point. Each run feeds the graph, and the graph feeds the next direction through goals.md.

package/skill-sources/learn/skill.json

@@ -0,0 +1,17 @@
+{
+  "name": "knowledge-learn",
+  "description": "Research a topic and grow your knowledge graph. Uses Exa deep researcher, web search, or basic search to investigate topics, files results with full provenance, and chains to processing pipeline.",
+  "version": "0.4.0",
+  "author": "arscontexta",
+  "tags": ["knowledge-management", "research", "learning"],
+  "entry": "SKILL.md",
+  "platform_hints": {
+    "claude-code": {
+      "context": "fork",
+      "model": "opus"
+    },
+    "openclaw": {
+      "type": "external"
+    }
+  }
+}

package/skill-sources/next/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: next
+description: Surface the most valuable next action by combining task stack, queue state, inbox pressure, health, and goals. Recommends one specific action with rationale. Triggers on "/next", "what should I do", "what's next".
+version: "1.0"
+generated_from: "arscontexta-v1.6"
+user-invocable: true
+context: fork
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+## Runtime Configuration (Step 0 — before any processing)
+
+Read these files to configure domain-specific behavior:
+
+1. **`ops/derivation-manifest.md`** — vocabulary mapping, domain context
+   - Use `vocabulary.notes` for the notes folder name
+   - Use `vocabulary.inbox` for the inbox folder name
+   - Use `vocabulary.note` for the note type name in output
+   - Use `vocabulary.topic_map` for MOC references
+   - Use `vocabulary.cmd_reduce` for process/extract command
+   - Use `vocabulary.cmd_reflect` for connection-finding command
+   - Use `vocabulary.cmd_reweave` for backward-pass command
+   - Use `vocabulary.rethink` for rethink command name
+
+2. **`ops/config.yaml`** — thresholds, processing preferences
+   - `self_evolution.observation_threshold` (default: 10)
+   - `self_evolution.tension_threshold` (default: 5)
+
+If these files don't exist, use universal defaults and generic command names.
+
+## EXECUTE NOW
+
+**INVARIANT: /next recommends, it does not execute.** Present one recommendation with rationale. The user decides what to do. This prevents cognitive outsourcing where the system makes all work decisions and the user becomes a rubber stamp.
+
+**Execute these steps IN ORDER:**
+
+---
+
+### Step 1: Read Vocabulary
+
+Read `ops/derivation-manifest.md` (or fall back to `ops/derivation.md`) for domain vocabulary mapping. All output must use domain-native terms. If neither file exists, use universal terms (notes, inbox, topic map, etc).
+
+---
+
+### Step 2: Reconcile Maintenance Queue
+
+Before collecting state, evaluate all maintenance conditions and reconcile the queue. This ensures maintenance tasks are current before the recommendation engine runs.
+
+**Read queue file** (`ops/queue/queue.json` or `ops/queue.yaml`). If `schema_version` < 3, migrate:
+- Add `maintenance_conditions` section with default thresholds
+- Add `priority` field to existing tasks (default: "pipeline")
+- Set `schema_version: 3`
+
+**For each condition in maintenance_conditions:**
+
+1. **Evaluate the condition:**
+
+| Condition | Evaluation Method |
+|-----------|------------------|
+| orphan_notes | For each note in {vocabulary.notes}/, count incoming [[links]]. Zero = orphan. |
+| dangling_links | Extract all [[links]], verify targets exist as files. Missing = dangling. |
+| inbox_pressure | Count *.md in {vocabulary.inbox}/. |
+| observation_accumulation | Count status: pending in ops/observations/. |
+| tension_accumulation | Count status: pending or open in ops/tensions/. |
+| pipeline_stalled | Queue tasks with status: pending unchanged across sessions. |
+| unprocessed_sessions | Count files in ops/sessions/ without mined: true. |
+| moc_oversize | For each topic map, count linked notes. |
+| stale_notes | Notes not modified in 30+ days with < 2 links. |
+| low_link_density | Average link count across all notes. |
+| methodology_drift | Compare config.yaml modification time vs newest ops/methodology/ note modification time. If config is newer, methodology may be stale. |
+
+2. **If condition exceeds threshold AND no pending task with this condition_key exists:**
+
+Create maintenance task:
+```bash
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+MAINT_MAX=$(jq '[.tasks[] | select(.id | startswith("maint-")) | .id | ltrimstr("maint-") | tonumber] | max // 0' ops/queue/queue.json)
+NEXT_MAINT=$((MAINT_MAX + 1))
+
+jq --arg id "maint-$(printf '%03d' $NEXT_MAINT)" \
+   --arg priority "{priority}" \
+   --arg key "{condition_key}" \
+   --arg target "{description}" \
+   --arg action "{recommended command}" \
+   --arg ts "$TIMESTAMP" \
+   '.tasks += [{"id": $id, "type": "maintenance", "priority": $priority, "status": "pending", "condition_key": $key, "target": $target, "action": $action, "auto_generated": true, "created": $ts}]' \
+   ops/queue/queue.json > tmp.json && mv tmp.json ops/queue/queue.json
+```
+
+3. **If condition is satisfied AND a pending task with this condition_key exists:**
+
+Auto-close it:
+```bash
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+jq --arg key "{condition_key}" --arg ts "$TIMESTAMP" \
+   '(.tasks[] | select(.condition_key == $key and .status == "pending")).status = "done" |
+    (.tasks[] | select(.condition_key == $key and .status == "pending")).completed = $ts' \
+    ops/queue/queue.json > tmp.json && mv tmp.json ops/queue/queue.json
+```
+
+4. **If condition fires AND a pending task already exists:**
+
+Update the target description (specifics may have changed):
+```bash
+jq --arg key "{condition_key}" --arg target "{new description}" \
+   '(.tasks[] | select(.condition_key == $key and .status == "pending")).target = $target' \
+   ops/queue/queue.json > tmp.json && mv tmp.json ops/queue/queue.json
+```
+
+---
+
+### Step 3: Collect Vault State
+
+Gather all signals. Run independent checks in parallel where possible. Record each signal even if the check returns zero — absence of signal is itself informative.
+
+| Signal | How to Check | What to Record |
+|--------|--------------|----------------|
+| **Task stack** | Read `ops/tasks.md` — current priorities and open items | Top items, open count, any deadlines |
+| **Queue state** | Read `ops/queue.yaml` or `ops/queue/queue.json` — pending pipeline tasks | Total pending, by phase (create, reflect, reweave, verify), blocked phases |
+| **Inbox pressure** | Count `*.md` files in {vocabulary.inbox}/, find oldest by mtime | Count per subdirectory, age of oldest item in days |
+| **Note count** | Count `*.md` in {vocabulary.notes}/ | Total notes for context |
+| **Orphan notes** | For each note, grep for `[[filename]]` across all files — zero hits = orphan | Count, first 5 names |
+| **Dangling links** | Extract all `[[links]]` from notes/, verify each target file exists | Count, first 5 targets |
+| **Stale notes** | Notes not modified recently AND with low link density (< 2 links) | Count |
+| **Goals** | Read `self/goals.md` or `ops/goals.md` — current priorities, active threads | Priority list, active research directions |
+| **Observations** | Count files with `status: pending` in `ops/observations/` | Count |
+| **Tensions** | Count files with `status: pending` or `status: open` in `ops/tensions/` | Count |
+| **Methodology** | Check `ops/methodology/` for recent captures (files modified in last 7 days) | Count of recent, total count |
+| **Health** | Read most recent report in `ops/health/` — note timestamp and issues | Last run date, issue count, any critical issues |
+| **Sessions** | Check `ops/sessions/` for files without `mined: true` in frontmatter | Count of unmined sessions |
+| **Recent /next** | Read `ops/next-log.md` (if exists) — last 3 recommendations | Previous suggestions to avoid repetition |
+
+**Adaptation rules:**
+- Directory names adapt to domain vocabulary (e.g., {vocabulary.inbox} instead of hardcoded "inbox")
+- Skip checks silently for directories that do not exist — do not report "ops/sessions/ not found"
+- A missing directory means that feature is not active, which is valid state
+
+**Signal collection commands:**
+
+```bash
+# Inbox pressure (adapt path to vocabulary)
+INBOX_COUNT=$(find {vocabulary.inbox}/ -name "*.md" -maxdepth 2 2>/dev/null | wc -l | tr -d ' ')
+OLDEST_INBOX=$(find {vocabulary.inbox}/ -name "*.md" -maxdepth 2 -exec stat -f "%m %N" {} \; 2>/dev/null | sort -n | head -1)
+
+# Note count
+NOTE_COUNT=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')
+
+# Pending observations
+OBS_COUNT=$(grep -rl '^status: pending' ops/observations/ 2>/dev/null | wc -l | tr -d ' ')
+
+# Pending tensions
+TENSION_COUNT=$(grep -rl '^status: pending\|^status: open' ops/tensions/ 2>/dev/null | wc -l | tr -d ' ')
+
+# Unmined sessions
+SESSION_COUNT=$(grep -rL '^mined: true' ops/sessions/*.md 2>/dev/null | wc -l | tr -d ' ')
+```
+
+---
+
+### Step 4: Classify by Consequence Speed
+
+Evaluate every signal against consequence speed — how fast does inaction degrade the system?
+
+| Speed | Signals | Threshold | Why This Priority |
+|-------|---------|-----------|-------------------|
+| **Session** | Inbox > 5 items, orphan notes (any), dangling links (any), 10+ pending observations, 5+ pending tensions, unprocessed sessions > 3 | Immediate — these degrade work quality right now | Orphans are invisible to traversal. Dangling links confuse navigation. Inbox pressure means lost ideas. Observation/tension thresholds mean the system is accumulating unprocessed friction. |
+| **Multi-session** | Pipeline queue backlog > 10, research gaps identified in goals, stale notes > 10, inbox items aging > 7 days, methodology captures > 5 in same category | Soon — these compound over days | Unfinished pipeline batches block downstream connections. Stale notes represent decaying knowledge. Aging inbox means capture is outpacing processing. |
+| **Slow** | Health check not run in 14+ days, {DOMAIN:topic map} oversized (>40 notes), link density below 2.0 average, low note count relative to time | Background — annoying but not blocking | These are maintenance tasks. Important for long-term health but not urgent. |
+
+**Threshold rule:** 10+ pending observations OR 5+ pending tensions is ALWAYS session-priority. Recommend {DOMAIN:rethink} in this case.
+
+**Signal interaction rules:**
+- Task stack items ALWAYS override automated recommendations (user-set priorities beat system-detected urgency)
+- Multiple session-priority signals: pick the one with highest impact (most items affected)
+- If inbox pressure AND queue backlog: recommend reducing inbox first (pipeline needs input before it can process)
+
+---
+
+### Step 5: Generate Recommendation
+
+Select the SINGLE most valuable action. The recommendation must be specific enough to execute immediately — a concrete command invocation, not a vague suggestion.
+
+**Priority cascade:**
+
+#### 1. Task Stack First
+
+If `ops/tasks.md` has open items, recommend from the task stack. User-set priorities override all automated recommendations because:
+- The user has context the system does not
+- Ignoring explicit priorities erodes trust
+- Task stack items represent deliberate decisions, not automated detection
+
+Format: Recommend the specific task with context about why it was in the stack.
+
+#### 1.5. Session-Priority Maintenance Tasks
+
+Read queue for maintenance tasks with `priority: "session"` and `status: "pending"`. These represent vault health conditions that degrade THIS session.
+
+Pick the highest-impact one:
+- orphan_notes: "{N} notes invisible to traversal"
+- dangling_links: "{N} broken links confusing navigation"
+- inbox_pressure: "{N} items aging in inbox"
+
+Recommend the `action` field from the queue entry.
+
+#### 2. Session-Priority Signals
+
+If no task stack items, pick the highest-impact session-priority signal:
+
+| Signal | Recommendation | Rationale Template |
+|--------|---------------|-------------------|
+| Dangling links / orphans | /health or specific fix command | "You have [N] orphan notes invisible to traversal. Connecting them increases graph density and retrieval quality." |
+| 10+ observations or 5+ tensions | /{DOMAIN:rethink} | "[N] pending observations have accumulated. Pattern detection requires processing this backlog to evolve the system." |
+| Inbox > 5 items | /{DOMAIN:reduce} [specific file] | "Your inbox has [N] items (oldest: [age]). [File X] has the highest connection potential based on [reason]." |
+| Unprocessed sessions > 3 | /remember --mine-sessions | "[N] sessions have uncaptured friction patterns. Mining them prevents methodology regressions." |
+
+**When recommending inbox processing:** Choose the specific inbox item that aligns best with current goals or has the most connection potential to existing notes. Recommend a concrete file, not "process some inbox."
+
+#### 3. Multi-Session Signals
+
+If no session-priority items:
+
+| Signal | Recommendation | Rationale Template |
+|--------|---------------|-------------------|
+| Queue backlog > 10 | /ralph [N] | "[N] pipeline tasks are pending. Your newest {DOMAIN:notes} lack connections, which means they can't participate in synthesis." |
+| Stale notes > 10 | /{DOMAIN:reweave} [specific note] | "[N] notes haven't been touched since [date]. [Note X] has the most connections and would benefit most from updating." |
+| Research gaps | /{DOMAIN:reduce} [file aligned with goals] | "Your goals mention [topic] but your graph has few notes there. [Inbox item] addresses this gap." |
+| Methodology convergence | /{DOMAIN:rethink} | "[N] methodology captures in the [category] area suggest a pattern worth elevating." |
+
+**When recommending reweaving:** Choose the most-connected stale note (highest link density + oldest modification). Reweaving high-connectivity notes has the highest ripple effect.
+
+#### 4. Slow Signals
+
+If nothing pressing:
+
+| Signal | Recommendation | Rationale Template |
+|--------|---------------|-------------------|
+| No recent health check | /health | "Last health check was [date]. Running one now catches structural issues before they compound." |
+| Topic map oversized | Restructuring suggestion | "[Topic map X] has [N] notes. Splitting into sub-topic-maps improves navigation and reduces cognitive load." |
+| Low link density | /{DOMAIN:reweave} on lowest-density note | "Your graph has an average link density of [N]. Reweaving sparse notes increases traversal paths." |
+
+#### 5. Everything Clean
+
+If all signals are healthy:
+
+```
+next
+
+  All signals healthy.
+  Inbox: 0 | Queue: 0 pending | Orphans: 0 | Dangling: 0
+
+  No urgent work detected.
+
+  Suggested: Explore a new direction from goals.md
+  or reweave older {DOMAIN:notes} to deepen the graph.
+```
+
+**Rationale is always mandatory.** Every recommendation must explain:
+1. WHY this action over alternatives
+2. What DEGRADES if this action is deferred
+3. How it connects to goals (if applicable)
+
+---
+
+### Step 6: Deduplicate
+
+Read `ops/next-log.md` (if it exists). Check the last 3 entries.
+
+**Deduplication rules:**
+- If the same recommendation appeared in the last 2 entries, select the next-best action instead
+- This prevents the system from getting stuck recommending the same thing repeatedly when the user has chosen not to act on it
+- If the same recommendation is genuinely the highest priority (e.g., inbox pressure keeps growing), add an explicit note: "This was recommended previously. The signal has grown stronger since then ([before] → [now])."
+
+---
+
+### Step 7: Output
+
+```
+next
+
+  State:
+    Inbox: [count] items (oldest: [age])
+    Queue: [count] pending ([phase breakdown])
+    Orphans: [count] | Dangling: [count]
+    Observations: [count] | Tensions: [count]
+    [any other decision-relevant signals]
+
+  Recommended: [specific command/action]
+
+  Rationale: [2-3 sentences — why this action,
+  how it connects to goals, what degrades if deferred]
+
+  After that: [second priority, if relevant]
+  [optional: alignment with goals.md priority]
+```
+
+**Command specificity is mandatory.** Recommendations must be concrete invocations:
+
+| Good | Bad |
+|------|-----|
+| `/{DOMAIN:reduce} inbox/article-on-spaced-repetition.md` | "process some inbox items" |
+| `/ralph 5` | "work on the queue" |
+| `/{DOMAIN:rethink}` | "review your observations" |
+| `/{DOMAIN:reweave} [[note title here]]` | "update some old notes" |
+
+**State display rules:**
+- Show only 2-4 decision-relevant signals — not all 14 checks
+- Zero-count signals that are healthy can be omitted (don't show "Orphans: 0" unless contrasting with a problem)
+- Non-zero signals at session or multi-session priority should always be shown
+
+---
+
+### Step 8: Log the Recommendation
+
+Append to `ops/next-log.md` (create if missing):
+
+```markdown
+## YYYY-MM-DD HH:MM
+
+**State:** Inbox: [N] | Notes: [N] | Orphans: [N] | Dangling: [N] | Stale: [N] | Obs: [N] | Tensions: [N] | Queue: [N]
+**Recommended:** [action]
+**Rationale:** [one sentence]
+**Priority:** session | multi-session | slow
+```
+
+**Why log?** The log serves three purposes:
+1. Deduplication — prevents recommending the same action repeatedly
+2. Evolution tracking — shows what signals have been persistent vs transient
+3. /rethink evidence — persistent recommendations that go unacted-on may reveal misalignment between what the system detects and what the user values
+
+---
+
+## Edge Cases
+
+### Empty Vault (0-5 notes)
+
+Recommend capturing or reducing content. Maintenance is premature with < 5 notes — the graph does not have enough nodes for meaningful analysis.
+
+```
+next
+
+  State:
+    Notes: [N] — early stage vault
+
+  Recommended: Capture or /{DOMAIN:reduce} content
+  Rationale: Your graph has [N] notes. At this stage, adding
+  content matters more than maintaining structure. Health checks,
+  reweaving, and rethink become valuable after ~10 notes.
+```
+
+### Everything Clean
+
+Say so explicitly. Recommend exploratory work aligned with goals, or reflective work on older notes:
+
+```
+  No urgent work detected. Consider:
+  - Exploring a research direction from goals.md
+  - Reweaving older {DOMAIN:notes} to deepen connections
+  - Reviewing and updating goals.md itself
+```
+
+### No Goals File
+
+Recommend creating `self/goals.md` or `ops/goals.md` first. Without priorities, recommendations lack grounding and the system cannot distinguish between "important to the user" and "detected by automation."
+
+```
+  Recommended: Create ops/goals.md
+  Rationale: Without goals, /next can only recommend based on
+  automated detection. Goals let the system align recommendations
+  with what actually matters to you.
+```
+
+### No ops/derivation-manifest.md
+
+Use universal vocabulary. Do not fail — /next should always produce a recommendation regardless of configuration state.
+
+### Queue Not Active
+
+Skip queue checks silently. Not all vaults use the pipeline architecture — some rely on manual processing. Do not report "queue not found" as an issue.
+
+### Multiple Session-Priority Signals
+
+When several signals are at session priority simultaneously, pick the one that unblocks the most downstream work:
+- Dangling links block graph traversal → fix first
+- Observation threshold → rethink prevents methodology drift
+- Inbox pressure → processing prevents idea loss
+
+If genuinely equal priority, pick the one the user has not been recommended recently (check next-log.md).
+
+### Stale /next Log
+
+If `ops/next-log.md` has not been updated in 14+ days, the user may not be running /next regularly. Note this but do not make it a recommendation — /next is optional, not mandatory.
+
+---
+
+## Anti-Patterns
+
+These are patterns that /next must avoid:
+
+| Anti-Pattern | Why It Is Wrong | What to Do Instead |
+|-------------|----------------|-------------------|
+| Recommending everything | Overwhelms the user, defeats the purpose of "single most valuable action" | Pick ONE. Mention a second only as "after that" |
+| Vague recommendations | "Process inbox" gives no actionable starting point | Name the specific file, note, or command |
+| Ignoring task stack | User-set priorities exist for a reason | Always check ops/tasks.md first |
+| Repeating the same rec | If the user did not act on it, recommending it again is nagging | Deduplicate via next-log.md |
+| Recommending maintenance too early | A 5-note vault does not need health checks | Scale recommendations to vault maturity |
+| Cognitive outsourcing | Making all decisions for the user | Recommend and explain — never execute |