Next

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:

2. If condition exceeds threshold AND no pending task with this condition_key exists:

Create maintenance task:

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:

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):

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.

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:

# 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?

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:

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:

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:

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:

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):

## 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: