# The Vault Bootstrap Kit **One instruction that stands up an AI-managed second brain for any domain.** This is the abstract framework, not anyone's particular vault. It describes how to build an Obsidian vault driven by a pipeline of scheduled AI routines: what to build, in what order & the failure modes that cost real downtime to discover. It is deliberately domain-neutral. The same structure runs a company operating system, a research practice, a training log or a household. Point the interview at a different domain and you get a different vault out of the same machinery. None of this is invented from nothing. **Phase 0** below lists the open-source projects that do the load-bearing work, with links & licences, and **The system components** describes the fourteen subsystems that are invisible at five routines & load-bearing at forty. Written by Steve Boogar. Use it, fork it, argue with it: --- ## The one thing to internalize first **The interview is the product.** A vault built without understanding the person's context is abandoned inside a week. The highest-leverage hour in this entire process is the conversation you have before you create a single folder. Do not skip it because folder-creation feels more productive. The interview decides which domain routines to build, which data sources to wire, the governance facts every routine depends on & the cadence that matches how the person actually works. Its answers become the governance document. ### The interview — ten categories Run these before creating a single folder. Spend 5–10 minutes per category. Capture the answers verbatim — they become the governance doc's "Critical Context" section. **1. Role & context.** What do you do? What is the thing you are trying to manage with this vault? (A company. A personal site. A training practice. A household.) Who else is involved? What is the one sentence you would use to describe this vault's purpose? **2. Systems & tools.** Where does your data live today? (Email provider, chat tool, calendar, code repos, CRM, notes app, file storage.) For each: can it be crawled programmatically, or is it manual-only? Which ones are you already logged into on the machine that will run the vault? **3. Daily rhythm.** When does your day start & end? When do you have uninterrupted time to read a brief? When is the worst time to be interrupted? Do you work weekends? What timezone & does it change? **4. Current pain.** What falls through the cracks today? What do you forget to follow up on? What information do you wish you had at the start of each day? What are you tracking in your head that you wish something else tracked? **5. Key relationships & entities.** Who or what do you track? (Customers, investors, team members, vendors, training partners, family members — whatever matters in this domain.) For each: what is the signal that tells you something changed? Where does that signal live? **6. Decision surface.** What decisions do you make repeatedly? What information do you wish you had when making them? What decisions have you made badly in the last month because you were missing context? **7. Content & communication.** Do you publish anything? (Blog, newsletter, social, internal updates, investor emails.) If so, in whose voice? Do you have existing style rules or a voice guide? What channels do you post to? **8. Objectives.** What are you trying to accomplish in the next 90 days? What does success look like? What are the 2–3 strategic pillars everything should ladder up to? **9. Privacy & sensitivity.** What must NEVER appear in a shared or team-visible output? (Names, deals, health data, financial figures, an unannounced personnel change.) For each sensitive domain: who may see it? Name the confidential lanes explicitly — they become deny-list entries in the maintenance skill. **10. Learning & growth.** Is there a body of knowledge you need to hold in your head but don't? (A codebase, a regulatory framework, a medical protocol.) How do you learn best — daily drip or deep dive? What would you read every morning if someone wrote it for you? ### After the interview — synthesis From the answers, derive four things before building anything: 1. **The routine build list** — which domain routines (Phase 3) to build, and which to skip. Each is gated on a condition from the interview: if they answered "no" to publishing, skip content-ideation; if they have no codebase, skip product-intel. 2. **The governance facts** — the critical-context block for the governance doc. These are the facts every routine depends on: identifiers, paths, timezone, pillars, sensitivity rules. 3. **The schedule** — when each routine fires, based on their daily rhythm. The synthesis must land before they start work; the crawler must run after their last meeting. 4. **The explicit skips** — which routines you are NOT building, and why. Writing the skips prevents a future session from re-proposing something the interview already ruled out. 5. **The improvement-layer audit.** Answer all three in writing. A skip must be justified, not achieved by omission: - Which routine makes the vault's **content** better — not merely current? (deepens a topic, researches against primary sources, upgrades a thin note into a good one) - Which routine notices **what this system cannot yet do**, and proposes new routines? - Which routine reviews the vault's **architecture**, as distinct from its tidiness? If any answer is "none", write why in one sentence. **"The person will notice" is not an answer** — it is the exact failure mode this audit exists to prevent. See *A pipeline of pure detection improves nothing* below for why this item is here at all: a bootstrap that got everything else right still shipped all three gaps, because nothing in this document asked. Confirm all five with the person before proceeding. Their confirmation is the gate to Phase 1. The ten categories above are the minimum interview. A richer version with lessons-learned from multiple real bootstraps (what turned out to matter, what people under-report, what follow-up questions surface the real answer) lives in the source vault's `Interview Protocol.md` — if you are building from the full internal kit rather than this public edition, read that file instead. Example synthesis output (short form — expand as needed): ``` Routine build list: crawler, synthesis, site-maintainer. Skip all others. Governance facts: repo at ~/dev/my-site, Netlify deploy, MT timezone, start 8 AM. Schedule: site-maintainer 11:40 PM → crawler 7:00 PM → synthesis 9:00 PM. Explicit skips: product-intel (no codebase), content-ideation (no blog), investor-prep (not fundraising), competitive-scan (no competitors). ``` --- ## Phase 0: What this is built on Read this before Phase 1. Four open-source projects do real work in a mature version of this system, and all four are public & installable in minutes. Cloning the right ones first saves you from re-deriving a command surface, a prompt optimizer, a research engine & a spec standard by hand. ### obsidian-second-brain — the command surface · Eugeniu Ghelbur A 44-command cross-CLI skill (Claude Code, Codex, Gemini CLI, OpenCode) that turns any Obsidian vault into an AI-first second brain. Two commands are worth the install on their own: `/obsidian-emerge` scans the last 30 days of dated notes & names the pattern you never named, and `/obsidian-challenge` red-teams an idea against your own history. This project is the origin of the contradiction-detection layer described below, & of the claim the whole design rests on: the model is not the moat, your notes are. ### FAPO — the prompt optimizer · Cisco Foundation AI · Apache-2.0 Fully Automated Prompt Optimization. It treats a multi-step LLM pipeline as an inspectable graph, records every intermediate step, attributes each failure to a prompt, an upstream evidence source or the chain structure itself, then edits the prompt — escalating to chain parameters or chain structure only when attribution shows prompts can no longer help. That attribution step is the difference between "the output was bad" & "step three's retrieval was bad," which is the difference between guessing & optimizing. This is the machinery behind self-improving prompts below. The wiring that makes it cheap: the grader routine's scorecards *are* the eval labels, so you are not building a labelled dataset, you are already producing one. It runs against a local CLI on a normal subscription with no API key, which makes the session limit rather than cost the binding constraint. ### STORM — the research engine · Stanford OVAL Multi-perspective question-asking plus outline-driven synthesis: it interviews itself from several viewpoints before writing, which is why its long-form output has an actual structure instead of a list. Two configuration notes matter for vault use. Point its language model at a local CLI rather than an API key, & use its vector retriever over **your own vault** so synthesis grounds on your notes rather than only the open web. Without search keys the web retriever rate-limits quickly, so plan vault-first. ### ProductSpec — the intent harness · Gokul Rajaram · MIT An open standard for product intent: Product Spec → Engineering Spec → Code → Evaluation → Learning, with run receipts & decision traces as companion artifacts. It ships two loadable agent skills — one for consuming a spec, one for authoring & validating it — installable with `npx skills add gokulrajaram/ProductSpec`. What it contributes here is the scope fence: what to build, what **not** to build, how to prove completion & when to stop and re-plan. It is also the cleanest example of the upstream-watcher routine class — a routine that watches a third-party repo by commit SHA & does nothing at all when the SHA has not moved. ### TasteSkill — the anti-slop primitives · MIT Not a dependency, but the source of several structures used throughout: hard bans over soft guidance, brief inference before generation, pre-flight checklists, numeric dials, design locks & model-specific variants. All of these appear in the methodology-file anatomy below. ### The two you have to build yourself Two more pieces are load-bearing & have no public equivalent, because they encode your context rather than a general capability: - **A canonical tool-patterns repo.** One markdown file per external tool your routines touch (post a message, write a vault file, read a calendar, run a git operation), each stating the one canonical pattern, where it came from & a copy-pasteable example. Plus an audit log & a map of which routines use which pattern. - **A planning hub for whatever you actually produce.** A living opportunity tree, a folder per initiative with a plan, a one-pager, user stories & a spec, all from templates, all indexed. The discipline that makes it work is duller than it sounds: every artifact type has a template, & nothing exists that is not in the index. ### What to clone on day 1 Only two are worth standing up before the vault exists. **The 44-command skill**, because it gives you a working command surface on an empty vault, and its emergence & challenge commands are the cheapest version of the adversarial layer you would otherwise build in week three. **Your own canonical-patterns repo**, even as three near-empty markdown files. It costs an hour on day one & it is the only thing that stops forty routines each inventing their own message-posting convention. Retrofitting it across a grown pipeline is the expensive path, and you will not enjoy it. The research engine & the prompt optimizer are week three or later. One needs a corpus & the other needs eval labels, & both are useless against an empty vault. The spec standard arrives when you start shipping artifacts worth specifying. --- ## Phase 1: Foundation Nothing automated runs yet. You are laying the substrate everything else depends on. **Folder structure.** Semantic names, never numbered prefixes. Numbered folders collide, break the moment you insert one & embed brittle paths across every routine. A working top-level set: a pipeline folder for task infrastructure (methodology files, logs, todos, proposals), a folder for dated daily notes, a journal folder, a reference folder, templates, attachments, a dashboard at the root and a governance document at the root. Add domain folders only for domains the interview surfaced. Empty folders are clutter. **The governance document.** One file every routine and every interactive session reads first. It holds the vault's purpose and the person's context, the folder map, the critical-context block, the routine schedule table, the cross-task data-flow diagram, the writing rules & the universal constraints for all tasks. Here is a minimal working example — fill each section from your interview answers: ```markdown # [Vault Name] — Governance ## About This Vault [One paragraph: what this vault manages and who it's for.] ## Vault Structure [A tree of your folder names, copied from what you just created.] ## Critical Context - **[Domain identifier]:** [the URL / repo / CRM / whatever your routines read] - **Timezone:** [your timezone] - **Working start:** [when the person starts their day — briefs must land before this] - **[Domain-specific facts]:** [deploy model, key contacts, strategic pillars — whatever every routine needs to know. These come directly from interview categories 2, 5, 8.] ## Routine Schedule | Time | Routine | Purpose | |------|---------|---------| | [time] | [name] | [one line] | ## Data Flow [Which routine feeds which. Even for two routines, write it down. Example:] [site-maintainer] → drafts + changelog [crawler] → daily note [synthesis] reads both → DM to person → [loop-closer] reads replies ## Writing & Style Rules [Voice, formatting, anything from interview category 7.] ## Constraints for All Tasks 1. Read the vault-maintenance skill first 2. Partial data > no data 3. Read before writing 4. Log every run 5. Update methodology at end of run 6. [Domain-specific constraints from interview category 9] ``` **The maintenance skill.** Defines folder structure, naming conventions, the folder-ownership table (which routine may write where), log-rotation thresholds and the tidiness checklist. Critically: **install it as something routines can actually load.** A single source of truth for where files go is worthless if nothing can read it. How to install depends on your harness: in Claude Code, save it as a skill file (`.claude/skills/vault-maintenance/SKILL.md`) and reference it by name; in a plain scheduled-prompt setup, include its path in every routine's Step 0 ("read `Pipeline/vault-maintenance-skill.md`"); in any case, **verify a routine can actually read it** by running one and checking. The source vault mandated this skill but never installed it for weeks — routines kept operating on stale assumptions. **Infrastructure files.** For a minimal vault (2–3 routines), you need three: a todos file, a reflection log & the methodology files themselves. Add an efficacy log, improvements tracker & proposals file once you cross ~5 routines. Add coaching tips once the meta-review exists. All should have frontmatter and a "newest entries at top" header. Decide log ordering now and write it into each header. Newest-first is the right default, because both humans and routines read the head for current state. **Naming conventions.** Dated files `YYYY-MM-DD[-descriptor].md`. Standing docs in Title Case with no date. Weekly rollups `YYYY-Wnn.md`. No special characters in filenames. Wikilinks always `[[folder/filename|Display Name]]`. YAML frontmatter on every file. ### Day 1 Checklist Everything above, condensed into one ordered list. Check each off before moving to Phase 2. ``` [ ] 1. Run the interview (10 categories). Write the synthesis (build list, governance facts, schedule, explicit skips). Confirm with the person. [ ] 2. Create the folder structure — Pipeline/ (with Routines/, Archive/), Daily Notes/, Journal/, Reference/, Templates/, Attachments/, plus domain folders from the interview. No empty folders. [ ] 3. Create the governance document (CLAUDE.md) at the root — fill in every section from the interview answers. Include the schedule table and data-flow diagram, even if there are only two routines. [ ] 4. Create the vault-maintenance skill — folder ownership table, naming conventions, log-rotation thresholds, tidiness checklist. VERIFY a routine can actually load it. [ ] 5. Create the Dashboard (Dashboard.md) — a hub linking every section. One wikilink per folder, one per standing doc. [ ] 6. Create infrastructure files with frontmatter and a "newest at top" header. For a small vault (2–3 routines): Task Todos, Task Reflection Log, one methodology file per planned routine. Add Efficacy Log, Improvements, Proposals once you cross ~5 routines. [ ] 7. Clone the 44-command skill (obsidian-second-brain) if using Obsidian. [ ] 8. Create a canonical-patterns repo — even three near-empty files. [ ] 9. Verify: governance doc is readable, maintenance skill is loadable, every folder exists, every infrastructure file has frontmatter. ``` --- ## Phase 2: Core routines These are domain-independent. Build them for every vault regardless of purpose, in dependency order, because each one's output is the next one's input. ### The Minimal Viable Vault — start here You do not need all five core routines on day two. The smallest useful vault has **two**: 1. **The crawler** — writes one dated daily note from whatever services matter. This is the keystone. If only one routine exists, it is this one. 2. **The synthesis** — aggregates the crawler's output into a brief delivered to the person. This is the routine they actually read. Add the other three as the vault earns them: 3. **The loop-closer** — add this the first time the person replies to the synthesis with a correction. Before that, you are the loop-closer (apply corrections manually). 4. **The janitor** — add this once you have ~10+ files and broken links start appearing. 5. **The meta-review** — add this once you have ~5+ routines and need to track which ones are actually producing value. Must exist before you scale past ~8 routines. 6. **The watchdog** — add this the first time a routine fails silently. At 2 routines you will notice a failure yourself; at 10 you will not. For a vault managing a single domain (a personal site, a training log, a household), the minimal pair (crawler + synthesis) plus one domain routine is enough to start producing value on day three. You can run this way for weeks before anything forces you to add the others. **Read this before you stop at the minimum.** Every routine on the list above *detects* — it crawls, tidies, delivers, corrects, watches, scores. None of them makes the vault's content better. So the list as written prescribes a pipeline that improves nothing, and a builder following it precisely reproduces that gap by construction. Two additions, in this order: 7. **The proposal function** — something that asks, monthly, *"what can this system not yet do?"* and writes the answer down. **This has no size threshold.** A two-routine vault needs to notice a missing capability exactly as much as a forty-routine one. Do not wait for the meta-review to earn it — that routine is correctly size-gated and a small vault will skip it, taking the proposal function down with it. Give the job to the watchdog instead: it is the one routine that exists at every size, and it already holds the manifest of what exists, which is the input for noticing what does not. **Propose, never build** — creating a scheduled task stays the person's decision, because a routine that spawns routines runs away from its owner. A month with nothing to propose is a valid month; write that line. 8. **One knowledge-deepening routine**, as soon as there is a corpus worth deepening — realistically week two or three. Below that, the vault's substantive content stays exactly as good as the day it was written, forever, and invisibly, because every health check is green the entire time. Two extra routines is a real cost against the abandonment risk the start-small path exists to manage. Take it anyway. The proposal function is cheap — a monthly question appended to a routine that already runs — and it is the one that recovers the others later. ### The full five (build all of these by the time you cross ~8 routines) **Build the watchdog before you cross ~8 routines, not after.** A routine that verifies expected outputs actually landed: file on disk, message actually sent. This is the highest-ROI routine in the entire pipeline and the most commonly skipped, because it feels premature. It is not. A pipeline with no output verification fails silently for days. 1. **The crawler.** Crawls the person's services and writes one dated daily note. Everything downstream consumes it. Rule: produce the note even if some sources fail. Partial data beats no data. 2. **The janitor.** Validates links, cross-links new files, curates the dashboard, archives oversized logs. Runs after the crawler. 3. **The synthesis.** Aggregates every routine's output into one brief delivered to the person, plus a reflection file. This is the routine they actually read & it earns the whole pipeline its keep. 4. **The loop-closer.** Reads the person's replies to the synthesis and implements corrections across the vault. This is how human judgment overrides automated state. 5. **The meta-review.** Scores every routine's efficacy from evidence, manages improvement items, surfaces coaching. Must exist before you scale up, because it is what keeps a growing pipeline honest. **Size-gate the *scoring*, not the *proposing*** — see the minimum-vault note above for why the two must not be one routine. **The janitor is two jobs, and merging them loses the one without a checklist.** Split them explicitly: | | **The janitor** | **The architect** | |---|---|---| | Asks | *Is the vault tidy?* | *Is the vault well-designed?* | | Checks | Links, frontmatter, orphans, hub currency, log rotation, duplicate files | Note granularity (split/merge), the path a newcomer reads, link topology, folder fit, duplication of *meaning* | | Cadence | Daily | Quarterly | | Authority | **Fixes** | **Proposes** | The architect's prompt is a reading exercise, not a scan: *"Read the vault as someone encountering it for the first time. Where would they get lost? Which notes have grown past one idea and should split? Which pairs say the same thing twice and should merge? Is the top-level folder set still the right partition of the work, or does it reflect what the work was six months ago? Propose changes with reasoning; change nothing."* Two rules make the split hold. **Quarterly is the correct cadence** — a design question asked daily degrades into a hygiene checklist inside a week, which is exactly how these collapse into one routine. And **the architect proposes, never fixes**: splitting a note or moving a folder is a decision with taste in it, and it invalidates inbound links across the vault. If the architect's output ever reads like a link report, the split has failed. --- ## Phase 3: Domain routines Build only what the interview justified. Each is gated on a condition from the interview: - **Product intel + product update post** — if they own or monitor a codebase. Scans the repo daily, translates git activity into business-framed intelligence. - **Marketing update** — if they own a public marketing site under version control (a second repo). Same engine as product intel, pointed at the marketing repo. - **Upstream-framework watcher** — if a third-party repo defines a standard their own work is built on. Watches by commit SHA; does nothing on quiet days. - **Content ideation** — if they publish or do thought leadership. Drafts articles in their voice. ⚰️ A companion **content-approval** nudger is the obvious next thought & the source vault retired it after **one run**: a publishing bottleneck is behavioral, so a daily one-tap ask just becomes another ignored message. A *weekly* publish gate is what survived. - **Competitive / market intel scan** — if they operate in a contested market. Watches social, product pages & changelog pages (social scans alone miss off-platform launches). - **Investor & board prep** — if they are fundraising or report to a board. Maintains a rolling investor email + board deck at "90%+ ready." - **Deal pitch-prep war-room** — if a single high-stakes live transaction has a near-term decision meeting. Event-scoped; retired when the deal closes. - **Many-to-one origination engine** — if one seller must run a broad sourcing funnel against a universe of counterparties, banker-style. - **Meeting prep** — if their calendar is meeting-heavy. Daily morning brief per meeting. ⚰️ **Retired in the source vault after two runs**, both on its build day, archived roughly three months later; the morning brief absorbed it by carrying a per-meeting calendar block. **Do not build it on day one.** Let the synthesis routine carry the calendar first & split prep out only against a named meeting that block failed to prepare you for. - **Meeting transcript intelligence** — if a capture service produces speaker-attributed transcripts. Processes recordings into crosslinked, relevance-scored vault notes. - **Knowledge deepening** — if the vault holds a body of knowledge that should get *better* over time, rather than only operational state. Weekly. Picks the note whose thinness costs the most (most-read, most-cited, most load-bearing for a live decision) and deepens it **against primary sources** — the actual documents, repos, specs & filings, never the vault's own summaries of them, which is circular and manufactures false corroboration. Cites every addition. A no-change week is a valid outcome. **This is the improvement layer's first member**; it sits on this optional list only because it needs a corpus to work on, and the *decision* to build it belongs at the gate into this phase, not here. Its write permission is the whole design problem — see *Detection without a paired write permission* below. - **Technical training** — if they own a complex or inherited codebase (bus-factor risk). One concept per day, depth over breadth, prerequisite-ordered. **Not a substitute for the routine above:** training makes the *person* better, deepening makes the *vault* better. Conflating them is how a vault runs for months with a static knowledge base & a green dashboard. - **Pilot feedback** — if they run customer pilots or POCs where silence is a signal. ⚰️ **Retired in the source vault after three runs**; a broader weekly customer-success lane appears to have absorbed it. Build the weekly first. - **Artifact-spec generator** — if they ship per-prospect tailored assets from a parametric repo. Produces a buildable-cold spec per request. - **Long-horizon initiative tracker** — if one critical multi-phase initiative is buried in a busy repo with a hard external deadline. Daily "did it move / did it ship?" - **Team dynamics monitor** — if they lead a team that coordinates in a shared chat tool. Reads the interpersonal layer (ownership vacuums, dropped commitments, exclusion patterns). **Principal-eyes-only by construction** — never posts in a team channel, never mentions the people it observes. - **Open-source readiness tracker** — if they are weighing a "go public" move on a proprietary asset. Read-only decision support: readiness punch-list + competitive landscape. - **Daily product UAT** — if they own the product their docs describe. A Playwright/headless browser pass over the live product: count everything, walk every flow, screenshot per-section, compare against docs & code. - **Error-monitoring early-warning** — if they run production services with an error monitor. Re-scans standing unresolved issues by frequency, because native alerting fires on novelty, not ongoing severity. - **Host / substrate health monitor** — if the automation self-hosts on a single machine rather than elastic cloud. Weekly, **advisory only**: OOM kill-log + swap trend + schedule-collision audit. Never changes anything itself. - **Personal / public-presence site maintainer** — if they own a personal public website. Daily reviewed improvements, never deployed without explicit per-change approval. Wire each one's output into the synthesis as you build it. --- ## Phase 4: Strategic and weekly routines These need baseline daily data to be useful. Every weekly routine must **add a framework layer** over the daily feed — cross-cutting patterns, trend lines, classification. Never just restate the dailies. Weekly/monthly routines to consider: weekly business retro (per-pillar wins/losses/blockers), weekly strategic pulse (roll up all on-demand sessions; count open questions — more than five signals overload), weekly sprint pulse, weekly hiring pulse, weekly partnership pipeline, weekly customer-success triage (score every account on engagement/sentiment), weekly competitive battle cards (strengths-forward), weekly engineering health (scored for a non-engineer), weekly publish gate or content publishing prep, monthly security & compliance audit. **On-demand strategic sessions**, triggered by a command rather than a clock: office hours (pressure-test a bet via forcing questions; verdict ship/park/kill), scope decision (force a choice into one of N scope modes), investigation (root-cause a recurring problem via a phased method). All three need an explicit no-trigger exit — if no matching command is found, exit as a logged no-op, never fabricate input. **Learnings capture** — a cross-cutting routine called by the others to append durable lessons into a categorized institutional memory. **A live status dashboard + its review loop** — once the vault has enough data worth glancing at, build it as **three** routines: a cheap frequent mechanical renderer (every ~2 hours), a daily reflective reviewer that screenshots the rendered output and scores it on a fixed rubric, and an hourly comment-triage drain once the person starts writing back. This fast-path / slow-sweep split recurs across the pipeline. **Schedule-as-code** — a committed manifest of every routine's canonical cron expression. It is the documented recovery move after the scheduler is disturbed (a single-fire task that re-asserts the entire schedule, then verifies). The manifest is the cure; the watchdog is the alarm. You need both. --- ## The routine template Every routine follows the same shape: 1. **A methodology file** with frontmatter and sections: Purpose, Inputs, Outputs, Run steps, Best Practices, Anti-Patterns, Cross-Task Dependencies, Run Log (newest at top). 2. **A prompt whose first four actions are always**: read the maintenance skill, read its own methodology file, check the todo file for its items, read-before-write anything it touches. 3. **Wired into the data flow**, declared in the governance doc. 4. **Registered with the meta-review** so it gets scored. 5. **Verified to exist.** Approving a routine is not creating it. The non-negotiable DNA. Reads its own methodology at start & appends learnings at end. Logs every run unconditionally, even a no-op. Verifies outputs on disk before claiming success. Treats prior outputs & subagent reports as hypotheses needing fresh verification. Produces partial output rather than none. Defaults conservative on anything irreversible. ### Example methodology file This is a complete, minimal methodology file for a crawler routine. Copy the structure, replace the domain-specific content. Every methodology file follows this shape. ```markdown --- title: Daily Crawler Methodology created: 2026-01-15 updated: 2026-01-15 runs_analyzed: 0 task_id: nightly-crawler schedule: "0 19 * * *" --- ## Purpose Crawl all connected services and write one dated daily note. Everything downstream consumes this note. If only one routine exists, it is this one. ## Inputs - Email (Gmail / Outlook — last 24h) - Chat (Slack / Teams — watched channels) - Calendar (today + tomorrow) - [Domain-specific sources from the interview] ## Outputs - `Daily Notes/YYYY-MM-DD.md` with a "Top 3" header - Atomic updates to any tracked entities (contacts, deals, projects) ## Section 0 — Pre-Flight (run this before any work) 1. Read the vault-maintenance skill 2. Read this methodology file 3. Check `Task Todos.md` for items tagged to this routine 4. Read-before-write any file you will touch 5. Confirm source connectors are authenticated ## Hard Bans - **BAN-001:** Never skip the daily note, even if all sources fail. An empty note with "all sources unavailable" is better than no note. - **BAN-002:** Never change a tracked entity's status without ≥2 independent sources. ## Execution Steps 1. Crawl each source in priority order (highest-signal first) 2. Synthesize into `Daily Notes/YYYY-MM-DD.md`, leading with Top 3 3. Update any tracked entity files that changed 4. Verify the daily note exists on disk (`ls` the file) 5. Log this run to the Run Log below ## Pre-Flight Checklist (before marking run complete) - [ ] Daily note exists on disk - [ ] Top 3 header is populated (or explicitly "quiet day") - [ ] No source failed silently (each source has a status line) ## Best Practices (Empty — these accrete from run experience. Tag each with the run number.) ## Anti-Patterns (Empty — these accrete from failures. Tag each with the run number.) ## Cross-Task Dependencies - **Provides to:** synthesis, janitor, all domain routines - **Receives from:** nothing (this is the first routine in the chain) ## Run Log ``` ### Example prompt skeleton This is what the scheduled task's prompt looks like. The first four actions are always the same; the rest are domain-specific. Adapt the body for each routine. ``` You are the daily crawler for [vault name]. Step 1: Read the vault-maintenance skill at `Pipeline/vault-maintenance-skill.md`. Step 2: Read your methodology file at `Pipeline/Routines/crawler-methodology.md`. Step 3: Check `Pipeline/Task Todos.md` for items tagged `crawler`. Step 4: Read `Daily Notes/` to check for today's note (read-before-write). Step 5: Crawl [source 1 — e.g. "the last 24h of Gmail"]. Extract signals. Step 6: Crawl [source 2 — e.g. "Slack channels #general, #support"]. Extract signals. Step 7: Crawl [source 3 — e.g. "Google Calendar for today + tomorrow"]. Step 8: Synthesize into `Daily Notes/YYYY-MM-DD.md`. - Lead with "## Top 3" — the three most important signals. - One section per source, newest-first. - Produce the note even if a source fails — partial data > no data. Step 9: Update any tracked entity files that changed. Step 10: Verify the daily note exists on disk. Step 11: DM the person ONLY if a Top 3 item needs action before tomorrow. Step 12: Append a run block to your methodology file's Run Log. ``` ### Adapting the skeleton for a domain routine A domain routine's body replaces the crawl steps with domain-specific work. The preamble (Steps 1–4) never changes. Here is how a site-maintainer's body differs: ``` [Steps 1-4: identical preamble — read skill, methodology, todos, read-before-write] Step 5: Read the improvement backlog for the highest-priority unshipped item. Step 6: Read the site repo (git log, changed files) for current state. Step 7: Read the canonical bio source for any factual claim you will touch. Step 8: Draft one improvement. Write a dated draft file describing the exact change. Step 9: Apply the change to a local preview branch. Never push to production. Step 10: Screenshot the rendered result (full-page + per-section). Look at it. Step 11: DM the person with: what changed, a link to the draft file, "approve to deploy." Step 12: Update the backlog (move the item to "In Draft") and the changelog. Step 13: Append a run block to your methodology file's Run Log. ``` The shape is the same: read context → do work → verify → report → log. The content is different because the domain is different. ### Example domain methodology file — competitive / market intel scan A second worked example, this time for a domain routine rather than a core routine. Compare the structure to the crawler example above — same skeleton, different domain logic. ```markdown --- title: Competitive Intel Scan Methodology created: 2026-01-20 updated: 2026-01-20 runs_analyzed: 0 task_id: nightly-competitive-scan schedule: "0 3 * * *" --- ## Purpose Surface what competitors and the broader market said or shipped in the last 24 hours. Pair the social scan with direct product/pricing page fetches — social scans are structurally blind to off-platform releases and pricing moves. ## Inputs - Social feed searches (watchlist of competitor handles + industry keywords) - Direct fetch of each competitor's product page, pricing page, changelog - The person's meeting calendar (pre-meeting counterparty scan) ## Outputs - A dated scan file with Top 3 findings and deep-link URLs to each source - Seed topics for the content-ideation routine - Insights routed to the journal/synthesis ## Section 0 — Pre-Flight 1. Read the vault-maintenance skill 2. Read this methodology file 3. Check `Task Todos.md` for items tagged to this routine 4. Read the prior scan file (read-before-write) 5. Read the query-effectiveness ranking (prune dead queries) ## Hard Bans - **BAN-001:** Every finding must carry a clickable deep-link. A summary the person cannot click through to is not actionable. - **BAN-002:** Never manufacture a finding on a quiet day. A quiet day correctly produces a short receipt: "scanned N sources, nothing material." - **BAN-003:** Never re-use a carried deal-status or win-loss claim without re-verifying it against the live pipeline source this run. ## Execution Steps 1. Run watchlist searches (from:handle queries for each competitor) 2. Run product-name-pattern searches (catches launches from staff handles that the corp-handle sweep misses) 3. Directly fetch each competitor's product page, pricing page, changelog 4. Check the person's calendar for upcoming meetings; run a pre-meeting counterparty scan for any meeting in the next 48h 5. Synthesize into a dated scan file, leading with Top 3 6. Route seed topics to the content-ideation backlog 7. Verify the scan file exists on disk 8. DM the person ONLY if a Top 3 item is time-sensitive 9. Update the query-effectiveness ranking 10. Append a run block to the Run Log below ## Pre-Flight Checklist (before marking run complete) - [ ] Scan file exists on disk with deep-link URLs - [ ] Every competitor in the watchlist was checked (or explicitly marked "source unavailable" — never silently skip) - [ ] No carried deal-status was re-quoted without re-verification - [ ] Quiet day = short receipt, not manufactured content ## Best Practices (Accrete from runs. Examples of what typically lands here:) - "A `from:author keyword OR keyword` query silently degrades to generic noise — parenthesize the OR-group or go direct-profile." (Run N) - "A confirmed silence from a high-signal source is a finding, not a wasted query — log the null as a positive signal." (Run N) ## Anti-Patterns - Trusting the social scan alone for off-platform launches - Repeating the same null query shape 3+ runs instead of changing the query - Re-quoting a carried deal status without checking the live source - Padding quiet days with filler ## Cross-Task Dependencies - **Provides to:** synthesis/journal (Top 3), content-ideation (seed topics) - **Receives from:** crawler (meeting calendar, counterparty context) ## Run Log ``` Notice how the domain methodology differs from the crawler: it has domain-specific hard bans (deep-links, no manufactured content, re-verify deal status), a query-effectiveness ranking as an input, and it routes outputs to two downstream routines. The Section 0 / Hard Bans / Pre-Flight / Run Log skeleton is identical. --- ## The system components The phases tell you what to build. This section describes the subsystems that make a grown pipeline hold together — the parts that are invisible at five routines & load-bearing at forty. **When to build each one:** | Subsystem | Build at | Why not earlier | |---|---|---| | Data flow graph (#1) | Day 1 | Retrofitting edges into a grown pipeline is expensive | | Methodology skeleton (#2) | Day 1 | Every routine needs one from birth | | Governance document (#12) | Day 1 | Every routine reads it first | | Tool harmonization (#4) | ~8 routines | Below 8 you notice drift yourself | | Self-improving prompts (#3) | ~10 routines | Needs eval labels from a scoring routine | | The four request modes (#5) | First human reply | Classify from day one, formalize at ~5 routines | | Contradiction detection (#6) | ~30 days of notes | Needs a corpus to argue against | | Cross-agent review (#7) | First code MR | Only for vaults that produce code | | Convergence tracking (#9) | When the thesis matters | Only if you are building an argument | | Model migration (#10) | ≥2 routines + a model upgrade | Before that there is nothing to migrate | | Anti-slop layer (#11) | First content draft | Start with 5 tells, grow to 50 | | Schedule-as-code | ~8 routines | Below 8 you can re-arm by hand | The first four are substrate. The rest activate when the pipeline earns them. ### 1. The pipeline is a fan-in graph, not a list of jobs At maturity you are running dozens of scheduled tasks against one methodology file each: mostly daily, some weekly, one or two monthly, plus event-triggered handlers & on-demand sessions triggered by a command. They are not independent: ``` producers (repo scanners, market scans, trackers, monitors) ─┐ the crawler (all services -> one dated note) ────────────────┤ the janitor (links, dashboard, log rotation) ────────────────┼─> synthesis -> loop-closer research / content / intel lanes ────────────────────────────┤ (the brief (human the meta-review (scores + todos) ────────────────────────────┘ they read) judgment) loop-closer -> corrections propagate to every file meta-review -> todos propagate to every routine ``` Two rules only reveal themselves at scale. **Declare the edges in the governance doc** — every routine states which routines feed it & which it feeds, because without that, reordering a schedule silently inverts a dependency and *nothing goes red*. And **the schedule you documented is not the schedule that runs**, so reconcile the governance table against the live scheduler registry on a cadence. A pipeline can run for weeks with most of its routines firing hours off their documented slots, long enough to invert the fan-in order, with every check green. ### 2. Methodology file anatomy One file per routine. This is the moat: the model improves on its own, but the accumulated per-routine rules are what make *your* pipeline good. The section order that survived: 1. **Purpose.** One paragraph. What this solves that nothing else covers. 2. **Inputs / Outputs.** Every file read, every file written, every channel posted to. 3. **Section 0: brief inference.** Before producing anything, the routine answers three questions in writing: what changed since my last run · what is the single most important thing this run · what should I **not** do. This exists to defeat default-mode generation, where the agent skips the read & falls back to the statistical centre of "what an update looks like." Cheapest quality intervention in the file. 4. **Execution steps.** Numbered, imperative, each with its verification. 5. **Hard bans.** Named, numbered, absolute. Not "try to avoid" — **never**. Soft guidance gets ignored by agents; absolute prohibitions work. Each ban records the run that caused it, so nobody relitigates a settled failure. A ban is how a one-time correction becomes permanent, and a mature content routine carries dozens. 6. **Pre-flight checklist.** A box-by-box verification before output ships. Structured self-review as a primitive, not a vibe. 7. **Best practices & anti-patterns**, each tagged with the run number that produced it. 8. **Cross-task dependencies.** Receives from · provides to. 9. **Run log**, newest at top, one block per run. **Rotate it.** These files reach hundreds of kilobytes & then a routine silently reads a truncated view of its own rules & misses one. Carry the newest handful, archive the rest, & write the threshold into the header. ### 3. Self-improving prompts Routines that grade their own output & rewrite their own prompts from the score. Four parts: 1. **The grader scores every routine** against a fixed rubric, from evidence: did the artifact land, was it acted on, did it repeat itself, did it produce a decision. 2. **Each routine appends its own learnings** to its methodology file at end of run — a new best practice, a new anti-pattern, or a new hard ban if the failure was one an instruction could have prevented. 3. **The scores become eval labels.** That is the optimizer wiring: scorecards feed the prompt optimizer, which produces numbered variants, & a live A/B runs *inside* the routine — version A against version B, both delivered, with a one-tap vote. Winner promoted, loser retired, everything logged. 4. **The loop-closer closes it.** The vote & any corrections re-enter as human judgment. The rule that keeps this safe: a routine may rewrite its **own** methodology file & may *propose* changes to another's, but never silently edit one. Guard the obvious failure: an eval loop that never captures a label is pure overhead. Audit that the instrument actually measures, not merely that it runs. An A/B that collects zero votes for forty runs is spending real compute to manufacture confidence. ### 4. Tool harmonization Every routine eventually reimplements message posting, file access & frontmatter slightly differently, & then a fix in one place propagates nowhere. The canonical-patterns repo pins the one pattern per tool, each with its provenance & a copy-pasteable example. A daily auditor reads every methodology file & checks whether it references the canonical patterns, whether it has a section 0, hard bans & a pre-flight checklist, & whether it follows the canonical frontmatter. Files created in the last 24 hours get flagged specially, because that is where drift enters. Crucially it **proposes, it does not apply.** Deviations go to an audit log with routine · tool · issue · canonical · fix · status, a fragmentation map records who uses what & a convergence number turns the whole thing into one figure that should go up. Build this once about eight routines share a tooling layer. ### 5. Classifying a human reply: modes, then dispositions The human replies to the brief in prose, & prose is ambiguous. Before acting on any reply, classify it into exactly one of four modes. The mode decides what is permitted & how far scope may extend. | Mode | Triggers | Action | Scope | |---|---|---|---| | **CORRECT** | "this is wrong", "change X to Y", "the number is actually Z", "kill it", name & number fixes | Apply the specific fix to the named files. Two corrections in the same direction become a decision record. A mistake the pipeline keeps making becomes a **new named hard ban**. | **Minimal.** Only what was said. "Fix the number in that file" means that number in that file, not everywhere. | | **ROUTE** | "this belongs in X", "tell so-and-so", "add this to the other update", or any directive outside this routine's charter | Move the signal: create or escalate a todo carrying the **verbatim** framing & the source timestamp. Multi-clause directives get the quote *and* a numbered decomposition. If no routine owns the topic, log a coverage gap. | **Move, don't transform.** Never paraphrase, never execute the routed work — the owning lane does. | | **ACKNOWLEDGE** | a thumbs-up, "got it", "thanks", "ok", emoji only, **or silence** | Log it. Nothing else. | **None.** Confirmation is not correction. "Got it" is not permission to expand, refine or proliferate. | | **IGNORE** | "not relevant", "skip this", "stop tracking this", "drop it" | Archive immediately. Write a decision record if the pattern is worth remembering. | **Remove, don't transform.** An IGNORE is terminal: do not re-raise it, do not add caveats, do not create a watch item. | Four bans make the modes real, & each exists because the lane broke it once. Never expand a CORRECT beyond the stated scope. Never create changes from an ACKNOWLEDGE. **Never treat silence as a CORRECT** — silence is an ACKNOWLEDGE & the item stays open, not approved. Never argue with an IGNORE. **The mode is only the first axis.** Once you know how much authority a reply carries, route it by what it *is*: a factual correction applies immediately & atomically across every file carrying the stale value · a content disposition routes to the publishing lane · a strategic context delta updates the governing artifact & propagates · an approval or decline routes back to the routine that asked · a slash-prefixed message dispatches to an on-demand session · and a policy ruling updates the governance document, which is the one case where a reply edits the constitution. Two gates decide whether a message belongs to this lane at all: **signal shape** (is it human-authored, with no automation footer?) & **content class** (is it one of the types above?). A bare link drop passes the first gate & fails the second — it is an ingest signal owned by the intel lane, not a correction. Two more jobs belong in the same lane. A **command dispatcher**, so a message beginning with a slash keyword launches an on-demand session instead of being read as feedback. And ownership of the **anti-tell library**, because when a correction reveals a voice problem rather than a fact problem, that is a new tell rather than a new ban. ### 6. Contradiction detection A second brain that only remembers is a filing cabinet. The layer worth building sits on top: the vault red-teams your current position against your own history. Three passes, cheapest first. **Emergence.** Scan the last 30 days of dated notes & name the pattern that was never named. The canonical example: the same friction appearing in four separate projects without ever being called a systemic problem. **Contradiction.** Surface where the vault now asserts two incompatible things. In practice most of these come from a reversal — a rule changed & files written under the old rule still assert it. **Ghost self.** A temporal baseline. Confront a current claim with what the vault said 90 days ago & make the delta explicit. The rule that makes repair actually work: **repair the authority the stale files cite, not just the files.** Grep for what those files name as their *source* & fix the root first, or the next routine to follow that pointer regenerates the error, freshly worded, & every check reports clean. And the trap that comes with it: **several routines agreeing is not several sources.** In a fan-in pipeline every downstream task reads the same upstream note, so agreement is the default rather than evidence. Collapse each "source" to its origin datum & count those. Three routines re-quoting one meeting line is one source. An out-of-office entry, a commit gap & a status change is three. ### 7. Cross-agent review When a routine opens a merge request, a **second, independent** session reviews it before a human is assigned. The implementing session wrote the code, so it reads past its own mistakes. Use it for large diffs, security-sensitive changes, anything customer-facing & any change to the pipeline engine. Skip trivial fixes & dependency bumps. The reviewer reads the reasoning trace **first**, then the diff, checking logic errors, missing edge cases on error paths, security, performance, style against existing patterns, test coverage on failure paths & trace-versus-code alignment: does the code do what the trace says it does? Three bans. Never merge — that is a human decision. Never edit the code — comment only, the implementing session fixes. Never skip the trace, because without it the reviewer cannot tell an intentional decision from an oversight. And never auto-approve silently: "reviewed N files, M tests, no issues found" is itself the output. It supplements rather than replaces the stack: automated static analysis, then cross-agent review, then human judgment & merge. ### 8. Reasoning traces committed with the code Every merge request a routine opens carries a trace file **committed alongside the code**, not pasted into the description, so it survives in the repo & travels with the diff. Four fixed sections: the prompt, summarized · the key decisions · the files read before writing · why each change was made. The reviewer, human or agent, then gets the reasoning rather than only the diff — which is the only thing that distinguishes a deliberate trade-off from a mistake. ### 9. Convergence tracking Maintain one living file recording where **independent external sources converge on the claim your architecture bets on.** In this system that claim is: > the durable advantage is encoded domain knowledge as infrastructure, not the model itself. It started as a five-source table & is now more than ten independent sources, spanning a platform lead at a model vendor, a company-operating-system pattern from a chief product officer, a proactive-agents essay, a production agentic-infrastructure blueprint, the self-arguing-vault project, an enterprise knowledge-base teardown, a recursive self-improving agent harness, a managed-agents talk, an agentic-trust metadata standard, a sandbox-architecture argument & a forward-deployed-engineering playbook. Each carries a full reading note & a link to a primary. It earns its place for three reasons. It is the **design rationale** for the whole pipeline in one line: the moat is the accumulated methodology files & configs, not the shared model. It is directly reusable in a strategy memo or a hiring conversation, because convergence from many independent vantage points is much harder to argue with than one opinion. And **the discipline it demands is the point** — every source must be traced to a primary before it counts, & the count must be honest, since correlated commentary on one event is one source rather than three. This file has dropped entries that failed verification, including one that turned out not to resolve to any real person, & that is the file working correctly. ### 10. Model migration A long-lived pipeline outlives its model. New families ship every few months & a routine tuned to one model's prompting paradigm can degrade silently under another. Treat model choice as governed infrastructure. **An assignment table in the governance doc**, one row per routine: routine · model · variant file. It is the single place anyone checks what they are running on. **Per-routine variant files** that *layer over* the parent methodology rather than replacing it, so a routine on a non-default model reads both. **Tiered migration** — move a few routines first, A/B them, then the rest, never all at once. **A migration handler**, event-triggered on model-change detection, always performed by the newest model available. And **reversibility as a first-class requirement**, which is the part people skip. When an allocation ran out, this system rolled every routine back in one edit: variant files preserved but marked inactive, plus an explicit override telling every routine to read its parent methodology only. Rollback was a table edit & one paragraph, not forty file rewrites. ### 11. The anti-slop layer Two distinct quality problems, two distinct mechanisms. Do not merge them. **Hard bans** prevent factual & procedural errors. They live in the owning methodology file & are the enforcement mechanism. **Tells** prevent voice & tone errors — the patterns that make output read as though an assistant wrote it. They live in one central versioned library that every content-producing routine references **by ID** rather than duplicating inline. Each entry carries a name, a *bad* example of what the model produces, a *good* example of what the person would actually write, a pointer to any ban it overlaps & the routines it applies to. Starting at roughly fifty tells across your handful of output surfaces is a realistic first version. The primitives worth stealing wholesale: hard bans over soft guidance · brief inference before generation · pre-flight checklists · a few numeric dials that cascade through downstream rules, giving flexible-but-bounded behaviour without a file per variation · design locks, decisions that cannot be reversed mid-output · model-specific variants, because different models have different failure modes · and anti-tell detection, which moves the bar from "does it work" to "can you tell a model made it." Ownership: the loop-closer creates new tells from the human's corrections, the grader tracks compliance. **Where new tells come from, & the gate they must pass.** Two good public sources to watch are [humanizer](https://github.com/blader/humanizer) & [stop-slop](https://github.com/hardikpandya/stop-slop); [TasteSkill](https://www.tasteskill.dev/) is the framework the primitives above come from. Clone the ones you want, then run a low-frequency scan — once a week, off-hours — that diffs each clone against the SHA you last looked at & tests any genuinely-novel pattern against your own recent output before it is allowed anywhere near the library. **No A/B evidence, no admission.** The gate matters more than the sources: these repos target generic machine-written prose, so once your output is cleaner than their target, the marginal upstream rule is likelier to over-fire & strip a real voice than to catch anything. Record every rejection with its evidence, keep a permanent-reject list for rules the person has already overruled, & never reuse a retired tell ID. Most weeks admit nothing, and that is the expected outcome rather than a failed run. The full reasoning is under *What is expensive to learn the hard way*. ### 12. The governance document One file at the vault root that **every routine & every interactive session reads first.** It is not documentation, it is the executable constitution, & its instructions override default behaviour. What it must contain: 1. **About this vault** — purpose, the person's role & context. 2. **Structure** — the full folder map as a tree. 3. **Critical context** — the facts every routine depends on: identifiers, paths, timezone, the strategic priorities. 4. **The pipeline table** — time · routine · purpose · key outputs, plus the data-flow diagram. 5. **Writing & style rules** — voice, which skill to load for content, & any what-may-be-said-publicly ruling, recorded with the verbatim decision & a citable timestamp, plus an explicit **scope** paragraph. Permission to name something is not permission to describe everything about it, & the scope paragraph is what stops that slide. 6. **Verification rules** — for example, never sign off on a rendered page by reading the markup; render it & look at screenshots, per-section as well as full-page. 7. **The methodology file list**, one line per routine. 8. **Model assignment**, including any active override. 9. **Numbered constraints for all tasks** — read the maintenance skill first · partial data beats no data · link everything · read before writing · do not overwrite another task's work · log every run · update your methodology · implement your todos · check your model assignment · commit a reasoning trace with code. Three properties make it work in practice. **Decisions are recorded with their evidence** — a reversal names what it supersedes, quotes the decision verbatim & carries a citable timestamp, so no routine relitigates it & no stale file can claim authority. **It is layered** — durable principles, evolving facts, ephemeral overrides — kept small enough to read every run & mechanically editable. And **it is the interview's output**: everything in critical context comes straight from the interview, which is what makes the document theirs rather than a copy of someone else's. ### 13. The maintenance skill The governance document is the constitution. The maintenance skill is the building code, & it is the one piece most often written and never installed. It defines the folder structure with allowed content types · the **ownership table** recording which routines may write to which folders, so routines stop clobbering each other's territory · naming conventions for files, folders, links & frontmatter · log-rotation thresholds per log type · the janitor's standing tidiness checklist · and any confidentiality exclusions, enforced at the **name and topic level** rather than only by folder, because a folder rule cannot reach a routine that names the topic somewhere else. The cardinal lesson is dull & expensive: **writing the rules into a markdown file is not the same as installing them as something routines can actually load.** A single source of truth for where files go is worthless if nothing can read it, & a pipeline will happily run for weeks on stale assumptions while the correct rules sit in a file nobody loads. ### 14. Treat the schedule as code Scheduler state is a runtime artifact by default, which means it is invisible, unversioned & one bad afternoon from being unrecoverable. Three practices fix that. **A committed manifest** recording every routine's canonical schedule expression & enabled state. It is the documented recovery move after any scheduler disturbance: one task that re-asserts the whole schedule, verifies by listing it back, then disables itself. **Reconciliation between the document & the registry** — a standing check that diffs the governance table against what is actually registered. This catches the most insidious failure in the whole system, because it is the one with **no liveness signature at all**: every routine fires, every artifact lands, every check is green, & the dependency order is quietly inverted. It can persist for months. **Registry inspection when a keystone goes dark** — check its registration (enabled state, schedule expression, last run) *before* debugging the machine. A one-time schedule that already fired looks identical, from the output folder alone, to a crashed recurring routine, & the two need opposite fixes. --- ## What is expensive to learn the hard way These are the non-obvious ones. Most cost real downtime to discover. **A pipeline of pure detection notices everything & improves nothing — and it passes every gate in this document while doing so.** This is the one lesson here that came from a *second* vault, built from this kit by someone who did not write it, which makes it the only evidence of how these instructions perform in a stranger's hands. That bootstrap was done correctly: interview run in full, synthesis written & confirmed, skips justified, watchdog built first, core routines honestly scoped down. Three capability gaps shipped anyway, and in each case the *person* found the gap, not the system. Nothing deepened the knowledge base — routines maintained it, verified its figures & hunted opportunities against it, but none made it better, so the vault's substantive content stayed exactly as good as the day it was written. Nothing proposed new routines — two backlogs existed & neither tracked *"this system cannot yet do X."* Nothing reviewed the architecture — the janitor checked links, frontmatter & orphans, and never asked whether the information architecture was still *right*. **The reason this is structural rather than one builder's oversight:** detection is easy to specify, easy to gate & produces visible output on day one; improvement is hard to specify & its value compounds slowly. So detection gets built first, **and then the pipeline feels complete.** It is not, and no check in this document could tell you — every gate is green, output lands daily, the watchdog is silent. Four causes, all of them defects in *this document* rather than in that build. (a) *"Skip aggressively" had no floor:* the instruction is correct & stays, but it is one-directional — it says what to cut and never what may not be cut, so the layer whose value compounds slowest is always the first thing cut on build day. (b) *The proposal function was welded to the scoring function:* small vaults correctly skip the scoring engine and lost the proposal function with it, though noticing a missing capability has no size threshold at all. (c) *Tidiness & architecture were one routine,* both described as vault-hygiene work — so a builder scoping down merges them & implements only the hygiene half, because that is the half with obvious mechanical checks. (d) *The learning-goals interview question produced an answer that changed nothing* — precisely, its forcing function pointed at the **person** (a training routine) and never at the **vault's own content**. The sharpest instance was the minimum-vault list in this very document, and the report did not even name it: crawler + synthesis, both detection. **The rule: at least one routine must make the vault better rather than merely current; name it at the gate into Phase 3 rather than leaving it to Phase 3's optional list; and if you skip it, write the sentence.** "The person will notice" is not a plan — it is the failure mode. **Detection without a paired write permission manufactures unactionable findings.** A vault set its knowledge folder read-only to every routine. This is defensible & it is the default most builders reach for: human-authored content should not drift under automation. It failed inside a day. A routine verified figures against a primary source, found a note asserting a superseded value, and **could not fix it** — so it filed a correct report about an error it had itself identified, and the error stayed live. The permission boundary did not prevent a bad write; it converted a good write into a backlog item. The signature is worth memorizing because nothing looks broken: **the reports are all correct.** The routine runs, finds real problems & writes accurate reports. The defect shows up only in the ratio of findings *raised* to findings *closed*, which nobody watches on day one. Build-step rule: for every folder, name what may read it, what may write it, and — if those sets differ — what closes the findings the readers produce. "The person does" is a legitimate answer, but it must be a decision, and it should be sized: three findings a week is fine, thirty is a design error. **Amended: that sizing test is necessary & nowhere near sufficient.** Sizing by *volume* silently licenses the worst case in this family — a single finding, correctly detected, correctly routed, and open indefinitely because the party who must close it has no clock. When the closer is the person, the item also needs a stated maximum age & a named consequence at expiry, sized by consequence per elapsed day rather than by count. See *Two correctly-scoped owners can deadlock on the same finding* below, which also covers the two-lane variant this entry does not reach at all: the closer resolving to *another routine* that is itself correctly barred from acting, so both sides log a correct deferral & the item reads as handled from everywhere. **Applying a settled decision is safe; making one is not.** This is the fix for the entry above, and it needs stating separately because the obvious repair — just grant write access — trades an un-closable finding for something worse: a routine quietly rewriting conclusions nobody asked it to revisit. Automated drift in human-authored content is far harder to detect than an unfixed finding, because it leaves no report at all. Both blanket settings are wrong. The distinction that resolves it is not *how much* a routine may write but *what kind of act* the write is. **Propagating a decision the vault has already made** needs no authority — the decision exists — and is safe to automate: a figure was corrected in the canonical table, six notes still cite the old one, fix the six. **Deciding which of two conflicting claims is right** is adjudication, and it belongs to the person: two notes disagree, no canonical source settles it, **surface it**. The paired shape that worked in the field: one routine may *deepen and cite* — never delete, never introduce a figure outside the single-source table, never soften a warning without a contradicting primary source; a second may *propagate settled corrections* — never adjudicate. Both are narrow, both can write, neither can quietly change what the vault believes. This is also mechanically checkable in a prompt, which matters — "don't rewrite conclusions" is unenforceable, whereas "point at the canonical decision you are applying, or stop" is a precondition the routine can state & fail. **A vault that corrects itself needs something that checks itself against itself.** A correction landed correctly in the register. Six notes kept asserting the superseded version. No routine was at fault — each did its job — and the register was right the whole time. **Nobody owned the copying.** The most dangerous state for a knowledge vault is not being wrong; it is being **wrong in one place & right in another**, because the reader has no way to tell which to trust and both look equally authoritative. A uniformly wrong vault gets corrected the moment anyone notices; a half-corrected one teaches its readers that the vault cannot be trusted, which is slower & far more expensive. The counter-intuitive part: **detection routines make this worse, not better.** Every correction the detection layer finds creates a new propagation surface, so a vault that corrects itself vigorously & propagates nothing accumulates contradictions in direct proportion to how well its detection works. Note how this differs from *repair the authority the stale files cite*, further down: that remedy assumes the stale files **name a source** you can grep for & fix at the root, which is the tractable case. This is the harder one — notes asserting a fact with no cited authority at all, which no root-repair can reach because there is no pointer to follow. The gap is **ownership**: propagation is unowned work that every routine is individually blameless for skipping. When you build anything that issues corrections, name in the same breath what propagates them. The check itself is cheap — after a correction, search the corpus for the *superseded* value's assertion and list every surface still carrying it. The expensive part was never the search; it was that no routine's charter said the search was its job. **"Approved" is not "shipped" & "fired" is not "delivered."** Routines get proposed, reviewed, marked approved & never created. Verify the scheduled task exists and has produced one real output before calling it done. Gate every status claim, both the failures and the green ticks, behind an actual check. **When you move folders, migrate every consumer in the same commit.** Renaming structure without migrating the routines that hard-coded the old paths silently kills the pipeline. **Config drift outlives the fix.** Reconcile each routine's read and write paths against reality on a schedule, not once. **The schedule you documented is not the schedule that runs.** Diff the governance doc's schedule table against the live scheduler registry on a cadence. This failure has no liveness signature at all. Every routine fires, every artifact lands, every check is green & the dependency order is quietly inverted. If a consumer chronically reports its upstream as stale, check the registered fire order of the pair *before* debugging the producer. **Liveness must look backward & from outside.** Forward checks cannot see a routine that simply did not run: it writes nothing and logs nothing. Give each routine a check that confirms its own prior run produced its artifact. And put at least one sentinel *outside* the system, because a watchdog that shares the substrate dies alongside what it watches. **Silence and absence are data.** An empty stage, a quiet contact, a stale input are findings, not reasons to skip. A quiet day correctly produces a short receipt, not manufactured content. **Force-rank and cap every output.** Top three, top five, escalations only. The file holds detail. The message carries the single highest-leverage item. Over-listing destroys signal. **Specific asks beat open questions.** Frame every decision request with a falsifiable default and a one-tap answer. Open questions get ignored. Make the human's approval step one action, not an editorial sub-task. **Match cadence to real engagement.** A daily routine the person ignores six days out of seven should fire less often, not louder. **Methodology files are the moat, but a moat you cannot read is no moat.** The model improves on its own. The accumulated per-routine practices are what make *this* vault good. They also grow past the read limit, at which point a routine reads a truncated view of its own rules and silently misses one. Rotate them like any other log. **A file-verified tick can still be a fossil.** Verification catches "did this run land," never "is the fact still true." Re-ground any load-bearing, multi-cycle-old claim against its live source before repeating it. Re-ground, do not increment. **Agreement between routines is not corroboration.** In a fan-in pipeline every downstream task reads the same upstream note, so several routines agreeing may be one source wearing several hats. Trace each "source" back to its origin datum before treating consensus as evidence. **Re-stating a claim is not re-verifying it.** Before inheriting a classification a prior run of your own routine made, ask whether it was ever independently derived or only ever cited forward. A field you already log every cycle will often falsify it if you look at the trend instead of the latest value. **The false-clean family.** A check that looks like rigor while being structurally blind: - a pattern that can never match what it searches for - an instrument that captures no signal at all, spending real compute to manufacture confidence - an instrument that measures the wrong quantity, so a rising count is the healthy shape and it goes quiet on the one thing that is broken - an instrument that measures the right quantity correctly, over a fraction of the surface it claims to cover The last is the most dangerous, because sound partitioning is what stops anyone re-deriving the pattern. For any compliance sweep, read how the governed files *actually phrase* the obligation (abbreviations, internal pointers, euphemisms, category descriptions naming nothing) & derive the pattern from that, never from how the rule was originally worded. Every run should be able to answer: what phrasings can this pattern not see? **A detector's watch-set must be monotonic.** A probe universe re-derived from scratch each run can silently shrink & "nothing found" from a narrowed universe is indistinguishable from a true negative. A bigger set is not a superset: check set inclusion against the prior run, item by item & make every removal cost a logged reason. **A guard you read is not a guard you run.** A self-policing rule (compliance is the act you are already taking) can live in shared canon. A *reciprocal* rule, one demanding a second separate write against another object, must be embedded in the actor that performs the write, or it is decoration that every routine reads and none executes. **Repair the authority, not just the symptoms.** Before fixing a set of stale assertions, grep for what those files name as their *source* & fix the root first. Otherwise the next routine to follow that pointer regenerates the error, freshly worded & every check reports clean. **Anything that publishes numbers others consume needs an inbound correction channel.** The moment one routine's output becomes another's ground truth, independence without a correction path is not rigor, it is un-auditability: the only party holding the disproving evidence may be the one party barred from acting on it. Corrections should flow in as data the owner adjudicates, never as edits to someone else's score. **A long-lived pipeline outlives its model.** Treat model choice as governed infrastructure: an assignment table in the governance doc, per-routine variant files layered over the parent methodology & a migration routine that moves in tiers rather than all at once. **Past a handful of routines, authoring itself becomes a source of drift.** A central rule cannot govern routines that do not exist yet. Add standing convergence auditors that check each *new* artifact against the canon at the moment it appears & have them log or propose, never silently rewrite another routine's instructions. **Retiring a routine is a multi-surface operation, & the deferrals pointing at it are the surface everyone forgets.** Every other failure here is a check that misses something real. This one is work that quietly stops being done because a *reference* outlived the thing it referenced. In the source pipeline an investor-follow-up lane was built, ran once & was abandoned; months later its methodology was archived — file moved, job done. But a *live* weekly customer-triage lane still carried, in its own prompt, a mutual-exclusion step: *skip the customers the follow-up lane covers, don't double-flag.* That lane no longer existed anywhere in the scheduler. So an entire customer segment was skipped by the only routine that would have triaged it, & the skipping routine **reported clean every week**, because from its own point of view it was correctly deduplicating. Notice what makes this invisible to everything else on this page: no error, no gap, no stale claim. A *correct* instruction pointing at a *dead* target. **Retirement is four surfaces: archive the file · repoint every index row at the archive with an explicit RETIRED marker · deregister the scheduled task & verify it is gone · grep every live prompt for routines that DEFER to this one, then delete each deferral or name who inherits the work.** The last is the only step about *work* rather than *files*, which is why it is the one that gets skipped — and it is invisible in a changelog, where "archived three dead methodologies" reads complete. **There is a fifth surface, & it is the one you are reading.** Any document that *recommends* the routine to someone else outlives the retirement too — and if that document has a derived copy (a published edition, an onboarding doc, a template repo), the correction has to reach the derived copy or it reaches nobody who matters. This document failed exactly that test: three routine classes were marked retired in its internal source & the marks did not travel here for four days, so the only edition a stranger can actually read went on recommending all three. The internal fix felt complete because the internal file was correct. **A correction to a document with a derived edition is not done when the source is right; it is done when the derived edition is right** — and if the two are maintained by different owners or different cadences, that gap is a deadlock waiting to happen, which is the entry two below this one. **A named-but-incapable owner is worse than no owner, because it reads as handled & ends the search.** The general form of the failure above. An unowned item stays visibly open & keeps getting re-flagged; the moment someone writes a disposition naming an owner, it converts to apparently-closed & everyone stops looking. So validate that the named owner **exists & is in a state that can discharge the work**. The sharpest version: when you defer a known defect to a *successor* file or a next version, grep that successor for the exact defect you are deferring before you write the disposition. The source pipeline deferred a defect flagged nine separate times to a successor that carried the identical defect verbatim. **A correct, populated instrument with no assigned reader is still a blind spot.** Track a `runs_analyzed` counter & a dated run log per routine and dormancy is, as every guide will tell you, visible at a glance. In the source pipeline it was — and three dead routines sat in the *live* routine folder for about three and a half months, counted as healthy by every census that swept it. The instrument was never wrong & never read, because no routine was obligated to read it. Give dormancy review an owner & a cadence, or the counter is decoration. And before you reap anything, separate the three zero-run cases, because the same zero covers all of them: a genuinely dead lane · an on-demand command legitimately awaiting its first trigger · a cross-cutting helper that has no runs *by design* & never will. The discriminator is the routine's declared trigger, not its count. Reaping on the count alone destroys working shared infrastructure. **An upstream best-practice source is authoritative about its target, not about yours.** Sooner or later you will point your vault at an external quality framework — a style guide, an anti-slop library, a linting ruleset, a security benchmark. The failure mode is not missing an upstream improvement. It is adopting a rule that is correct in general & wrong for you, because it was written against a target population your output has already outgrown. A baseline pass over two public anti-slop repos tested seven candidate rules & admitted two. Three of the five rejected would have actively damaged the writing they were meant to improve: they were built to catch generic machine-written prose, and against a corpus that had already cleared that bar the marginal rule stopped catching defects & started removing the voice. So make the evidence gate a hard ban rather than a preference — nothing enters your house ruleset without an A/B test against *recent, real* output. Never the upstream project's own examples, which are selected to demonstrate the rule & are therefore advocacy rather than evidence. Never invented sample text. Never the persuasiveness of the argument. Three rules follow from that. Admit at the scope where it scored positive & document every surface it hurt as an explicit exclusion, because **scope is usually the finding** and a global default silently converts a narrow win into a broad regression. Treat *zero instances found* as UNTESTED, never as a pass — a rule that never fires on real output has avoided measurement, not survived it. And keep rejections as first-class output with their evidence attached, plus a permanent-reject list for rules you have already overruled, so an upstream restatement cannot quietly reopen a settled decision. The counter-intuitive part: **a scan that admits nothing is a successful run.** A watcher measured by how much it adopts will adopt. Note this is the same SHA-diff engine as the upstream-framework watcher & the opposite default — that one refreshes a derived analysis when upstream changes, which is cheap to redo; this one changes rules that will govern your own work, which is not. **A diagnosis written during an unresolved incident is a hypothesis about the future.** The most common error is predicting permanent loss from a mid-incident snapshot. An audit routine, running late after a scheduler stall, observed seven routines whose stored state showed a last-run of the previous day & a next-run of the *following* day — the current day's slot apparently skipped, with no queue, no retry & no error. It filed a blocking incident stating those seven occurrences would never run. Within roughly ninety minutes, all seven had run. The evidence was real & the detection insight was sound; the prediction was not. What makes this worth writing down is where the falsifier was: **in the same run's own output.** A separate item in the very same report documented the mechanism — that a recovering scheduler fires its backlog in a collapsed burst — which is exactly what ran those seven. Two correct findings, filed under two IDs, contradicting each other, & nothing in the process compares them. Decomposing an incident into separately-tracked items is good practice, & it is precisely what removes the surface on which the contradiction would have been visible. Three rules. Separate the observation from the prognosis *in the text* — "seven lanes show a skipped slot & a healthy-looking next-run time" is verifiable & durable, while "they will never run" is a forecast that deserves a label, a falsification time & a re-check, not the severity of the observation. Before publishing a loss claim during a live incident, apply your own other findings from the same run as falsifiers; a cheap mechanical version is to enumerate the run's findings & ask of each pair, *could A be the reason B is wrong?* And separate the claim from the ask, because severity framing survives the correction: the remedy here — an out-of-band witness, since any monitor registered inside the failing scheduler dies with it — was right whether those slots were lost or merely delayed, & the detection insight is the durable half. **A failed state whose stored representation is byte-identical to a healthy one, where a future next-run timestamp affirmatively certifies health, is worth building for regardless.** Correcting an overstated consequence must not be allowed to discredit a sound remedy. Say plainly which half moved. **Two correctly-scoped owners can deadlock on the same finding, & both sides' logs will read as compliant.** Three entries above cover findings that stall: one where nobody has standing to close a finding, one where the named owner no longer exists, one where a correction cannot travel. This is the case where **every one of those worked** — the finding was detected first-hand by two independent lanes, routed correctly & declined correctly by both — and it stayed open anyway. A document a vault publishes to the open web was found serving content its own scrub rules forbid. The lane that *authors* the document detected the leak, fixed it on disk & could not publish it: publishing belongs to the site lane, and the authoring lane is hard-banned from touching site infrastructure precisely so it cannot bypass review. The lane that *publishes* measured the live bytes failing the scrub on three consecutive runs, had the fix committed & tested, & could not ship: its gate requires the principal's approval, and a spending freeze meant shipping at all needed an override that is explicitly the principal's call. Both lanes asked, hours apart, neither knowing the other had. Neither was answered. **Nobody was wrong at any step**, and each lane's log records a *correct* deferral to the other party — which reads as handled. The diagnostic signature is the new part: **not a growing backlog, but a single item sitting in two lanes' logs as correctly deferred.** A backlog is visible & someone eventually reads it. A mutual deferral is invisible, because from inside each lane it looks exactly like the system working. A second instance, same shape at a fraction of the stakes, is what makes it a class rather than an anecdote: one stale sentence in a reference file, flagged on four consecutive runs, root-caused on the second (no registered owner claims that file as an output), and correctly routed to the janitor every time. Four correct routings, zero movement. Five rules. **Every handoff across an authority boundary carries a clock, & the clock belongs to neither party** — "awaiting approval" is a state, not a plan, so give it a stated maximum age & a named consequence at expiry. Without that, a defer is operationally indistinguishable from a drop & both parties stay individually blameless forever. > ⭐ **Corrected, & the correction is the most useful thing here — see the entry below it.** > This rule first specified the consequence at expiry as an automatic re-classification from > *deferred* to *incident* after a fixed 48 hours, reported by whichever lane noticed the age > first. That remedy was put to the principal as a single yes/no question & he answered **no** — > in five minutes, three days after this page had gone live recommending it to strangers. > **The diagnosis survives the refusal; the remedy does not.** The mechanism is untouched: a > mutual deferral really is invisible in a way a backlog is not, verified first-hand twice. What > was wrong was the *shape* of the clock. A fixed age firing automatically into an incident > spends the scarcest resource in the system — the principal's attention — on a schedule he never > agreed to, & it does so hardest on exactly the items he has already judged not worth an > interruption. **The replacement, derived from the refusal: tie the clock to the expiry of the > constraint that justified the deferral, not to a fixed age.** If a deploy is waiting on a > spending freeze that lifts on a known date, that date is the clock. Before it, the deferral is > *correct* & re-raising it is noise; after it, the stated reason is gone & the item is genuinely > stale. A constraint-expiry clock names the thing the approver is actually waiting on, cannot > fire while his own reason still holds, & degrades to the fixed-age version only when the > blocker has no known expiry. One caution: do not read a refusal as more than it was. He > declined a *standing rule*. He did not say the underlying item was fine, & inferring that from > one word would be the prognosis error two entries above. **Size the clock by consequence per elapsed day, not by count** — one finding on a page strangers read outranks thirty on an internal note. **A handoff must leave the artifact in the state the receiver's contract expects, & the sender's own methodology must name that state in the receiver's vocabulary** — one authoring lane's charter said it *"stages the change"*; it staged nothing, it edited a file in a git working tree & walked away, twice, and both times the receiving lane's pre-flight found a dirty tree & had to commit another routine's edit before it could run its own checks. The verb was doing work the action never did, and nobody noticed because the word sounded like a completed handoff. **A receiver that silently absorbs the sender's mess destroys the only feedback the sender would ever get** — absorbing a defect is kinder than reporting it & strictly worse, since it converts a repeatable, fixable contract violation into a permanent tax on the receiver, invisible to the only party who could fix it. Make the cleanup a reported finding routed back to the sender. **Escalation is only as good as your ability to detect the answer** — positive-control the reply channel before recording "no response." One lane logged *zero human replies* across four consecutive runs from a probe whose only possible sentence was *"I saw no footerless messages"*: structurally incapable of reporting a reply, while a real reply existed the whole time. And when two lanes independently escalate the same item to the same person within hours, that is not diligence — it is the signature of an item with **no owner & two claimants**, and it degrades the ask by making silence ambiguous, because neither lane can tell whether it was ignored or whether the other one was answered. **A kit like this one has a novelty gate & a confidentiality gate, & no adoption gate — so it can recommend to strangers a rule its own author's vault never agreed to run.** Every other entry on this page is about a check that misses something. This one is about a check that was never written, & it sits underneath all of them. Before a lesson enters a document like this it gets tested twice: *is it already covered?* & *is it safe to publish?* Both are tests of the text. Neither asks the question that decides whether a prescription is worth anything: **has anyone with the authority to adopt it actually adopted it?** The reason it stays invisible is that a lesson has two halves & only one of them is established by the incident that produced it. The **diagnosis** — what went wrong — is evidenced, often first-hand & more than once. The **remedy** — what to do about it — is invented on the spot by the person writing the lesson up, & it inherits the diagnosis's credibility for free. Nothing downstream ever separates them again. In the case that produced this entry, the diagnosis had been verified twice in two independent lanes' logs; the remedy was written the same night, published internally & to the open web within a day, & refused by the only person who could install it in the first five minutes he looked at it. Three rules. **Label every prescription with its adoption state, in the text** — *derived* (invented here, nobody has run it), *adopted* (agreed, with a date), *declined* (offered & refused; keep the entry, mark it, & say what replaced it). An unlabelled prescription reads as adopted, because a document written in imperatives sounds like policy. Most of what any kit contains is honestly **derived**, & saying so costs nothing while sparing a reader from running a rule the author's own system would not. **A declined remedy is high-value evidence — never delete it, & never let it discredit the diagnosis.** This is the mid-incident prognosis entry run backwards: there, an overstated observation was corrected & the sound remedy survived; here the observation is sound & the remedy was refused. Both demand the same discipline — state plainly which half moved. The refusal is worth more than a clean entry would have been, because it is the only signal in the whole system that originates outside the pipeline's own reasoning. **A pre-registered escalation gate is a hypothesis about what the principal wants, & it is superseded by his answer to the question that gate encodes.** This is the half with teeth. The routine in question had pre-registered, in writing, that on its next run it would escalate the open item *as an incident rather than a repeat* — & by the time that run fired, the principal had explicitly declined incident-reclassification for that exact class. Firing it would have been *I asked, you said no, my run log told me to anyway.* A gate written before an answer arrives does not survive the answer: re-read your own pre-registered conditions against anything the principal has said since, **before** firing them. The failure is asymmetric & quiet — firing a superseded gate looks like diligence, & the person receiving it cannot tell it apart from a routine that never asked at all. --- ## First-week troubleshooting The failures below hit most new vaults in the first seven days. Each is listed as symptom → likely cause → fix. **A routine was approved but never fires.** The scheduled task does not exist. Approving a routine in a proposal or a todo is not creating the task in your scheduler. Fix: verify the task exists (`list_scheduled_tasks` or equivalent) and has a recurring cron expression with `enabled: true`. The source vault's highest-ROI routine sat approved-but-uncreated through two multi-day blackouts. **A routine fires but produces nothing.** Three common causes. (1) The methodology file path in the prompt is wrong — the routine reads nothing and falls back to defaults. Fix: verify the exact path and `cat` it from the prompt's perspective. (2) The vault path has detached — a managed-sync layer (iCloud, Dropbox, OneDrive) relocated the vault and left the configured path as a live-looking empty stub. Fix: `find ~ -name "CLAUDE.md"` to locate the real copy, update the path, and add the path-liveness check to Step 0. (3) A connector (Slack, Gmail, Calendar) lost auth silently — the routine runs clean but reads nothing. Fix: add a connector-auth check to Step 0 and declare degraded mode immediately rather than discovering the gap mid-crawl. **The daily note is empty or trivially short.** The crawler's sources are returning nothing. Most often: an API rate limit, an expired OAuth token, or a query that matches nothing. Fix: check each source independently. A source that returns empty is still a finding ("source returned empty at [timestamp]") — write that into the note rather than skipping it. Partial data beats no data. **The methodology file cannot be read in one pass.** The file has grown past the harness's single-pass read limit (~256 KB) because the run log was never rotated. Fix: move the oldest run blocks to `Pipeline/Archive/[routine] Run Log - Runs [range].md`, leave a one-line pointer in the methodology file, and set a rotation threshold in the maintenance skill so this is enforced rather than remembered. **Duplicate or conflicting files appear.** A filesystem-sync conflict (iCloud, Dropbox) created copies with names like `methodology 2.md` or `methodology (conflicted copy).md`. A routine that opens the wrong copy reads an older fork of its own instructions. Fix: run `find` for the conflict-name patterns (` 2.md`, `conflicted`), keep the newest-mtime copy, remove the rest, and check your sync tool's conflict-resolution setting. **Two routines clobber each other's output.** Both routines write to the same file or folder without checking the other's work. Fix: add the offending folder to the ownership table in the maintenance skill and enforce one primary writer per folder. If both genuinely need to write to the same file, use append-only semantics with a per-routine section marker. **The synthesis reports stale information for days.** The most common cause: the synthesis routine is scheduled *before* the producer it reads. The schedule table says one order; the live scheduler runs another. Fix: diff the governance doc's schedule table against the live scheduler registry. A consumer chronically reporting its upstream as stale is a scheduling hypothesis before it is a producer hypothesis — check the registered fire order of the pair before debugging the producer. **A correction applied by the loop-closer keeps reverting.** The corrected files cite a source document as their authority, and that source document still teaches the old rule. The next routine to follow the pointer re-derives the stale value, freshly worded. Fix: grep for what the corrected files name as their *source* and repair that root first. Symptom-only repairs regenerate. **The vault works for a week, then stops overnight.** The machine sleeps or reboots, and the scheduler does not auto-resume. A laptop is not a scheduler. Fix: ensure the scheduler survives a restart (launchd `KeepAlive`/`RunAtLoad` on macOS, a systemd service on Linux, a login-item plus a watchdog). Alternatively, move the scheduler to an always-on machine or a cloud cron service. The source vault lost multiple overnight windows to this before provisioning an always-on host. --- ## Scope of this document This is the pattern, not an instance. Every organization name, customer, person, figure, schedule and private detail from the vault this was distilled from has been left out by construction: this document was written clean rather than redacted, because a redaction is only as good as the pattern used to verify it & that is one of the failure modes described above. Two pieces in Phase 0 are described but not linked, because they are internal repos rather than open-source ones: the canonical tool-patterns repo & the planning hub. That is deliberate. A link you cannot open is worse than a description you can act on, & both of those encode a context rather than a capability — you are meant to build your own, not clone mine. You are meant to instantiate it against your own context, not to adopt someone else's answers.