reweave

name	reweave
description	Update old notes with new connections. The backward pass that /reflect doesn't do. Revisit existing notes that predate newer related content, add connections, sharpen claims, consider splits. Triggers on "/reweave", "/reweave [note]", "update old notes", "backward connections", "revisit notes".
user-invocable	true
allowed-tools	Read, Write, Edit, Grep, Glob, Bash, mcp__qmd__search, mcp__qmd__vector_search, mcp__qmd__deep_search, mcp__qmd__status
context	fork

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. ops/derivation-manifest.md — vocabulary mapping, platform hints

   • Use vocabulary.notes for the notes folder name
   • Use vocabulary.note / vocabulary.note_plural for note type references
   • Use vocabulary.reweave for the process verb in output
   • Use vocabulary.topic_map / vocabulary.topic_map_plural for MOC references
   • Use vocabulary.cmd_verify for the next-phase suggestion

2. ops/config.yaml — processing depth, pipeline chaining

   • processing.depth: deep | standard | quick
   • processing.chaining: manual | suggested | automatic
   • processing.reweave.scope: related | broad | full

If these files don't exist, use universal defaults.

Processing depth adaptation:

Depth	Reweave Behavior
deep	Full reconsideration. Search extensively for newer related {vocabulary.note_plural}. Consider splits, rewrites, challenges. Evaluate claim sharpening. Multiple search passes.
standard	Balanced review. Search semantic neighbors and same-{vocabulary.topic_map} {vocabulary.note_plural}. Add connections, sharpen if needed.
quick	Minimal backward pass. Add obvious connections only. No rewrites or splits.

Reweave scope:

Scope	Behavior
related	Search {vocabulary.note_plural} directly related to the target (same {vocabulary.topic_map}, semantic neighbors)
broad	Search across all {vocabulary.topic_map_plural} and semantic space for potential connections
full	Complete review including potential splits, rewrites, and claim challenges

EXECUTE NOW

Target: $ARGUMENTS

Parse immediately:

• If target contains [[note name]] or note name: reweave that specific {vocabulary.note}
• If target contains --handoff: output RALPH HANDOFF block at end
• If target is empty: find {vocabulary.note_plural} that most need reweaving (oldest, sparsest, most outdated)
• If target is "recent" or "--since Nd": reweave {vocabulary.note_plural} not touched in N days
• If target is "sparse": find {vocabulary.note_plural} with fewest connections

Execute these steps:

1. Read the target {vocabulary.note} fully — understand its current claim, connections, and age
2. Ask the reweave question: "If I wrote this {vocabulary.note} today, with everything I now know, what would be different?"
3. If a task file exists (pipeline execution): read it to see what /reflect discovered. The Reflect section shows which connections were just added and which {vocabulary.topic_map_plural} were updated — this is your starting context for the backward pass.
4. Search for newer related {vocabulary.note_plural} — use dual discovery (semantic search + {vocabulary.topic_map} browsing) to find {vocabulary.note_plural} created AFTER the target that should connect
5. Evaluate what needs changing:
   • Add connections to newer {vocabulary.note_plural} that did not exist when this was written
   • Sharpen the claim if understanding has evolved
   • Consider splitting if the {vocabulary.note} now covers what should be separate ideas
   • Challenge the claim if new evidence contradicts it
   • Rewrite prose if understanding is deeper now
6. Make the changes — edit the {vocabulary.note} with new connections (inline links with context), improved prose, sharper claim if needed
7. Update {vocabulary.topic_map_plural} — if the {vocabulary.note}'s topic membership changed, update relevant {vocabulary.topic_map_plural}
8. If task file exists: update the {vocabulary.reweave} section
9. Report — structured summary of what changed and why
10. If --handoff in target: output RALPH HANDOFF block

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

---

Reweave

Revisit old {vocabulary.note_plural} with everything you know today. {vocabulary.note_plural} are living documents — they grow, get rewritten, split apart, sharpen their claims. This is the backward pass that keeps the network alive.

Philosophy

{vocabulary.note_plural} are living documents, not finished artifacts.

A {vocabulary.note} written last month was written with last month's understanding. Since then:

• New {vocabulary.note_plural} exist that relate to it
• Understanding of the topic deepened
• The claim might need sharpening or challenging
• What was one idea might now be three
• Connections that were not obvious then are obvious now

Reweaving is not just "add backward links." It is completely reconsidering the {vocabulary.note} based on current knowledge. Ask: "If I wrote this {vocabulary.note} today, what would be different?"

"The {vocabulary.note} you wrote yesterday is a hypothesis. Today's knowledge is the test."

What Reweaving Can Do

Action	When to Do It
Add connections	Newer {vocabulary.note_plural} exist that should link here
Rewrite content	Understanding evolved, prose should reflect it
Sharpen the claim	Title is too vague to be useful
Split the {vocabulary.note}	Multiple claims bundled together
Challenge the claim	New evidence contradicts the original
Improve the description	Better framing emerged
Update examples	Better illustrations exist now

Reweaving is NOT just Phase 4 of /reflect applied backward. It is a full reconsideration.

Invocation Patterns

/reweave [[note]]

Fully reconsider a specific {vocabulary.note} against current knowledge.

/reweave (no argument)

Scan for candidates needing reweaving, present ranked list.

/reweave --sparse

Process {vocabulary.note_plural} flagged as sparse by /health.

/reweave --since Nd

Reweave all {vocabulary.note_plural} not updated in N days.

How to find candidates:

# Find notes not modified in 30 days
find {vocabulary.notes}/ -name "*.md" -mtime +30 -type f

/reweave --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 1: Understand the {vocabulary.note} as It Exists

Read the target {vocabulary.note} completely. Understand:

• What claim does it make?
• What reasoning supports the claim?
• What connections does it have?
• When was it written/last modified?
• What was the context when it was created?

Also read the task file if one exists (pipeline execution). The task file's Reflect section shows:

• What connections /reflect just added
• Which {vocabulary.topic_map_plural} were updated
• What synthesis opportunities were flagged
• What the discovery trace looked like

This context prevents redundant work — you know what /reflect already found, so you can focus on what it missed or what needs deeper reconsideration.

Phase 2: Gather Current Knowledge (Dual Discovery)

Use the same dual discovery pattern as /reflect — {vocabulary.topic_map} exploration AND semantic search in parallel.

Path 1: {vocabulary.topic_map} Exploration — curated navigation

From the {vocabulary.note}'s Topics footer, identify which {vocabulary.topic_map}(s) it belongs to:

• Read the relevant {vocabulary.topic_map}(s)
• What synthesis exists that might affect this {vocabulary.note}?
• What newer {vocabulary.note_plural} in Core Ideas should this {vocabulary.note} reference?
• What tensions involve this {vocabulary.note}?

Path 2: Semantic Search — find what {vocabulary.topic_map_plural} might miss

Three-tier fallback for semantic search:

Tier 1 — MCP tools (preferred): Use mcp__qmd__deep_search (hybrid search with expansion + reranking):

• query: "[{vocabulary.note}'s core concepts and mechanisms]"
• limit: 15

Tier 2 — bash qmd with lock serialization: If MCP tools fail or are unavailable:

LOCKDIR="ops/queue/.locks/qmd.lock"
while ! mkdir "$LOCKDIR" 2>/dev/null; do sleep 2; done
qmd query "[note's core concepts]" --collection {vocabulary.notes_collection} --limit 15 2>/dev/null
rm -rf "$LOCKDIR"

The lock prevents multiple parallel workers from loading large models simultaneously.

Tier 3 — grep only: If both MCP and bash fail, log "qmd unavailable, grep-only discovery" and rely on {vocabulary.topic_map} + keyword search only. This degrades quality but does not block work.

Evaluate results by relevance — read any result where title or snippet suggests genuine connection.

Also check:

• Backlinks — what {vocabulary.note_plural} already reference this one? Do they suggest the target should cite back?

grep -rl '\[\[target note title\]\]' {vocabulary.notes}/ --include="*.md"

Key question: What do I know today that I did not know when this {vocabulary.note} was written?

Phase 3: Evaluate the Claim

Does the original claim still hold?

Finding	Action
Claim holds, evidence strengthened	Add supporting connections
Claim holds but framing is weak	Rewrite for clarity
Claim is too vague	Sharpen to be more specific
Claim is too broad	Split into focused {vocabulary.note_plural}
Claim is partially wrong	Revise with nuance
Claim is contradicted	Flag tension, propose revision

The Sharpening Test:

Read the title. Ask: could someone disagree with this specific claim?

• If yes, the claim is sharp enough
• If no, it is too vague and needs sharpening

Example:

• Vague: "context matters" (who would disagree?)
• Sharp: "explicit context beats automatic memory" (arguable position)

The Split Test:

Does this {vocabulary.note} make multiple claims that could stand alone?

• If the {vocabulary.note} connects to 5+ topics across different domains, it probably needs splitting
• If you would want to link to part of it but not all, it is a split candidate

Phase 4: Evaluate Connections

Backward connections (what this {vocabulary.note} should reference):

For each newer {vocabulary.note}, ask:

• Does it extend this {vocabulary.note}'s argument?
• Does it provide evidence or examples?
• Does it share mechanisms?
• Does it create tension worth acknowledging?
• Would referencing it strengthen the reasoning?

Forward connections (what should reference this {vocabulary.note}):

Check newer {vocabulary.note_plural} that SHOULD link here but do not:

• Do they make arguments that rely on this claim?
• Would following this link provide useful context?

Agent Traversal Check (apply to all connections):

Ask: "If an agent follows this link during traversal, what decision or understanding does it enable?"

Connections exist to serve agent navigation. Adding a link because content is "related" without operational value creates noise. Every backward or forward connection should answer:

• Does this help an agent understand WHY something works?
• Does this help an agent decide HOW to implement something?
• Does this surface a tension the agent should consider?

Reject connections that are merely "interesting" without agent utility.

Articulation requirement:

Every new connection must articulate WHY:

• "extends this by adding the temporal dimension"
• "provides evidence that supports this claim"
• "contradicts this — needs resolution"

Never: "related" or "see also"

Phase 5: Apply Changes

For pipeline execution (--handoff mode): Apply changes directly. The pipeline needs to proceed without waiting for approval.

For interactive execution (no --handoff): Present the reweave proposal first, then apply after approval.

Reweave proposal format (interactive only):

## Reweave Proposal: [[target note]]

**Last modified:** YYYY-MM-DD
**Current knowledge evaluated:** N newer {vocabulary.note_plural}, M backlinks

### Claim Assessment

[Does the claim hold? Need sharpening? Splitting? Revision?]

### Proposed Changes

**1. [change type]: [description]**

Current:
> [existing text]

Proposed:
> [new text]

Rationale: [why this change]

**2. [change type]: [description]**
...

### Connections to Add

- [[newer note A]] — [relationship]: [specific reason]
- [[newer note B]] — [relationship]: [specific reason]

### Connections to Verify (other {vocabulary.note_plural} should link here)

- [[note X]] might benefit from referencing this because...

### Not Changing

- [What was considered but rejected, and why]

---

Apply these changes? (yes/no/modify)

When applying changes:

1. Make changes atomically
2. Preserve existing valid content
3. Maintain prose flow — new links should read naturally inline
4. Verify all link targets exist
5. Update description if claim changed

---

The Five Reweave Actions

1. Add Connections

The simplest action. Newer {vocabulary.note_plural} exist that should be referenced.

Inline connections (preferred):

# before
The constraint shifts from capture to curation.

# after
The constraint shifts from capture to curation, and since [[throughput matters more than accumulation]], the question becomes who does the selecting.

Footer connections:

relevant_notes:
  - "[[newer note]] — extends this by adding temporal dimension"

2. Rewrite Content

Understanding evolved. The prose should reflect current thinking, not historical thinking.

When to rewrite:

• Reasoning is clearer now
• Better examples exist
• Phrasing was awkward
• Important nuance was missing

How to rewrite:

• Preserve the core claim (unless challenging it)
• Improve the path to the conclusion
• Incorporate new connections as prose
• Maintain the {vocabulary.note}'s voice

3. Sharpen the Claim

Vague claims cannot be built on. Sharpen means making the claim more specific and arguable.

Sharpening patterns:

Vague	Sharp
"X is important"	"X matters because Y, which enables Z"
"consider doing X"	"X works when [condition] because [mechanism]"
"there are tradeoffs"	"[specific tradeoff]: gaining X costs Y"

When sharpening, also update:

• Title (if claim changed) — use the rename script if available
• Description (must match new claim)
• Body (reasoning must support sharpened claim)

4. Split the {vocabulary.note}

One {vocabulary.note} became multiple ideas over time. Splitting creates focused, composable pieces.

Split indicators:

• Connects to 5+ topics across different domains
• Makes multiple distinct claims
• You would want to link to part but not all
• Different sections could be referenced independently

Split process:

1. Identify the distinct claims
2. Create new {vocabulary.note_plural} for each claim
3. Each new {vocabulary.note} gets:
   • Focused title (the claim)
   • Own description
   • Relevant subset of content
   • Appropriate connections
4. Original {vocabulary.note} either:
   • Becomes a synthesis linking to the splits
   • Gets archived if splits fully replace it
   • Retains one claim and links to others

Example split:

Original: "knowledge systems need both structure and flexibility"

Splits:

• [[structure enables retrieval at scale]]
• [[flexibility allows organic growth]]
• [[structure and flexibility create tension]] (links to both)

When NOT to split:

• {vocabulary.note} is genuinely about one thing that touches many areas
• Connections are all variations of the same relationship
• Splitting would create {vocabulary.note_plural} too thin to stand alone

5. Challenge the Claim

New evidence contradicts the original. Do not silently "fix" — acknowledge the evolution.

Challenge patterns:

# if partially wrong
The original insight was [X]. However, [[newer evidence]] suggests [Y]. The refined claim is [Z].

# if tension exists
This argues [X]. But [[contradicting note]] argues [Y]. The tension remains unresolved — possibly [X] applies in context A while [Y] applies in context B.

# if significantly wrong
This note originally claimed [X]. Based on [[evidence]], the claim is revised: [new claim].

Always log challenges: When a claim is challenged or revised, this is a significant event. Note it in the task file Reweave section with the original claim, the new evidence, and the revised position.

---

Enrichment-Triggered Actions

When processing a {vocabulary.note} that came through the enrichment pipeline, check the task file for post_enrich_action signals. These were surfaced by /enrich and need execution:

title-sharpen

The enrich phase determined the {vocabulary.note}'s title is too vague after content integration.

1. Read post_enrich_detail for the recommended new title
2. Evaluate: is the suggested title actually better? (sharper claim, more specific, still composable as prose)
3. If yes and a rename script exists: use it to rename. Otherwise rename manually and update all wiki links.
4. Update the {vocabulary.note}'s description to match the new title
5. Log the rename in the task file Reweave section

split-recommended

The enrich phase determined the {vocabulary.note} now covers multiple distinct claims.

1. Read post_enrich_detail for the split recommendation
2. Evaluate: does splitting genuinely improve the vault? (each piece must stand alone)
3. If yes:
   • Create new {vocabulary.note} files for each split claim
   • Move relevant content from original to splits
   • Update original to either link to splits or retain one claim
   • Create queue entries for the new {vocabulary.note_plural} starting at the connect phase
4. Log the split in the task file Reweave section

merge-candidate

The enrich phase determined this {vocabulary.note} substantially overlaps with another.

Do NOT auto-merge or auto-delete. This requires human judgment.

1. Log the merge recommendation in the task file Reweave section
2. Note which {vocabulary.note_plural} overlap and why
3. The final report surfaces this for human review

---

Quality Gates

Gate 1: Articulation Test

Every change must be articulable. "I am adding this because..." with a specific reason.

Gate 2: Improvement Test

After changes, is the {vocabulary.note} better? More useful? More connected? More accurate?

If you cannot confidently say yes, do not make the change.

Gate 3: Coherence Test

After changes, does the {vocabulary.note} still cohere as a single focused piece? Or did you accidentally make it broader?

Gate 4: Network Test

Do the changes improve the network? More traversal paths? Better paths?

Gate 5: When NOT to Change

• The {vocabulary.note} is accurate, well-connected, and recent — leave it alone
• The "improvement" would just be cosmetic rewording — do not churn
• The {vocabulary.note} is a historical record — these evolve through status changes, not rewrites

---

Output Format

## Reweave Complete: [[target note]]

### Changes Applied

| Type | Description |
|------|-------------|
| connection | added [[note A]] inline, [[note B]] to footer |
| rewrite | clarified reasoning in paragraph 2 |
| sharpen | title unchanged, description updated |

### Claim Status

[unchanged | sharpened | split | challenged]

### Network Effect

- Outgoing links: 3 -> 5
- This {vocabulary.note} now bridges [[domain A]] and [[domain B]]

### Cascade Recommendations

- [[related note]] might benefit from reweave (similar vintage)
- {vocabulary.topic_map} [[topic]] should be updated to reflect changes

### Observations

[Patterns noticed, insights for future]

---

What Success Looks Like

Successful reweaving:

• {vocabulary.note} reflects current understanding, not historical understanding
• Claim is sharp enough to disagree with
• Connections exist to relevant newer content
• {vocabulary.note} participates actively in the network
• Someone reading it today gets the best version

The test: if this {vocabulary.note} were written today with everything you know, would it be meaningfully different? If yes and you did not change it, reweaving failed.

---

Critical Constraints

Never:

• Silently change claims without acknowledging evolution
• Split {vocabulary.note_plural} into pieces too thin to stand alone
• Add connections without articulating why
• Rewrite voice/style (preserve the {vocabulary.note}'s character)
• Make changes without approval in interactive mode
• Create wiki links to non-existent files

Always:

• Present proposals before editing (interactive mode)
• Explain rationale for each change
• Preserve what is still valid
• Log significant claim changes
• Verify link targets exist

---

The Network Lives Through Evolution

{vocabulary.note_plural} written yesterday do not know about today. {vocabulary.note_plural} written with old understanding do not reflect new understanding. Without reweaving, the vault becomes a graveyard of outdated thinking that happens to be organized.

Reweaving is how knowledge stays alive. Not just connecting, but questioning, sharpening, splitting, rewriting. Every {vocabulary.note} is a hypothesis. Every reweave is a test.

The network compounds through evolution, not just accumulation.

---

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.reweave} ===
Target: [[note name]]

Work Done:
- Older {vocabulary.note_plural} updated: N
- Claim status: unchanged | sharpened | challenged | split
- Network effect: M new traversal paths

Files Modified:
- {vocabulary.notes}/[older note 1].md (inline link added)
- {vocabulary.notes}/[older note 2].md (footer connection added)
- [task file path] ({vocabulary.reweave} section)

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

Queue Updates:
- Advance phase: {vocabulary.reweave} -> {vocabulary.verify}
=== 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.reweave} section of that task file with:

• Older {vocabulary.note_plural} updated and why
• Claim status (unchanged/sharpened/challenged/split)
• Network effect summary

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

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)
# NEXT_PHASE is the phase after reweave in phase_order (i.e., verify)
jq '(.tasks[] | select(.id=="TASK_ID")).current_phase = "{vocabulary.verify}" |
    (.tasks[] | select(.id=="TASK_ID")).completed_phases += ["{vocabulary.reweave}"]' \
    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 reweaving completes, output the next step based on ops/config.yaml pipeline.chaining mode:

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

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