arscontexta 0.6.0

package/methodology/backward maintenance asks what would be different if written today.md

@@ -0,0 +1,62 @@
+---
+description: This mental model distinguishes reweave from reflect — maintenance becomes genuine reconsideration rather than mechanical link-adding
+kind: research
+topics: ["[[maintenance-patterns]]"]
+methodology: ["Zettelkasten"]
+---
+
+# reweaving asks what would be different if written today
+
+The question "what connections should I add?" leads to a different activity than "if I wrote this note today, what would be different?" The first is mechanical: scan for links, add them. The second is intellectual: reconsider the entire note against current understanding. The question is only meaningful because [[digital mutability enables note evolution that physical permanence forbids]] — Luhmann couldn't implement "what would be different" because his paper cards resisted editing. We can ask the question AND act on the answer. Understanding (reassessing against current knowledge) must precede building (updating the note). Because [[the generation effect requires active transformation not just storage]], the difference is not just stylistic. Mechanical link-adding produces no new understanding — it's rearrangement. Genuine reweaving produces something that didn't exist: a reframed argument, a sharpened claim, a newly articulated connection.
+
+This matters because notes written last month were written with last month's understanding. Since then, new notes exist, understanding has deepened, and what seemed like one idea might now be three. A note about "knowledge graphs" written before understanding spreading activation models is incomplete in ways that link-adding won't fix. The prose itself needs rewriting. The deeper reason this matters is that since [[coherence maintains consistency despite inconsistent inputs]], an unreviewed note may now contradict newer understanding without anyone noticing — the temporal inconsistency that accumulates between sessions is precisely what backward maintenance exists to detect and resolve.
+
+The reframe changes what actions become available. Adding connections is one option, but so is rewriting content when understanding evolved, sharpening the claim when [[claims must be specific enough to be wrong]] reveals the title is too vague, splitting the note when multiple claims got bundled together, or even challenging the claim when new evidence contradicts the original. Since [[backlinks implicitly define notes by revealing usage context]], one input to this reconsideration is checking what roles the note currently plays — its backlinks reveal which arguments elsewhere depend on this note, providing constraints on how aggressively the claim can be revised without disrupting the graph. Because [[summary coherence tests composability before filing]], catching bundling at creation time is cheaper than detecting it during maintenance passes — the summary requirement is an upfront quality gate that reduces later reweave burden. If [[maturity field enables agent context prioritization]], maturity status becomes a reweaving input: seedlings explicitly signal "this note needs development work," making them obvious candidates for the reconsideration pass.
+
+Without this mental model, vault maintenance becomes a mechanical pass that leaves outdated thinking intact but organized. And since [[wiki links as social contract transforms agents into stewards of incomplete references]], maintenance carries an additional dimension beyond quality: it is the mechanism through which link commitments get fulfilled, reframing the backward pass from cleanup to stewardship. Since [[throughput matters more than accumulation]], what matters is the quality of what flows through the system, not the size of the organized archive. Reweaving ensures that existing content remains part of the living flow rather than becoming a graveyard of historical understanding.
+
+The backward pass complements the forward pass: connection-finding links new notes to old ones, backward maintenance updates old notes based on new ones. This mental model is precisely why [[skills encode methodology so manual execution bypasses quality gates]] — without the "what would be different" frame encoded in the workflow, maintenance degrades to mechanical link-adding that preserves the form while missing the substance. This is [[verbatim risk applies to agents too]] manifesting in the maintenance phase: an agent could add links that look like connections while never engaging the deeper question of what would be different today.
+
+The per-note reconsideration has a system-level counterpart in reconciliation. Since [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]], the reconciliation loop formalizes the "what would be different" question at the structural level: it declares desired state (all links resolve, all notes in MOCs, schema compliance) and periodically checks whether actual state has drifted. Where backward maintenance asks "what would this note look like if written today?", reconciliation asks "does the system still match what we said healthy looks like?" Both are drift-correction mechanisms, but they operate at different scales and use different detection methods — backward maintenance requires judgment (reading and reconsidering), while reconciliation detection is deterministic (counting, comparing, checking). And since [[three concurrent maintenance loops operate at different timescales to catch different classes of problems]], backward maintenance maps specifically onto the slow loop: the high-judgment reconsideration that only makes sense at weekly or monthly timescales, because description staleness and claim drift develop over the course of understanding evolution, not session-to-session. The medium loop's detection (orphan checks, link density) surfaces candidates for the slow loop's reconsideration, making the two loops cooperate: mechanical detection at one timescale feeds judgment-requiring remediation at another.
+
+Backward maintenance is also an attention allocation decision in disguise. Since [[AI shifts knowledge systems from externalizing memory to externalizing attention]], the question "what would be different if written today?" is fundamentally about directing finite attention — which older notes deserve renewed focus given current understanding. The system externalizes this attention decision through maintenance targeting and scheduling rather than relying on the operator to notice what has become stale. The same question scales up to system architecture: since [[evolution observations provide actionable signals for system adaptation]], the diagnostic protocol asks "what would be different" not about individual notes but about the structural decisions themselves -- which note types would you still define, which fields would you still require, how would you organize navigation? The per-note reconsideration and the per-system diagnostic operate at different scales but share the same mental model: current understanding tests historical decisions.
+
+Whether this holistic reconsideration is the optimal approach remains testable. Since [[gardening cycle implements tend prune fertilize operations]] proposes separating maintenance into three focused phases (tend/prune/fertilize), the question becomes: does the "what would be different today" frame that considers everything at once outperform focused operations that each start fresh? The gardening experiment tests whether cognitive focus per operation beats holistic reconsideration. A separate question is WHEN the reconsideration should happen — since [[spaced repetition scheduling could optimize vault maintenance]] tests whether newly created notes need more frequent attention than mature notes, the timing of reweave may matter as much as the method. Backward maintenance also sits squarely on the curation side of a deeper governance dilemma: since [[organic emergence versus active curation creates a fundamental vault governance tension]], every reweave is an active curation intervention that shapes the graph according to current understanding. The governance rhythm determines when curation interventions like reweaving are appropriate — too frequent and they suppress the organic patterns that organic growth would produce, too infrequent and the structural debt from outdated thinking compounds past the point of easy correction.
+
+But there is a deeper question about WHO does the reconsideration. When agents run backward maintenance, they do the intellectual work of asking "what would be different." The human approves the proposals. Since [[cognitive outsourcing risk in agent-operated systems]] tests whether delegating all processing atrophies human meta-cognitive skills, backward maintenance may be particularly susceptible: the human never practices the act of holistic reconsideration, they only evaluate someone else's reconsideration. If the gardening experiment validates focused operations, smaller-scope human approvals might preserve more genuine judgment than approving one holistic proposal.
+
+The same "what would be different" question operates at a higher scale too. Since [[derived systems follow a seed-evolve-reseed lifecycle]], reseeding asks this question not about individual notes but about the entire system architecture: what would this configuration look like given what we now know about how it gets used? Backward maintenance at the note level (reweaving) and backward maintenance at the system level (reseeding) share the mental model but differ in scope and intervention type. Reweaving can sharpen a claim, add connections, split a note. Reseeding restructures templates, pipelines, and MOC hierarchy. The scale difference matters because systemic incoherence — schemas that have drifted, navigation that no longer matches content — cannot be fixed by improving individual notes, no matter how thorough the reweave.
+
+There is also a cross-deployment dimension. Since [[the derivation engine improves recursively as deployed systems generate observations]], the backward maintenance performed within each individual system generates the operational observations that improve derivation for all future systems. When a reweave sharpens a claim or surfaces a tension, that observation enriches the shared claim graph — making backward maintenance not just a local quality practice but a data-generation mechanism for the derivation engine's recursive improvement. The individual system benefits from better notes; the meta-system benefits from better claims.
+
+The question of WHERE activation should spread during reweave has a concrete answer. Since [[maintenance targeting should prioritize mechanism and theory notes]], productive targets are notes about the MECHANISM being reconsidered, not just notes in the same MOC. For experiments testing theories, the theory notes themselves are the high-value reweave targets because they provide the grounding the experiment tests against.
+---
+
+Relevant Notes:
+- [[digital mutability enables note evolution that physical permanence forbids]] — foundational enabler: this mental model only works because the medium permits revision; Luhmann's cards couldn't be reconsidered, only cross-referenced
+- [[backlinks implicitly define notes by revealing usage context]] — provides an answer to what would be different: check what roles the note currently plays across the graph (its backlinks) before changing what it claims
+- [[maintenance targeting should prioritize mechanism and theory notes]] — refines this mental model with concrete targeting heuristics: mechanism connection predicts higher reweave value than topic proximity
+- [[throughput matters more than accumulation]] — reweaving maintains quality in the flow rather than preserving organized but outdated content
+- [[skills encode methodology so manual execution bypasses quality gates]] — the what would be different mental model is the quality gate that prevents mechanical link-adding
+- [[wiki links implement GraphRAG without the infrastructure]] — explains the stakes: graph quality degrades when links aren't actively maintained
+- [[the generation effect requires active transformation not just storage]] — explains WHY mechanical link-adding fails: generation creates cognitive hooks, rearrangement doesn't
+- [[maturity field enables agent context prioritization]] — if validated, maturity status would flag seedlings as reweaving candidates, making development opportunities explicit
+- [[random note resurfacing prevents write-only memory]] — tests the selection method: which notes get chosen for the reconsideration pass that this note describes
+- [[gardening cycle implements tend prune fertilize operations]] — tests whether separating maintenance into three focused phases outperforms this holistic reconsideration approach
+- [[spaced repetition scheduling could optimize vault maintenance]] — tests WHEN reconsideration should happen; reweaving defines what maintenance accomplishes, scheduling optimizes when that happens
+- [[cognitive outsourcing risk in agent-operated systems]] — tests whether delegating reconsideration to agents atrophies the human's ability to do holistic reconsideration themselves
+- [[vault conventions may impose hidden rigidity on thinking]] — if conventions constrain at creation time, reweaving provides an escape hatch: notes can evolve past their initial form
+- [[verbatim risk applies to agents too]] — tests whether agents can produce maintenance passes that look like reweaving (adding links) while skipping genuine reconsideration; mechanical link-adding is verbatim risk in the backward pass
+- [[AI shifts knowledge systems from externalizing memory to externalizing attention]] — paradigm frame: backward maintenance is an attention allocation decision — which older notes deserve renewed focus given current understanding; the system externalizes this attention direction rather than relying on the operator to notice staleness
+- [[wiki links as social contract transforms agents into stewards of incomplete references]] — adds a motivational reframe: maintenance is not just holistic reconsideration of outdated thinking but stewardship of commitments; every dangling link is a promise that backward maintenance helps fulfill, shifting the frame from cleanup to obligation
+- [[evolution observations provide actionable signals for system adaptation]] — the system-level counterpart: this note asks what would be different at the note level, the diagnostic protocol asks what would be different at the system-architecture level, monitoring whether structural decisions (types, fields, MOCs, processing) still match operational reality
+- [[derived systems follow a seed-evolve-reseed lifecycle]] — scale extension: the same mental model at system level becomes reseeding, which asks what the entire architecture would look like given operational experience; note-level reweaving and system-level reseeding share the question but differ in scope and intervention type
+- [[organic emergence versus active curation creates a fundamental vault governance tension]] — governance frame: backward maintenance is the primary mechanism of the curation pole, and the governance rhythm determines when reweaving interventions are appropriate; too frequent curation suppresses organic growth, too infrequent lets structural debt compound
+- [[the derivation engine improves recursively as deployed systems generate observations]] — cross-deployment extension: backward maintenance within each system generates operational observations that enrich the shared claim graph, making note-level reweaving a data-generation mechanism for the derivation engine's meta-level improvement
+- [[reconciliation loops that compare desired state to actual state enable drift correction without continuous monitoring]] — system-level counterpart: backward maintenance asks what would be different per-note through judgment, reconciliation asks whether structural health has drifted through deterministic comparison; both are drift-correction mechanisms at different scales
+- [[three concurrent maintenance loops operate at different timescales to catch different classes of problems]] — scheduling container: backward maintenance is the slow loop's remediation operation requiring high judgment, while medium-loop detection (orphan checks, link density) surfaces the candidates that the slow loop reconsiders
+- [[friction reveals architecture]] — the trigger signal: friction in use is what surfaces which notes need the reconsideration pass; agents especially benefit because they cannot push through friction with intuition, forcing the articulation that backward maintenance requires
+- [[coherence maintains consistency despite inconsistent inputs]] — the belief-level goal: backward maintenance serves coherence by detecting and resolving contradictions that accumulate as understanding evolves; the reconsideration question is ultimately asking whether the note still coheres with the current belief system
+
+Topics:
+- [[maintenance-patterns]]

package/methodology/balance onboarding enforcement and questions to prevent premature complexity.md

@@ -0,0 +1,229 @@
+---
+description: What to enforce, what to explain, and what to ask during /setup — the decision framework for vault generation that prevents premature complexity while ensuring a healthy starting point
+kind: guidance
+status: active
+topics: ["[[derivation-engine]]"]
+---
+
+# balance onboarding enforcement and questions to prevent premature complexity
+
+/setup is the most consequential moment in a vault's life. The choices made here determine whether the system compounds value or gets abandoned within a week. Since [[premature complexity is the most common derivation failure mode]], the primary risk is generating too much structure too soon.
+
+This doc tells the plugin WHAT to decide during /setup, and more importantly, what NOT to decide.
+
+## The Three Categories
+
+Every onboarding decision falls into one of three categories:
+
+### 1. Enforce (Non-Negotiable)
+
+These are always present, never optional. The user doesn't choose them because without them the system doesn't function.
+
+| Feature | Why Non-Negotiable | Implementation |
+|---------|-------------------|----------------|
+| Markdown files with YAML frontmatter | Since [[markdown plus YAML plus ripgrep implements a queryable graph database without infrastructure]], this is the storage layer | Generated automatically |
+| `description` field on every note | Since [[descriptions are retrieval filters not summaries]], agents need descriptions for discovery | Required in all templates |
+| Wiki links as connection mechanism | Links are the graph edges that make traversal possible | Enabled by default |
+| `topics` field linking to at least one MOC | Orphan prevention — notes must be navigable | Required in templates |
+| Capture zone (inbox equivalent) | Content needs a place to land without ceremony | Generated folder |
+| At least one MOC | Navigation needs a starting point | Hub MOC generated |
+| Context file (CLAUDE.md equivalent) | Agent needs orientation per session | Generated with domain config |
+| Git commits on significant changes | Version history enables rollback and tracks evolution | Configured per platform |
+| Session logging | Operational observability — since [[maintenance operations are more universal than creative pipelines because structural health is domain-invariant]] | Logging structure generated |
+| Timestamps on entries | Temporal ordering is required for pattern detection and freshness checks | Required in templates |
+
+These are the kernel primitives. Since [[ten universal primitives form the kernel of every viable agent knowledge system]], they form the invariant base that derivation never varies.
+
+### 2. Explain (Defaults with Rationale)
+
+These have sensible defaults but the user should understand why. The plugin sets the default and explains it, giving the user the option to change.
+
+| Decision | Default | Rationale | When to Change |
+|----------|---------|-----------|----------------|
+| Processing intensity | Medium | Balances thoroughness with overhead | Heavy for research/therapy; Light for tracking domains |
+| MOC hierarchy pattern | Based on domain | Three-tier for research, flat-peer for personal | User preference for flatter/deeper |
+| Schema strictness | Soft enforcement | Since [[schema enforcement via validation agents enables soft consistency]], start soft | Hard enforcement only if user requests it |
+| Review cadence triggers | Condition-based | Since [[maintenance scheduling frequency should match consequence speed not detection capability]] | Time-based if user prefers regular rhythm |
+| Note granularity | Atomic (claim-level) | Since [[note titles should function as APIs enabling sentence transclusion]], atomic enables composability | Compound for domains with narrative content |
+| Linking style | Inline preferred | Since [[inline links carry richer relationship data than metadata fields]] | Footer-only for less writing-intensive domains |
+
+The key principle: **explain WHY the default is set, then let the user override.** Don't ask "Do you want atomic or compound notes?" — say "Your notes will be atomic (one idea per note) because this enables remixing ideas across contexts. If you prefer longer, more narrative entries, I can adjust this."
+
+### 3. Ask (Genuinely Variable)
+
+These have no sensible default — the plugin must ask because the answer depends on the user's specific situation.
+
+| Question | Why Ask | What It Determines |
+|----------|---------|-------------------|
+| What domain(s) do you work in? | Selects domain composition(s) | Entire vault architecture |
+| What's your primary goal? | Distinguishes storage from thinking | Processing pipeline depth |
+| What do you already have? | Import vs fresh start | Migration strategy |
+| What platform are you on? | Since [[platform capability tiers determine which knowledge system features can be implemented]] | Feature ceiling |
+| How much time will you spend with this? | Daily vs weekly vs sporadic | Maintenance trigger frequency |
+
+**Ask as few questions as possible.** Since [[configuration paralysis emerges when derivation surfaces too many decisions]], the plugin should derive most configuration from the domain selection + primary goal, asking only what it genuinely cannot infer.
+
+## The Onboarding Flow
+
+### Step 1: Domain Discovery (Ask)
+"What kind of knowledge work do you do?" Listen for domain signals. Map to closest domain composition(s). If multi-domain, identify primary.
+
+### Step 2: Goal Clarification (Ask)
+"Are you building a system to store and retrieve information, or to develop and connect ideas?" This determines since [[storage versus thinking distinction determines which tool patterns apply]] the fundamental system type.
+
+### Step 3: Configuration Derivation (Explain)
+Based on domain + goal, derive the 8 configuration dimensions. Show the user what was chosen and why:
+
+"Based on your research workflow, I'm setting up:
+- Atomic notes (one claim per note, so you can remix ideas)
+- Three-tier MOC hierarchy (hub → domain → topic, for layered navigation)
+- Heavy processing (each source gets claim extraction, connection finding, and verification)
+- Condition-based maintenance (health checks run when conditions trigger, not on a schedule)
+
+These are defaults — tell me if any feel wrong for how you work."
+
+### Step 4: Vault Generation (Enforce)
+Generate the vault with kernel primitives + domain-specific layers:
+- Folder structure
+- Note templates with domain-native schemas
+- MOC hierarchy (initial MOCs with placeholder structure)
+- Context file with orientation protocol
+- Processing pipeline configuration
+- Maintenance trigger definitions
+
+### Step 5: First Capture (Immediate Use)
+Don't end /setup with "your system is ready." End with capturing something:
+"Let's add your first note. What are you working on right now?"
+
+Immediate use prevents the "I set it up but never used it" failure mode. Since [[friction-driven module adoption prevents configuration debt by adding complexity only at pain points]], the user should experience the system working before adding more features.
+
+## What NOT to Ask
+
+| Common Question | Why Skip It | What to Do Instead |
+|----------------|------------|---------------------|
+| "How many MOC levels?" | Users can't predict this | Start with 1-2 levels, grow organically |
+| "What schema fields do you want?" | Users don't know yet | Start with domain defaults, evolve per [[schema evolution follows observe-then-formalize not design-then-enforce]] |
+| "How should notes connect?" | Abstract question with no good answer | Show connection types through example |
+| "What maintenance schedule?" | Since [[maintenance scheduling frequency should match consequence speed not detection capability]] | Set condition-based defaults |
+| "What processing model?" | Meaningless to non-technical users | Derive from domain + goal |
+
+## Preset-Based Simplification
+
+Since [[use-case presets dissolve the tension between composability and simplicity]], the plugin offers presets as the primary onboarding path:
+
+| Preset | Optimized For | Configuration |
+|--------|--------------|---------------|
+| **Research** | Academic research, literature review, thesis work | Heavy processing, three-tier MOCs, atomic notes, citation tracking |
+| **Personal Assistant** | Life areas, goals, habits, reviews | Medium processing, flat-peer MOCs, mixed granularity, area health tracking |
+| **Experimental** | Novel/specialized domains | Medium processing, configurable MOCs, derive from closest reference |
+
+Users select a preset, optionally customize, and get a working vault. Advanced configuration is available but not required.
+
+## Multi-Domain Onboarding
+
+When users need multiple domains (e.g., "I do research AND track personal goals"), the plugin:
+
+1. Identifies the primary domain (most time investment)
+2. Adds secondary domains as layers (see [[multi-domain-composition]])
+3. Generates shared infrastructure (inbox, context file, maintenance) once
+4. Adds domain-specific note types and MOCs per domain
+5. Explains how domains interact: "Your research claims and personal goals share the same graph. A research finding might connect to a personal goal."
+
+Since [[multi-domain systems compose through separate templates and shared graph]], domains add note types and MOCs without conflicting.
+
+## Domain-Specific Onboarding Patterns
+
+Different domains need different onboarding emphasis. The plugin adjusts what it highlights during /setup based on the detected domain:
+
+| Domain | Onboarding Emphasis | What to Frontload | What to Defer |
+|--------|--------------------|--------------------|---------------|
+| Research | Claim extraction pipeline, source management | MOC hierarchy, citation schema | Review cadence, synthesis scheduling |
+| Therapy | Ethical constraints, privacy setup, warmth calibration | Mood tracking schema, pattern detection | Strategy effectiveness tracking |
+| PM | Decision tracking, stakeholder mapping | Meeting extraction templates, action items | Estimation analysis, retrospective synthesis |
+| Creative Writing | Consistency graph, canon management | Character/location/world-rule templates | Plot thread tracking, voice drift detection |
+| Personal Life | Area structure, review rhythm | Life area MOCs, capture workflow | Goal cascading, habit tracking |
+| Trading | Risk management, journal discipline | Trade journal template, thesis tracking | Correlation analysis, strategy backtesting |
+| Health | Tracking schema, correlation setup | Measurement templates, baseline capture | Protocol effectiveness, trend analysis |
+| Learning | Knowledge mapping, prerequisite tracking | Course/concept templates, mastery levels | Spaced repetition, cross-course synthesis |
+
+**The principle:** each domain has a "day one essential" and a "month two extension." /setup delivers the essential. The extension waits for friction to signal need.
+
+### Domain-Specific First Captures
+
+The first capture should demonstrate the domain's core value proposition:
+
+- **Research:** "What paper are you reading right now? Let's extract its claims."
+- **Therapy:** "What's on your mind right now? Let's capture a reflection."
+- **PM:** "What decision did your team make recently? Let's document it with rationale."
+- **Creative:** "Tell me about your main character. Let's build their canonical entry."
+- **Personal:** "What are your life areas? Let's set up the structure."
+
+The first capture proves the system works before the user can lose momentum.
+
+## Progressive Disclosure During Onboarding
+
+/setup should reveal the system's capabilities in layers, not all at once. Since [[configuration paralysis emerges when derivation surfaces too many decisions]], the plugin progressively discloses features:
+
+**Layer 1 (During /setup):** Core capture + basic navigation. The user can write notes and find them.
+
+**Layer 2 (First week):** Processing pipeline activation. The user sees the system extract value from their raw captures. "I noticed you've captured 5 entries. Here are 3 patterns I detected."
+
+**Layer 3 (First month):** Maintenance and evolution. The user encounters natural friction points and the plugin suggests solutions. "Your inbox has 12 unprocessed items. Would you like me to activate automatic processing?"
+
+**Layer 4 (Ongoing):** System-level optimization. The plugin recommends structural changes based on accumulated operational evidence. "Your research MOC has 45 notes — splitting into sub-MOCs would improve navigation."
+
+This progressive disclosure maps to the seed-evolve-reseed lifecycle: Layer 1 is the seed, Layers 2-3 are evolution, and Layer 4 enables principled restructuring when needed.
+
+## Post-Init Evolution
+
+/setup is a starting point, not a final configuration. The plugin should:
+
+1. **Track friction** — When the user struggles with a workflow, log an observation
+2. **Suggest modules** — When a pain point matches an available module, suggest activation
+3. **Evolve schemas** — When users consistently add fields manually, propose schema updates
+4. **Grow MOCs** — When topics accumulate notes, suggest MOC creation
+
+Since [[derived systems follow a seed-evolve-reseed lifecycle]], the initial vault is the seed. Evolution happens through use. Reseeding happens when accumulated friction justifies restructuring.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Better Approach |
+|-------------|-------------|-----------------|
+| Ask everything upfront | Configuration paralysis, decision fatigue | Ask 3-5 questions, derive the rest |
+| Generate maximum features | Premature complexity, maintenance burden | Start minimal, grow with pain points |
+| No explanation of defaults | User doesn't understand their system | Explain key decisions briefly |
+| Skip first capture | Setup without use → abandonment | End /setup with actual content |
+| Require platform expertise | Users shouldn't need to understand hooks/skills | Abstract platform details behind presets |
+| Same onboarding for all domains | Different domains have different day-one essentials | Domain-specific first captures |
+| Showing all capabilities at once | Overwhelm before the system proves value | Progressive disclosure across layers |
+
+## Domain Examples
+
+These domain compositions demonstrate onboarding patterns in practice:
+
+- [[academic research uses structured extraction with cross-source synthesis]] — Research preset with heavy processing, three-tier MOCs, atomic notes; shows the full enforce/explain/ask flow for an academic researcher
+- [[personal assistant uses life area management with review automation]] — Personal assistant preset with medium processing, flat-peer MOCs, mixed granularity; demonstrates how "What life areas matter to you?" maps to area MOC generation
+- [[therapy journal uses warm personality with pattern detection for emotional processing]] — Shows how the plugin explains processing intensity: "Your journal entries will be analyzed for patterns across mood, triggers, and coping strategies" (explain, not ask)
+- [[student learning uses prerequisite graphs with spaced retrieval]] — Experimental preset adapted for learning; demonstrates deriving prerequisite graph structure from the user's course description rather than asking about graph topology
+- [[trading uses conviction tracking with thesis-outcome correlation]] — Shows multi-domain onboarding: user describes "I trade and track my health to see correlations" → primary (trading) + secondary (health) composition
+
+## Grounding
+
+This guidance is grounded in:
+- [[premature complexity is the most common derivation failure mode]] — start simple
+- [[friction-driven module adoption prevents configuration debt by adding complexity only at pain points]] — grow with need
+- [[configuration paralysis emerges when derivation surfaces too many decisions]] — minimize questions
+- [[use-case presets dissolve the tension between composability and simplicity]] — presets as simplification
+- [[derived systems follow a seed-evolve-reseed lifecycle]] — /setup is seed, not final state
+- [[schema evolution follows observe-then-formalize not design-then-enforce]] — schemas grow from use
+- [[progressive schema validates only what active modules require not the full system schema]] — schema tracks feature activation
+
+---
+
+Topics:
+- [[index]]
+- [[index]]
+---
+
+Topics:
+- [[derivation-engine]]

package/methodology/basic level categorization determines optimal MOC granularity.md

@@ -0,0 +1,51 @@
+---
+description: Rosch's prototype theory predicts MOC titles work best at the "chair" level — specific enough to be informative, general enough to cover a cluster — and this level shifts as expertise deepens
+kind: research
+topics: ["[[graph-structure]]"]
+methodology: ["Cognitive Science", "PKM Research"]
+source: [[tft-research-part3]]
+---
+
+# basic level categorization determines optimal MOC granularity
+
+Eleanor Rosch's prototype theory, developed through experiments in the 1970s, established that humans naturally categorize at a "basic level" that maximizes informativeness with minimum cognitive effort. The basic level sits between superordinate categories (too abstract to be useful) and subordinate categories (too specific to be general). "Chair" is basic level. "Furniture" is superordinate — it tells you almost nothing about what you're dealing with. "Kitchen chair" is subordinate — it adds detail that rarely matters for navigation.
+
+This maps directly to MOC design. A MOC titled "tools" sits at the superordinate level: it covers everything and orients toward nothing. An agent loading a "tools" MOC gets a list so broad that the attention management benefit collapses — since [[MOCs are attention management devices not just organizational tools]], a superordinate MOC fails the orientation function because it presents too much unrelated content, forcing the agent to re-filter within the MOC itself. The attention tax that MOCs are supposed to eliminate gets relocated rather than reduced.
+
+At the other extreme, a MOC titled "obsidian git plugin" sits at the subordinate level. It covers so little that the overhead of maintaining a separate MOC exceeds the navigation benefit. The agent must traverse multiple subordinate MOCs to build any picture of the domain, which creates exactly the kind of fragmented orientation that since [[navigational vertigo emerges in pure association systems without local hierarchy]] identifies as the core failure mode of under-structured systems. Too many tiny MOCs produce the same disorientation as no MOCs at all — landmarks only help when they're sparse enough to provide bearing.
+
+The basic level is where MOC titles should sit: specific enough that loading the MOC tells you what the domain contains, general enough that a meaningful cluster of notes belongs there. "Graph structure," "agent cognition," "processing workflow" — these are basic-level categories in this vault. They name a domain you can reason about without being either uselessly abstract or unnecessarily narrow.
+
+But Rosch's deeper finding complicates this. Basic level is not fixed — it shifts with expertise. A novice's basic level for biology is "fish." A marine biologist's basic level is "salmonid." As understanding deepens, what counts as the right categorization granularity moves downward because the expert has enough context to make finer distinctions meaningful. The subordinate category that was too narrow for a novice becomes informationally rich for an expert.
+
+For vault MOCs, this means granularity should evolve with understanding, not just with volume. The vault's current split heuristic — CLAUDE.md prescribes splitting at 35-50 links — captures the volume dimension but misses the expertise dimension. A MOC might have only 25 notes but still benefit from splitting because the operator's understanding has deepened enough that the basic level has shifted. "Processing workflow" was basic level when the vault had a dozen notes about processing. Now, with distinct clusters around throughput, sessions, and forcing functions, the basic level has moved to "processing workflow throughput" — and the vault has already enacted this split, suggesting the principle operates even without being named. The deepening is not abstract — since [[incremental formalization happens through repeated touching of old notes]], each maintenance pass that sharpens a note also sharpens the operator's understanding of the domain, and it is precisely this accumulated understanding that makes the current MOC granularity feel inadequate and the finer distinctions feel necessary.
+
+Since [[community detection algorithms can inform when MOCs should split or merge]], the algorithmic approach and the cognitive approach complement each other. Community detection reveals WHEN boundaries have shifted by identifying dense clusters within a MOC. Basic level theory explains WHERE those new boundaries should land — at the level that maximizes informativeness for the current depth of understanding. A Louvain algorithm might tell you that graph-structure has bifurcated. Rosch tells you that the sub-MOCs should be "link semantics" and "network topology," not "wiki links" (too narrow) or "knowledge organization" (too broad). The algorithm finds the clusters; the theory names them at the right level.
+
+Since [[faceted classification treats notes as multi-dimensional objects rather than folder contents]], there is an interesting relationship between Ranganathan's framework and Rosch's. Faceted classification explains which AXES to categorize along (type, methodology, topic, role). Basic level theory explains what RESOLUTION to target on each axis. Together they predict that a well-designed classification system uses orthogonal facets at basic-level granularity — each dimension specific enough to filter meaningfully but general enough to group useful clusters.
+
+The expertise-shift mechanism has a vocabulary parallel. Since [[narrow folksonomy optimizes for single-operator retrieval unlike broad consensus tagging]], personal vocabulary in a single-operator vault evolves toward increasingly precise distinctions as understanding deepens — the same operator who once tagged notes "knowledge management" begins distinguishing "capture patterns" from "retrieval mechanisms" from "maintenance scheduling." The vocabulary shift and the categorization shift are two expressions of the same underlying process: expertise making finer distinctions meaningful. Basic level theory predicts when MOC titles should split; narrow folksonomy predicts when the operator's vocabulary has already outgrown those titles.
+
+This categorization judgment is exercised most visibly during MOC construction. Since [[MOC construction forces synthesis that automated generation from metadata cannot replicate]], the Lump phase of the Dump-Lump-Jump pattern IS basic level categorization in practice: the builder groups notes into clusters, decides which clusters deserve their own heading or sub-MOC, and senses the mental squeeze point where a single MOC becomes too coarse. Automated generation that matches notes to topics by metadata tags cannot perform this judgment because it has no mechanism to feel when the basic level has shifted — it classifies at whatever granularity the tags provide, regardless of whether that granularity serves the current understanding.
+
+The practical implication for agents is a testable heuristic: when creating or splitting a MOC, ask whether the title sits at basic level. Can you complete the sentence "This MOC covers everything about [title]" and have the scope be neither uselessly broad nor trivially narrow? Does loading this MOC orient you to a domain, or does it either overwhelm with scope or underwhelm with specificity? The answer depends on the current state of understanding — which is why MOC granularity is a living design decision, not a one-time architectural choice.
+
+---
+
+Source: [[tft-research-part3]]
+---
+
+Relevant Notes:
+- [[community detection algorithms can inform when MOCs should split or merge]] — algorithmic complement: community detection reveals WHEN boundaries should move, basic level theory explains WHERE they should land; the split signal from Louvain tells you a MOC has outgrown its category, basic level theory tells you what granularity the sub-MOCs should target
+- [[MOCs are attention management devices not just organizational tools]] — explains the cost of getting granularity wrong: a MOC at the wrong level wastes attention either through overloaded context (too superordinate) or fragmented orientation (too subordinate)
+- [[navigational vertigo emerges in pure association systems without local hierarchy]] — the failure mode that basic level targeting prevents: superordinate MOCs provide hierarchy but not useful landmarks, subordinate MOCs create too many landmarks to navigate between
+- [[faceted classification treats notes as multi-dimensional objects rather than folder contents]] — complementary classification theory: Ranganathan explains the axes of classification, Rosch explains the optimal resolution along each axis
+- [[progressive disclosure means reading right not reading less]] — MOC granularity determines disclosure effectiveness: a basic-level MOC loads the right amount of context for orientation, while superordinate MOCs load too broad a context and subordinate MOCs require loading multiple MOCs to orient
+- [[narrow folksonomy optimizes for single-operator retrieval unlike broad consensus tagging]] — parallel expertise-driven evolution: as understanding deepens, personal vocabulary becomes more precise (narrow folksonomy) and categorization becomes more granular (basic level shift); both are expressions of expertise making finer distinctions meaningful
+- [[incremental formalization happens through repeated touching of old notes]] — the mechanism that drives basic level shift: repeated touches deepen understanding, and that deepened understanding is what makes the current granularity feel too coarse and sub-MOCs feel necessary
+- [[cross-links between MOC territories indicate creative leaps and integration depth]] — diagnostic signal: notes appearing in multiple MOCs may indicate a MOC sitting at the wrong granularity level, where basic-level sub-MOCs would better capture the distinct domains those cross-links bridge
+- [[associative ontologies beat hierarchical taxonomies because heterarchy adapts while hierarchy brittles]] — foundation: basic level theory explains at what granularity the local hierarchy MOCs provide should operate within the heterarchical structure; MOCs are the controlled exception to pure association, and Rosch predicts their optimal resolution
+- [[MOC construction forces synthesis that automated generation from metadata cannot replicate]] — domain application: the Lump phase of MOC construction IS basic level categorization in practice; the builder decides whether a cluster of notes deserves its own sub-MOC by sensing the mental squeeze point, and this granularity judgment is precisely what automated generation cannot perform because it requires the domain expertise that Rosch's basic level shift depends on
+
+Topics:
+- [[graph-structure]]

package/methodology/batching by context similarity reduces switching costs in agent processing.md

@@ -0,0 +1,43 @@
+---
+description: Once you have fresh context per task, the next question is how to sequence work within a session — organizing by topic similarity minimizes the overhead of loading new context between tasks
+kind: research
+topics: ["[[processing-workflows]]"]
+methodology: ["Cognitive Science", "GTD"]
+source: [[tft-research-part3]]
+---
+
+# batching by context similarity reduces switching costs in agent processing
+
+Context switching has a cost. For humans, Leroy's attention residue research puts the recovery time at up to 23 minutes. For agents, the cost is different but real: loading context for a new topic consumes tokens, and the semantic distance between consecutive tasks determines how much re-orientation is required. Batching similar tasks together minimizes the frequency and severity of these switches. However, since [[attention residue may have a minimum granularity that cannot be subdivided]], even context-similar consecutive tasks still pay an irreducible floor cost at each boundary — batching reduces the variable component of switching cost (how much new context to load) but cannot eliminate the fixed component (the minimum cognitive redirection penalty). This means batching is necessary but not sufficient: it minimizes the severity of each switch without eliminating the fact that a switch occurred.
+
+The principle is straightforward. If you have ten inbox items — three about graph structure, four about processing workflow, and three about note design — processing all graph structure items consecutively means you load the graph structure context once and apply it three times. Processing them in random order means loading and unloading different topic contexts ten times. The total work done is the same, but the total switching cost is drastically lower in the batched case.
+
+For agent workflows, this translates to organizing task queues by context similarity rather than by priority or arrival order. A synthesis agent should complete all passes for one topic before moving to a different topic. A processing agent should handle all inbox items of one type before switching types. The ralph orchestration pattern already processes tasks sequentially from the queue, but the queue ordering determines how much context overlap exists between consecutive tasks.
+
+Since [[fresh context per task preserves quality better than chaining phases]], each task already gets its own session — this is the macro-level isolation that prevents attention degradation. Context-similar batching operates at the micro level: given that you will process tasks sequentially in fresh sessions, which ORDER minimizes total switching cost? The fresh session loads CLAUDE.md and vault context regardless, but the topic-specific context (relevant MOC, related notes, domain understanding) changes between batches. Processing three graph structure claims back-to-back means the knowledge-worker agent builds graph structure understanding once and carries the pattern across claims. This is [[spreading activation models how agents should traverse]] applied to queue design: topic context loaded for one task primes activation for the next, so the agent enters each subsequent task with relevant concepts already activated rather than starting cold.
+
+Since [[continuous small-batch processing eliminates review dread]], batching by similarity complements the small-batch philosophy. Small batches prevent accumulation (how much), while context-similar batching optimizes sequence (what order). The two heuristics are orthogonal and compound: process small batches of context-similar items for maximum efficiency with minimum dread.
+
+There is a tension with [[temporal processing priority creates age-based inbox urgency]]. Age-based priority says process the oldest items first because context decays with time. Context-similar batching says process related items together regardless of age. The resolution depends on the magnitude of each cost: if an item is about to cross the 72-hour critical threshold, temporal urgency overrides similarity batching. For items within the same urgency tier, similarity batching should determine order. Age sets the priority; similarity optimizes the sequence within each priority band.
+
+Since [[closure rituals create clean breaks that prevent attention residue bleed]], context-similar batching also reduces the residue gap between tasks. When consecutive tasks share context, the closure of one and the opening of the next involve less cognitive distance. The residue from a graph structure task is less harmful when the next task is also about graph structure — the "residue" is actually useful context.
+
+There is a second, deeper tension with [[incremental reading enables cross-source connection finding]]. Context-similar batching optimizes for efficiency by grouping related tasks together, but incremental reading deliberately disrupts that grouping to create forced context collision between different sources. The collision surfaces cross-source connections that sequential, topic-grouped processing would miss. The trade-off is switching cost (minimized by batching) versus serendipitous discovery (maximized by interleaving). Within a single source's claims, batching is unambiguously better because the claims already share context. Across sources, the question becomes whether the efficiency gains from topic-similar batching outweigh the discovery losses from not interleaving.
+
+The practical implication for queue design: when seeding a batch of claims from a single source, the claims are already context-similar (they came from the same material). Processing them in sequence leverages this natural similarity. When processing claims from multiple sources, the choice between topic-based batching and source-based interleaving depends on whether reflect adequately recovers cross-source connections after extraction, or whether some connections only surface through the juxtaposition of processing itself.
+
+---
+---
+
+Relevant Notes:
+- [[fresh context per task preserves quality better than chaining phases]] — addresses macro-level isolation (separate sessions per phase); this note addresses micro-level sequencing (within a session, how to order tasks)
+- [[continuous small-batch processing eliminates review dread]] — complementary forcing function: small batches prevent accumulation, context-similar batching optimizes the sequence within those batches
+- [[closure rituals create clean breaks that prevent attention residue bleed]] — closure between batches is more effective when the next batch shares context with the previous one, reducing the residue gap
+- [[temporal processing priority creates age-based inbox urgency]] — potential tension: age-based priority says process oldest first, context similarity says process related items together; both heuristics serve different goals
+- [[MOCs are attention management devices not just organizational tools]] — applies the same Leroy attention residue mechanism at the session level: MOCs reduce per-session orientation cost, while batching reduces cross-task switching cost
+- [[incremental reading enables cross-source connection finding]] — opposing sequencing strategy: batching minimizes switching cost by grouping similar topics, while incremental reading deliberately maximizes switching for serendipitous cross-source collision; the tension is efficiency vs discovery
+- [[spreading activation models how agents should traverse]] — mechanism: context-similar batching leverages spreading activation efficiency; topic context loaded for one task primes activation for the next similar task, reducing re-orientation cost
+- [[attention residue may have a minimum granularity that cannot be subdivided]] — limits: batching reduces the variable component of switching cost (semantic distance between tasks) but cannot eliminate the fixed component (irreducible redirection penalty); even context-similar tasks pay the floor cost at each boundary
+
+Topics:
+- [[processing-workflows]]

package/methodology/behavioral anti-patterns matter more than tool selection.md

@@ -0,0 +1,42 @@
+---
+description: PKM failure research shows systems break through habits not software — the Collector's Fallacy, productivity porn, and under-processing kill vaults regardless of which app hosts them
+kind: research
+topics: ["[[processing-workflows]]", "[[maintenance-patterns]]"]
+methodology: ["PKM Research"]
+source: [[7-3-failure-modes-anti-patterns]]
+---
+
+# behavioral anti-patterns matter more than tool selection
+
+The research is clear: Personal Knowledge Management systems fail through counter-productive habits, not inadequate software. The Collector's Fallacy (saving = learning), productivity porn (optimizing = producing), under-processing (capturing without transformation), over-engineering (structure before content) — these behavioral patterns kill vaults regardless of whether they run in Obsidian, Notion, Roam, or index cards. Tool debates miss the point because the failure mode is upstream of the tool.
+
+This explains the recurring disappointment cycle in the PKM community. Users migrate from Evernote to Notion to Obsidian seeking features that will solve their problems, but since [[PKM failure follows a predictable cycle]], they carry their behavioral patterns from system to system. The new tool provides a fresh start and temporary motivation, but the same habits reassert themselves. Tool-hopping is itself an anti-pattern — a manifestation of productivity porn that substitutes the effort of migration for the effort of processing.
+
+The implication cuts both ways. On one hand, it means most tool comparison debates are misallocated attention. If behavior dominates outcomes, obsessing over Dataview queries versus Notion databases misses what actually matters. On the other hand, it means fixing behavior can rescue any reasonable tool. A user with good habits operating in a basic folder system will outperform a user with bad habits operating in a sophisticated graph database.
+
+This matters for agent-operated systems because agents operate under fundamentally different behavioral constraints. Agents don't experience the dopamine hit from collecting. They don't procrastinate through system-tweaking. They don't feel the satisfaction of highlighting that substitutes for understanding. Since [[structure without processing provides no value]], agents can enforce the processing requirement mechanically in ways humans struggle to self-enforce. Because [[skills encode methodology so manual execution bypasses quality gates]], encoded workflows can make the anti-patterns structurally impossible rather than merely discouraged. And since [[hook enforcement guarantees quality while instruction enforcement merely suggests it]], the structural enforcement goes deeper than skills alone — hooks fire on every relevant event regardless of agent attention, which is the precise capability humans lack. Human PKM fails through behavioral anti-patterns because humans cannot make good behavior automatic; hook-enabled agent systems can. And since [[WIP limits force processing over accumulation]], hard architectural constraints can prevent the Collector's Fallacy at the system level — when inbox is full, the only way forward is processing, not more capture.
+
+The industry convergence on vibe notetaking illustrates this principle at product scale. Since [[vibe notetaking is the emerging industry consensus for AI-native self-organization]], tools from Notion AI to Mem to Supermemory all converge on the "dump and AI organizes" paradigm. The tool-level convergence is real — everyone is building essentially the same capture interface. But whether any of these tools produces knowledge depends on the behavioral layer: does the AI actually transform content into claims and reasoned connections, or does it just file things with better labels? The industry consensus operates at the tool level. Whether the tool works operates at the behavioral level. The convergence changes nothing about the fundamental finding that behavior dominates outcomes.
+
+Since [[storage versus thinking distinction determines which tool patterns apply]], the anti-pattern catalog itself is system-type-specific. The Collector's Fallacy, productivity porn, and under-processing are thinking-system failures — patterns that damage systems meant for synthesis. Storage systems have their own characteristic failures: retrieval latency, classification ambiguity, orphaned assets. Applying thinking-system anti-pattern detection to a storage system produces false alarms; applying storage-system metrics to a thinking system produces false confidence.
+
+But agents may introduce their own failure modes. An agent that moves files without transformation performs Lazy Cornell at LLM throughput — since [[the generation effect requires active transformation not just storage]], mere file shuffling creates no cognitive hooks, whether the shuffler is human or automated. An agent that adds links without articulating why creates false density. An agent that optimizes for coverage metrics rather than retrieval utility could produce a well-organized graveyard indistinguishable from human under-processing at larger scale. The human anti-patterns might not transfer directly, but the underlying failure mode — activity that mimics production without producing — surely does. Since [[verbatim risk applies to agents too]], the question becomes: what are the agent-specific behavioral anti-patterns, and how do we detect them before they corrupt the knowledge graph?
+---
+
+Relevant Notes:
+- [[PKM failure follows a predictable cycle]] — documents the 7-stage cascade that behavioral patterns create; tool selection doesn't appear in the failure sequence
+- [[structure without processing provides no value]] — the Lazy Cornell research that proves structure alone is insufficient; behavior (processing) is what creates value
+- [[productivity porn risk in meta-system building]] — one specific anti-pattern applied to agent contexts; building workflows can substitute for producing output
+- [[verbatim risk applies to agents too]] — tests whether agents have their own version of under-processing: well-structured summaries that reorganize without generating insight
+- [[skills encode methodology so manual execution bypasses quality gates]] — how encoded workflows can prevent anti-patterns by making good behavior structural rather than aspirational
+- [[WIP limits force processing over accumulation]] — the forcing function that makes Collector's Fallacy architecturally impossible: hard caps remove the choice between capturing more or processing now
+- [[temporal separation of capture and processing preserves context freshness]] — why under-processing is particularly damaging: Ebbinghaus decay (50% within 1 hour, 70% within 24 hours) means delayed processing loses context permanently; this grounds the urgency of the anti-pattern consequences
+- [[the generation effect requires active transformation not just storage]] — the cognitive principle that distinguishes real processing from mimicry: did the operation produce something that didn't exist before?
+- [[cognitive outsourcing risk in agent-operated systems]] — the third leg of the agent-failure-modes trio: while this note asks what agent anti-patterns might emerge, cognitive outsourcing addresses a different failure where the agent works perfectly but human capability atrophies
+- [[hook enforcement guarantees quality while instruction enforcement merely suggests it]] — the mechanism that makes good behavior structural: hooks fire regardless of attention state, which is precisely what separates agent systems from human ones where behavioral anti-patterns persist because enforcement is aspirational
+- [[vibe notetaking is the emerging industry consensus for AI-native self-organization]] — industry-scale illustration: the tool convergence is real (everyone builds dump-and-organize), but whether any implementation works still depends on whether the AI transforms content or merely files it — behavior dominates outcomes regardless of which vibe notetaking tool hosts the capture
+- [[storage versus thinking distinction determines which tool patterns apply]] — specifies which anti-patterns apply where: Collector's Fallacy and under-processing damage thinking systems; over-engineering and retrieval latency damage storage systems; the system type determines which behavioral failures to monitor
+
+Topics:
+- [[processing-workflows]]
+- [[maintenance-patterns]]

package/methodology/betweenness centrality identifies bridge notes connecting disparate knowledge domains.md

@@ -0,0 +1,57 @@
+---
+description: Graph theory metric that quantifies how often a note lies on shortest paths between others, revealing structural bridges worth developing, single points of failure, and gaps worth filling
+kind: research
+topics: ["[[graph-structure]]"]
+methodology: ["Network Science"]
+source: [[tft-research-part3]]
+---
+
+# betweenness centrality identifies bridge notes connecting disparate knowledge domains
+
+Graph theory offers a precise measure for something the vault otherwise detects only through intuition: which notes serve as bridges between otherwise disconnected clusters of thinking. Betweenness centrality counts how often a node appears on shortest paths between all other node pairs in the graph. A note with high betweenness doesn't just connect to many things — it connects things that would otherwise have no short path to each other.
+
+This is a different claim than saying a note has many links. A MOC with fifty outgoing connections has high degree centrality, but it might connect notes that already have other paths between them. Betweenness centrality captures something more specific: structural necessity. If you removed a high-betweenness note from the graph, the average path length between remaining notes would increase. Some concepts that were two hops apart might become five hops apart, or entirely disconnected.
+
+The distinction matters because it separates popularity from structural importance. Since [[small-world topology requires hubs and dense local links]], the vault already expects hub nodes with many connections. But not all hubs are bridges. A MOC that connects thirty notes within one tightly-clustered topic has high degree but may have low betweenness if those notes are densely interconnected without it. A synthesis note connecting two different topic clusters — say, linking graph-structure concepts to processing-workflow concepts — might have fewer total connections but far higher betweenness because it's the only short path between those domains.
+
+## What betweenness reveals for maintenance
+
+Periodic betweenness analysis surfaces three actionable signals:
+
+**Bridge notes worth developing.** Notes with high betweenness are structural load-bearers. If they're thin or poorly written, the entire traversal between two domains depends on a weak link. These notes deserve reweave attention because their quality disproportionately affects graph navigability. Since [[each new note compounds value by creating traversal paths]], the notes that CREATE the most traversal paths are the ones sitting on the most shortest paths — and betweenness centrality identifies exactly those notes.
+
+**Missing bridges between isolated clusters.** When betweenness analysis reveals that no note bridges two topic clusters, that's a gap signal more specific than what MOC coverage alone reveals. The question shifts from "are these notes in a MOC?" to "can you get from topic A to topic B in few hops?" If the answer is no, the vault has a structural hole that a synthesis note could fill. This gap detection complements what [[community detection algorithms can inform when MOCs should split or merge]] reveals at the group level — community detection shows that clusters have drifted apart, betweenness analysis shows specifically where the bridge is missing.
+
+**Single points of failure.** A note with extremely high betweenness relative to its neighbors is a single point of failure. Remove it, and two clusters lose their connection. The vault's `find-bridges.sh` script already implements a version of this — detecting notes whose removal would disconnect the graph. Betweenness centrality extends the concept from binary (bridge or not) to continuous (how much of a bridge).
+
+## The qualitative-quantitative pairing
+
+This claim complements what [[cross-links between MOC territories indicate creative leaps and integration depth]] captures qualitatively. Cross-MOC membership says "this note appears in multiple topics, which suggests integration thinking." Betweenness centrality says "this note lies on many shortest paths, which means it's structurally critical for navigation between domains." The two measures sometimes converge — a note in both graph-structure and agent-cognition MOCs might also have high betweenness — but they can diverge. A note might appear in only one MOC but still serve as the primary bridge between two clusters within that MOC's territory.
+
+The practical implication: use cross-MOC membership for assessing synthesis quality (did the author think across domains?), use betweenness centrality for assessing graph health (can the agent traverse between domains?). They answer different questions about the same structural phenomenon.
+
+## Agent implementation
+
+Since [[spreading activation models how agents should traverse]], betweenness centrality has a direct cognitive interpretation. Activation flowing from any concept toward any other concept will preferentially pass through high-betweenness nodes because those nodes sit on shortest paths. These nodes become natural waypoints — concepts the agent encounters repeatedly during diverse traversals. This repetition itself is a signal: if the agent keeps encountering the same note from different starting points, that note is structurally central.
+
+Since [[role field makes graph structure explicit]] proposes a `bridge` role for notes connecting distant domains, betweenness centrality provides the computable criterion for that designation. Rather than manually classifying notes as bridges, the metric identifies them from the graph's structure — and since [[backlinks implicitly define notes by revealing usage context]], backlink accumulation already reveals which notes function as hubs through popularity, but betweenness centrality captures something backlinks miss: structural necessity. A note with few backlinks might still have high betweenness if it happens to be the only short path between two clusters.
+
+For vault analysis scripts, betweenness can be computed from the wiki link graph. Each `[[link]]` is a directed edge. Computing all-pairs shortest paths and counting node appearances gives betweenness scores. Since [[dangling links reveal which notes want to exist]] by tracking reference frequency for future nodes, betweenness centrality complements by tracking structural position for existing nodes. Together they provide both forward-looking demand signals and backward-looking structural analysis.
+
+The uncertainty: betweenness centrality assumes shortest-path traversal, but real agent navigation often follows activation strength rather than strictly minimizing hops. High-decay focused retrieval follows shortest paths (where betweenness matters most), but low-decay exploratory synthesis might traverse longer paths where betweenness is less predictive. The metric is most useful for understanding focused navigation; for exploratory synthesis, cross-MOC membership may better capture what matters.
+
+---
+---
+
+Relevant Notes:
+- [[cross-links between MOC territories indicate creative leaps and integration depth]] — the qualitative complement: cross-MOC membership identifies bridges by topic diversity, while betweenness centrality identifies them by path structure
+- [[small-world topology requires hubs and dense local links]] — provides the structural context where betweenness matters: power-law distributions create the hub-spoke topology that makes some nodes disproportionately important for path routing
+- [[each new note compounds value by creating traversal paths]] — betweenness centrality measures exactly WHICH notes contribute most to path creation: high-betweenness notes are the ones whose removal would most reduce reachability
+- [[spreading activation models how agents should traverse]] — activation flows preferentially through high-betweenness nodes because they sit on more shortest paths, making them natural traversal waypoints
+- [[dangling links reveal which notes want to exist]] — demand-side complement: dangling links predict future hubs by reference frequency, betweenness centrality identifies existing hubs by structural position
+- [[community detection algorithms can inform when MOCs should split or merge]] — complementary macro view: betweenness identifies important individual nodes, community detection identifies meaningful group boundaries; together they provide micro and macro graph health monitoring
+- [[role field makes graph structure explicit]] — betweenness centrality provides the computable basis for the proposed bridge role designation: high-betweenness notes are the structurally critical connectors that a role field would make queryable without recomputation
+- [[backlinks implicitly define notes by revealing usage context]] — clarifies the degree-vs-betweenness distinction: backlink accumulation measures popularity (how many notes reference this one), while betweenness centrality measures structural necessity (how many shortest paths run through it)
+
+Topics:
+- [[graph-structure]]

package/methodology/blueprints that teach construction outperform downloads that provide pre-built code for platform-dependent modules.md

@@ -0,0 +1,42 @@
+---
+description: Platform-dependent modules ship as construction instructions so agents build contextually adapted artifacts — but blueprint staleness creates maintenance cost that may qualify the claim
+kind: research
+topics: ["[[design-dimensions]]"]
+confidence: speculative
+methodology: ["Original", "Systems Theory"]
+source: [[composable-knowledge-architecture-blueprint]]
+---
+
+# blueprints that teach construction outperform downloads that provide pre-built code for platform-dependent modules
+
+The standard distribution format for software modules is the download: pre-built artifacts that work immediately upon installation. For platform-independent knowledge system modules — YAML schemas, wiki link conventions, atomic note patterns — downloads work fine because the artifact is a text file that any agent can read. But since [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]], the automation and orchestration layers require platform-specific infrastructure: hooks need event bindings that differ across platforms, skills need metadata formats specific to each agent runtime, and pipelines need coordination mechanisms that vary from subagent spawning to queue-based orchestration. A pre-built hook for Claude Code's PostToolUse event is meaningless on a platform that fires events differently or not at all.
+
+The alternative is the blueprint: instructions that teach the agent how to construct the module in its specific environment. Rather than shipping a finished hook file, the blueprint explains what quality guarantee the hook should provide, what event type to bind, what the validation logic should check, and how to format the response. The agent reads the blueprint and builds the artifact adapted to its platform, its schema, and its use case. This is Christopher Alexander's generative insight applied to knowledge system distribution — each module takes its shape according to its context, not from a predetermined form.
+
+Four types of adaptation make blueprints structurally superior to downloads for platform-dependent modules. First, platform adaptation: since [[platform fragmentation means identical conceptual operations require different implementations across agent environments]], a validation hook blueprint produces bash scripts with JSON responses on Claude Code and TypeScript handlers with different event bindings on OpenClaw. The same quality guarantee, different implementations — and blueprints reduce the N-platforms times M-operations multiplier by shipping semantic guarantees that each platform compiles into native code rather than requiring per-platform pre-built artifacts. Second, environment adaptation: file paths, MCP configurations, tool availability, and directory structures vary across deployments even on the same platform. A blueprint parameterizes these while a download hardcodes them. Third, use-case adaptation: a processing pipeline blueprint for research extraction produces different phase sequences than the same blueprint configured for project logging or creative capture. The module's purpose shapes its construction. Fourth, self-extension: since [[self-extension requires context files to contain platform operations knowledge not just methodology]], an agent that builds a module from a blueprint understands how that module works and can modify it as needs evolve — unlike a downloaded artifact that functions as a black box.
+
+The practical test for blueprint quality is whether an agent on a platform the blueprint author has never encountered can read the instructions and build a working module. This test reveals the boundary between genuine blueprints and disguised downloads. A blueprint that says "create a file at `.claude/hooks/validate-note.sh` with this content" is still a download — it prescribes a specific artifact rather than teaching construction principles. A genuine blueprint says "create a validation hook that fires after file writes, checks YAML frontmatter against the active schema, and surfaces warnings that the agent can act on immediately" — leaving the implementation to the agent's platform knowledge.
+
+But the blueprint format carries a shadow side that qualifies the outperformance claim. Since [[platform adapter translation is semantic not mechanical because hook event meanings differ]], blueprints must describe quality guarantees at the semantic level — timing, scope, enforcement properties — not just the mechanical steps. Writing accurate semantic descriptions is harder than writing code. A hook that works is self-documenting; a blueprint that accurately captures what the hook achieves requires understanding the guarantee decomposition that the adapter translation note describes. Blueprint authors must think about what the module does, not just how it does it on their platform.
+
+More critically, blueprints can go stale. Since [[derived systems follow a seed-evolve-reseed lifecycle]], the staleness problem is a variant of configuration drift: platform APIs evolve, event models change, new capabilities emerge that invalidate old construction instructions. A downloaded module either works or it does not — the failure is immediate and obvious. A stale blueprint produces subtly wrong artifacts: a hook that fires at the wrong moment, a skill that uses deprecated metadata, a pipeline that misses a newly available coordination primitive. The "stale blueprint" failure mode is insidious because the agent successfully builds something — it just builds the wrong thing. This is harder to detect than a download that fails to install.
+
+The relationship to the composable architecture is direct. Since [[composable knowledge architecture builds systems from independent toggleable modules not monolithic templates]], modules need a distribution format that preserves their independence. Downloads create implicit platform coupling — the artifact embeds assumptions about where it runs. Blueprints preserve platform independence because the construction instructions can target any platform that provides the necessary capability tier. And since [[derivation generates knowledge systems from composable research claims not template customization]], derivation produces the configuration choices while blueprints handle the last mile: translating those choices into constructed infrastructure on the agent's specific platform. Without blueprints, derivation would still produce monolithic downloads that resist cross-platform deployment.
+
+The outperformance claim remains open because the maintenance cost of keeping blueprints current across evolving platforms is unquantified. The advantages — platform adaptation, environment adaptation, use-case adaptation, self-extension — are clear for the initial construction event. Whether those advantages survive the ongoing cost of blueprint maintenance as platforms evolve is the empirical question this claim cannot yet answer.
+
+---
+---
+
+Relevant Notes:
+- [[composable knowledge architecture builds systems from independent toggleable modules not monolithic templates]] — the architecture this shipping format serves; modules must be distributable, and the blueprint-vs-download choice determines whether distribution preserves composability or collapses back into monolithic artifacts
+- [[four abstraction layers separate platform-agnostic from platform-dependent knowledge system features]] — identifies which modules need blueprints: foundation and convention layers transfer as files (downloads work), but automation and orchestration layers require platform-specific construction that only blueprints can adapt
+- [[self-extension requires context files to contain platform operations knowledge not just methodology]] — the prerequisite: an agent can only build from a blueprint if its context file teaches platform construction competencies; without knowing how to create hooks, skills, or agents on its platform, the blueprint is unreadable
+- [[platform adapter translation is semantic not mechanical because hook event meanings differ]] — explains why downloads fail for automation modules: pre-built hooks carry implicit event semantics from the source platform that do not transfer mechanically to the target
+- [[derivation generates knowledge systems from composable research claims not template customization]] — complementary process: derivation decides WHAT to build by traversing the claim graph, blueprints decide HOW to ship the result so agents can construct it on their platform
+- [[platform fragmentation means identical conceptual operations require different implementations across agent environments]] — the problem blueprints solve at scale: fragmentation creates an N-platforms times M-operations multiplier, and blueprints reduce this by shipping semantic quality guarantees that each platform compiles into native implementations rather than requiring per-platform pre-built code
+- [[derived systems follow a seed-evolve-reseed lifecycle]] — the stale blueprint problem maps to the reseeding phase: as platforms evolve, blueprints accumulate drift just as derived configurations do, and re-derivation from current platform knowledge is the principled response to staleness
+- [[methodology development should follow the trajectory from documentation to skill to hook as understanding hardens]] — blueprints are the skill-level shipping format in the trajectory: automation modules ship as construction instructions (blueprint-level encoding) because the pattern is understood enough to teach but not deterministic enough for hook-level generation
+
+Topics:
+- [[design-dimensions]]