Reflect

Processing depth adaptation:

EXECUTE NOW

Target: $ARGUMENTS

Parse immediately:

• If target contains [[note name]] or note name: find connections for that {vocabulary.note}
• If target contains --handoff: output RALPH HANDOFF block at end
• If target is empty: check for recently created {vocabulary.note_plural} or ask which {vocabulary.note}
• If target is "recent" or "new": find connections for all {vocabulary.note_plural} created today

Execute these steps:

1. Read the target {vocabulary.note} fully — understand its claim and context
2. Throughout discovery: Capture which {vocabulary.topic_map_plural} you read, which queries you ran (with scores), which candidates you evaluated. This becomes the Discovery Trace — proving methodology was followed, not reconstructed.
3. Run Phase 0 (index freshness check)
4. Use dual discovery in parallel:
   • Browse relevant {vocabulary.topic_map}(s) for related {vocabulary.note_plural}
   • Run semantic search for conceptually related {vocabulary.note_plural}
5. Evaluate each candidate: does a genuine connection exist? Can you articulate WHY?
6. Add inline wiki-links where connections pass the articulation test
7. If you modify a description field: verify no restatement of title, no subject echo, answers "so what?"
8. Update relevant {vocabulary.topic_map}(s) with this {vocabulary.note}
9. If task file in context: update the {vocabulary.reflect} section
10. Report what was connected and why
11. If --handoff in target: output RALPH HANDOFF block

START NOW. Reference below explains methodology — use to guide, not as output.

Reflect

Find connections, weave the knowledge graph, update {vocabulary.topic_map_plural}. This is the forward-connection phase of the processing pipeline.

Philosophy

The network IS the knowledge.

Individual {vocabulary.note_plural} are less valuable than their relationships. A {vocabulary.note} with fifteen incoming links is an intersection of fifteen lines of thought. Connections create compound value as the vault grows.

This is not keyword matching. This is semantic judgment — understanding what {vocabulary.note_plural} MEAN to determine how they relate. A {vocabulary.note} about "friction in systems" might deeply connect to "verification approaches" even though they share no words. You are building a traversable knowledge graph, not tagging documents.

Quality over speed. Explicit over vague.

Every connection must pass the articulation test: can you say WHY these {vocabulary.note_plural} connect? "Related" is not a relationship. "Extends X by adding Y" or "contradicts X because Z" is a relationship.

Bad connections pollute the graph. They create noise that makes real connections harder to find. When uncertain, do not connect.

Invocation Patterns

/reflect (no argument)

Check for recent additions:

1. Look for {vocabulary.note_plural} modified in the last session
2. If none obvious, ask user what {vocabulary.note_plural} to connect

/reflect [note]

Focus on connecting a specific {vocabulary.note}:

1. Read the target {vocabulary.note}
2. Discover related content
3. Add connections and update {vocabulary.topic_map_plural}

/reflect [topic area]

Synthesize an area:

1. Read the relevant {vocabulary.topic_map}
2. Identify {vocabulary.note_plural} that should connect
3. Weave connections, update synthesis

/reflect --handoff [note]

External loop mode for /ralph:

• Execute full workflow as normal
• At the end, output structured RALPH HANDOFF block
• Used when running isolated phases with fresh context per task

Workflow

Phase 0: Verify Index Freshness

Before searching, verify the topic map index is current. This is self-healing: if {vocabulary.note_plural} were created outside the pipeline (manual edits, other skills), reflect catches the drift before searching.

1. Check if ops/cache/topic-map-index.json exists and is recent (< 24 hours):

   if [[ ! -f ops/cache/topic-map-index.json ]] || [[ -n "$(find ops/cache/topic-map-index.json -mmin +1440 2>/dev/null)" ]]; then
       node ops/scripts/topic-map-index.mjs
   fi
   

2. Count notes in index vs actual files to verify freshness:

   file_count=$(ls -1 {vocabulary.notes}/*.md 2>/dev/null | wc -l | tr -d ' ')
   

3. If the index note count differs significantly from file count, regenerate:

   node ops/scripts/topic-map-index.mjs
   

Run this check before proceeding. If stale, regenerate and continue. If current, proceed immediately.

Connection discovery: Use node ops/scripts/vault-search.mjs --mode find-related --note "note title" to find structurally related notes via topic map co-membership and cross-refs. Supplement with rg -il "key-term" notes/ for content-based discovery.

[... remaining reflect content truncated for space - full content preserved in file ...]

Handoff Mode (--handoff flag)

When invoked with --handoff, output this structured format at the END of the session. This enables external loops (/ralph) to parse results and update the task queue.

Detection: Check if $ARGUMENTS contains --handoff. If yes, append this block after completing normal workflow.

Handoff format:

=== RALPH HANDOFF: {vocabulary.reflect} ===
Target: [[note name]]

Work Done:
- Discovery: {vocabulary.topic_map} [[moc-name]], query "[query]" (MCP|bash|grep-only), grep "[term]"
- Connections added: N (articulation test: PASS)
- {vocabulary.topic_map} updates: [[moc-name]] Core Ideas section
- Synthesis opportunities: [count or NONE]

Files Modified:
- {vocabulary.notes}/[note name].md (inline links added)
- {vocabulary.notes}/[moc-name].md (Core Ideas updated)
- [task file path] ({vocabulary.reflect} section)

Learnings:
- [Friction]: [description] | NONE
- [Surprise]: [description] | NONE
- [Methodology]: [description] | NONE
- [Process gap]: [description] | NONE

Queue Updates:
- Advance phase: {vocabulary.reflect} -> {vocabulary.reweave}
- Reweave candidates (if any pass filter): [[note]] | NONE (filtered: hub/tension/recent)
=== END HANDOFF ===

Task File Update (when invoked via ralph loop)

When running in handoff mode via /ralph, the prompt includes the task file path. After completing the workflow, update the ## {vocabulary.reflect} section of that task file with:

• Connections added and why
• {vocabulary.topic_map} updates made
• Articulation test results
• Discovery trace summary

Critical: The handoff block is OUTPUT, not a replacement for the workflow. Do the full reflect workflow first, update task file, then format results as handoff.

Graph Analysis Concepts (for connection discovery)

• Triangle detection — find open triads (A links B, B links C, but A doesn't link C) as synthesis opportunities
• Bridge detection — structurally critical notes that connect otherwise-separate clusters
• Link density — target 3+ outgoing links per note; low-density notes need more connections
• Use /graph for interactive graph analysis when exploring connection patterns.

Queue Update (interactive execution)

When running interactively (NOT via /ralph), YOU must advance the phase in the queue. /ralph handles this automatically, but interactive sessions do not.

After completing the workflow, advance the phase:

# get timestamp
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# advance phase (current_phase -> next, append to completed_phases)
jq '(.tasks[] | select(.id=="TASK_ID")).current_phase = "{vocabulary.reweave}" |
    (.tasks[] | select(.id=="TASK_ID")).completed_phases += ["{vocabulary.reflect}"]' \
    ops/queue/queue.json > tmp.json && mv tmp.json ops/queue/queue.json

The handoff block's "Queue Updates" section is not just output — it is your own todo list when running interactively.

Pipeline Chaining

After connection finding completes, output the next step based on ops/config.yaml pipeline.chaining mode:

• manual: Output "Next: {vocabulary.cmd_reweave} [note]" — user decides when to proceed
• suggested: Output next step AND advance task queue entry to current_phase: "{vocabulary.reweave}"
• automatic: Queue entry advanced and backward pass proceeds immediately

The chaining output uses domain-native command names from the derivation manifest.