Rethink

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.note for the note type name in output
   • Use vocabulary.rethink for the command name in output
   • Use vocabulary.topic_map for MOC references
   • Use vocabulary.cmd_reflect for connection-finding references

2. ops/config.yaml — thresholds, processing preferences

   • self_evolution.observation_threshold: number of pending observations before suggesting rethink (default: 10)
   • self_evolution.tension_threshold: number of pending tensions before suggesting rethink (default: 5)

3. ops/methodology/ — existing methodology notes (read all to understand current system self-knowledge)

If these files don't exist (pre-init invocation or standalone use), use universal defaults.

The command name itself transforms per domain. The derivation manifest maps the universal name to domain-native language. If no manifest exists, use "rethink" as the command name.

EXECUTE NOW

Target: $ARGUMENTS

Parse immediately:

• If target is empty: run full six-phase rethink (Phase 0 drift check + five evidence phases) on all pending observations and tensions
• If target is "triage": run Phase 1 only (triage and methodology updates, no pattern detection)
• If target is "patterns": skip triage, run Phases 3-5 only (analyze existing evidence for patterns)
• If target is "drift": run Phase 0 only (drift check without triage or pattern detection)
• If target is a specific observation or tension filename: triage that single item interactively

START NOW. Reference below defines the six-phase workflow.

Philosophy

The system is not sacred. Evidence beats intuition.

Every rule in the context file, every workflow in a skill, every assumption baked into the architecture was a hypothesis at some point. Hypotheses need testing against reality. Observation notes in ops/observations/ capture friction from actual use. Tension notes in ops/tensions/ capture unresolved conflicts. Rethink first triages these individually (some become {DOMAIN:notes}, some become methodology updates, some get archived), then compares remaining evidence against what the system assumes and proposes changes when patterns emerge.

This is the scientific method applied to knowledge systems: hypothesize, implement, observe, revise.

Without this loop, generated systems ossify — they accumulate friction that never gets addressed, contradictions that never get resolved, and methodology learnings that never get elevated to system-level changes. /rethink is the immune system that prevents calcification.

Phase 0: Drift Check

Rule Zero: ops/methodology/ is the canonical specification of how this system operates. Before triaging observations, check whether the system has drifted from what the methodology says it should do.

0a. Load Methodology State

# Get all methodology notes with their metadata
for f in ops/methodology/*.md; do
  echo "=== $f ==="
  head -20 "$f"  # frontmatter with category, created, updated, status
  echo ""
done

Read all methodology notes fully. Extract:

• Each note's category, created date, updated date, status
• The behavioral assertions each note makes (the "What to Do" sections)

0b. Load System Configuration

Read:

• ops/config.yaml — current configuration state
• The context file (CLAUDE.md) — current behavioral instructions
• ops/derivation-manifest.md — vocabulary and feature state

0c. Compare Across Three Drift Types

Type 1: Staleness

# Compare config.yaml modification time vs newest methodology note
CONFIG_MTIME=$(stat -f %m ops/config.yaml 2>/dev/null || stat -c %Y ops/config.yaml 2>/dev/null || echo 0)
NEWEST_METH=$(ls -t ops/methodology/*.md 2>/dev/null | head -1)
METH_MTIME=$(stat -f %m "$NEWEST_METH" 2>/dev/null || stat -c %Y "$NEWEST_METH" 2>/dev/null || echo 0)

If CONFIG_MTIME > METH_MTIME: config has changed since methodology was last updated. Flag as staleness drift.

Type 2: Coverage Gap

For each active feature in config.yaml (features with enabled: true or features present in the active configuration), check whether a corresponding methodology note exists. Features without methodology coverage represent gaps — the system does things it cannot explain to itself.

Check these feature areas:

• Processing pipeline (is there a methodology note about processing behavior?)
• Maintenance conditions (methodology notes about when maintenance triggers?)
• Session rhythm (methodology notes about session workflow?)
• Domain-specific behaviors (methodology notes about domain vocabulary and patterns?)

Type 3: Assertion Mismatch

For each methodology note that makes a behavioral assertion ("What to Do" section), check:

• Does the context file contain instructions that align with or contradict this directive?
• Does config.yaml contain settings that align with or contradict this directive?
• Are there other methodology notes that contradict this one?

Report: which assertions align, which contradict, which have no corresponding system element.

0d. Create Drift Observations

For each drift finding, create an observation note in ops/observations/:

---
description: [specific drift finding]
category: drift
status: pending
observed: {today's date}
related_notes: ["[[methodology note]]", "[[config element]]"]
---
# [drift finding as prose sentence]

**Drift type:** staleness | coverage-gap | assertion-mismatch
**Methodology note:** [[affected note]]
**System element:** [config.yaml field, context file section, or missing coverage]
**Discrepancy:** [what the methodology says vs what the system does]

Resolution: update methodology note | update system config | flag for human review

0e. Report and Proceed

Output drift status summary:

Drift Check:
  Staleness: [N findings — config changed, methodology not updated]
  Coverage gaps: [N features without methodology notes]
  Assertion mismatches: [N contradictions between methodology and system]
  Total drift observations created: [N]

If drift observations were created, they join the pool of pending observations for Phase 1 triage. Proceed to Phase 1.

Phase 1: Triage

1a. Gather Pending Evidence

OBS_PENDING=$(grep -rl '^status: pending' ops/observations/ 2>/dev/null)
OBS_COUNT=$(echo "$OBS_PENDING" | grep -c . 2>/dev/null || echo 0)
TENSION_PENDING=$(grep -rl '^status: pending\|^status: open' ops/tensions/ 2>/dev/null)
TENSION_COUNT=$(echo "$TENSION_PENDING" | grep -c . 2>/dev/null || echo 0)

Read each pending item fully. These are small atomic notes — load all of them. Understanding the full content is required for accurate triage. If zero pending items, report clean state and exit early.

Also read ops/methodology/ to understand existing methodology notes — this prevents creating duplicates and informs whether new observations should extend existing methodology rather than create new notes.

1b. Classify Each Item

Assign exactly one disposition per observation or tension:

Triage heuristics for observations:

• Observation describes a general principle that works across sessions → PROMOTE
• Observation says "the system should do X differently" with a specific file/section → IMPLEMENT
• Observation describes agent behavior that should change (how to process, when to check, what to avoid) → METHODOLOGY
• Observation was about one specific session with no lasting value → ARCHIVE
• Observation might matter but only appeared once → KEEP PENDING

Triage heuristics for tensions:

• Tension was resolved by subsequent changes → ARCHIVE (set status: dissolved, add dissolved_reason)
• Tension reveals a genuine conflict between two {DOMAIN:notes} → PROMOTE (create a tension {DOMAIN:note} or resolution {DOMAIN:note})
• Tension points to a system workflow that needs redesigning → IMPLEMENT
• Tension is about agent methodology → METHODOLOGY
• Tension is real but resolution is unclear → KEEP PENDING

1c. Present Triage Table

Present the full triage to the user before executing any changes:

--=={ {DOMAIN:rethink} — Triage }==--

  Evidence: [N] observations, [M] tensions

  PROMOTE ([count])
    [filename] — [title] → proposed {DOMAIN:note} title
    [filename] — [title] → proposed {DOMAIN:note} title

  IMPLEMENT ([count])
    [filename] — [title] → change [specific file/section]
    [filename] — [title] → change [specific file/section]

  METHODOLOGY ([count])
    [filename] — [title] → create/update ops/methodology/[name].md
    [filename] — [title] → extends existing ops/methodology/[name].md

  ARCHIVE ([count])
    [filename] — [title] — [reason for archiving]

  KEEP PENDING ([count])
    [filename] — [title] — [why more evidence needed]

Use AskUserQuestion: "Review the triage above. Approve all, or list items to reclassify (e.g., 'keep obs-003 pending, promote obs-007 instead')."

Wait for user confirmation before proceeding to 1d. Do not execute triage without approval.

1d. Execute Triage

After user confirmation, apply all dispositions in order:

For PROMOTE items:

1. Create {DOMAIN:note} with prose-as-title in {vocabulary.notes}/
2. Follow standard note schema: YAML frontmatter (description, type, created), body developing the insight, Topics footer linking to relevant {vocabulary.topic_map}(s)
3. The observation content becomes the seed for the note body — but develop it fully, do not just copy the observation
4. Update the observation: set status: promoted, add promoted_to: [[note title]]

For IMPLEMENT items:

1. Make the specific change to the identified file/section
2. Show the change to the user (before/after) and get confirmation if the change is non-trivial
3. Update the observation/tension: set status: implemented, add implemented_in: [filepath]

For METHODOLOGY items: (see Phase 2 below)

For ARCHIVE items:

1. Update observation status: status: archived
2. For tensions being dissolved: status: dissolved, add dissolved_reason: [why]

For KEEP PENDING items:

1. No changes — leave in place

Update MOCs: After triage execution, update ops/observations.md and ops/tensions.md to reflect status changes. Move entries between Pending/Promoted/Archived/Resolved/Dissolved sections as appropriate.

Phase 2: Methodology Folder Updates

For items triaged as METHODOLOGY, create or update notes in ops/methodology/.

Creating New Methodology Notes

---
description: [what this methodology note teaches — specific enough to be actionable]
type: methodology
category: [processing | capture | connection | maintenance | voice | behavior | quality]
source: rethink
created: YYYY-MM-DD
status: active
evidence: ["obs-filename-1", "obs-filename-2"]
---

# [prose-as-title describing the learned behavior]

[Body developing the methodology learning:
- What the agent should do
- What the agent should avoid
- Why this matters (what went wrong without this)
- When this applies (scope/context)]

---

Related: [[methodology]]

Extending Existing Methodology Notes

If a methodology note with similar content already exists:

1. Do NOT create a duplicate
2. Instead, add the new evidence to the existing note
3. Update the evidence array in frontmatter
4. Strengthen or nuance the existing guidance based on the new observation
5. Update the observation: set status: implemented, add implemented_in: ops/methodology/[existing-file]

Checking for Methodology Duplicates

Before creating a new methodology note:

1. Read all files in ops/methodology/ (these are small)
2. Check if any existing note covers the same behavioral area
3. If overlap > 80%, extend rather than duplicate

Update Methodology MOC

After creating or updating methodology notes, update ops/methodology.md:

• Add new notes to the appropriate category section
• Update context phrases for modified notes

Phase 3: Pattern Detection

Analyze remaining pending evidence (post-triage) plus promoted/implemented history for systemic patterns. This is where individual data points become actionable signals.

Evidence Sources

1. Still-pending observations — items with status: pending after triage
2. Still-pending tensions — items with status: open or status: pending after triage
3. Recently promoted/implemented items — may share themes with pending items
4. Methodology notes — patterns in ops/methodology/ by category

Pattern Types

Detection Method

1. Group by category field: Sort observations by their category (methodology, process-gap, friction, surprise, quality). 3+ items in the same category = potential pattern.

2. Group by referenced {DOMAIN:topic maps} or system areas: Extract wiki links and file references from observation bodies. 3+ observations referencing the same area = recurring theme.

3. Cross-reference tensions: Check if multiple tensions share the same assumption. Multiple tensions pointing at the same thing = assumption may be wrong.

4. Check friction frequency for acceleration: Are friction observations about the same step appearing more frequently? An accelerating pattern is a stronger signal than steady-state friction.

5. Compare methodology notes against context file: If ops/methodology/ has 3+ notes in the same category that are not reflected in the context file, the methodology has converged enough for elevation.

6. Check for vocabulary drift: If observations use different terms than the derivation manifest or context file, the system's language may have drifted from the user's actual vocabulary.