undefined-ui/second-brain-os

# Audit the context window

Theory: [How models read context](https://secondbrainos.dev/#/read/course-1-context/how-models-read)
and [The four places](https://secondbrainos.dev/#/read/course-1-context/the-four-places).
Every piece of context belongs in exactly one of four places — a byte-stable
system prompt, a frozen tool set, a compacting history, and a short live tail —
and most agent problems trace back to something sitting in the wrong one.

## Core rule

Report and rank; never edit. The output is an audit, and the user decides
what to apply. If they ask you to apply fixes afterwards, that is a normal
edit session, not this skill.

# Bootstrap the eval suite

Theory: [Two kinds of checks](https://secondbrainos.dev/#/read/course-5-evals/two-kinds-of-checks)
and the full walkthrough in [Evals practice](https://secondbrainos.dev/#/read/course-5-evals/evals-practice).
An eval suite is the same test after every change. Behavioural checks read
the steps of a trace; end-to-end checks read only the result. Start
behavioural: they are deterministic, run in seconds, and diagnose instead of
just scoring.

## Workflow

1. **Find real failures.** Ask where the agent's runs live (logs, transcripts,
   a traces directory). Read until you have up to twenty real failures — not
   imagined ones. If there are no logged runs yet, build the trace logging

# Find the gates

Theory: [Cheap decisions](https://secondbrainos.dev/#/read/course-3-gate/cheap-decisions)
and [Gate practice](https://secondbrainos.dev/#/read/course-3-gate/gate-practice).
An agent does two kinds of work: it writes, which needs a big model, and it
decides — is this spam, which queue, does this need a person — which is a
bounded question the answer to which comes from a set you already know.
A gate is a cheap decision layer that sorts the stream so the expensive
model only sees the items that actually need judgement.

## Workflow

1. **Map the decisions.** Read the pipeline's entry points and prompts and
   list every decision made before or during a model call: classification,

# Write done as a script

Theory: [The four parts of a loop](https://secondbrainos.dev/#/read/course-2-loop/the-four-parts)
and the [goal test build page](https://secondbrainos.dev/#/read/track-loop/build-goal-test).
"Improve the error handling" cannot terminate a loop, because nothing can ever
say it is finished. The goal must be phrased so that a program — not a person,
not the model — returns true or false against it.

## Workflow

1. **Extract the claim.** Ask what the user wants true at the end, then
   restate it as verifiable facts: which command exits 0, which file exists,
   which string appears, which number crosses which threshold. If a part
   cannot be checked by a program, say so and negotiate it down to what can.

# Audit the four rings

Theory: [The four rings](https://secondbrainos.dev/#/read/course-4-harness/the-four-rings)
and [Harness practice](https://secondbrainos.dev/#/read/course-4-harness/harness-practice).
Build from the outside in: containment, guides, sensors, permissions. The
order matters because each ring must hold when every ring inside it fails —
a guide can be ignored, a sensor can miss, an approval can be misclicked;
a wall does not care.

## Core rule

Report and rank; never harden anything yourself. The audit's one organising
question is the blast radius: describe the worst session possible under the
current setup and what it costs. If the user asks you to apply fixes

# Backfill an archive

A backfill is where cost and quality both go wrong quietly. Done in the wrong
order it also inverts the vault's history, because later sources should update
pages that earlier ones created.

## Core rule

Oldest first, ten sources per batch, stop for a go-ahead between batches.

## Workflow

1. **Triage before ingesting.** Read titles and first paragraphs. Sort into
   worth-ingesting, keep-in-raw, and delete. Most archives are half dead links

# Trace changed positions

This is the query a vault can answer that nothing else can, and the reason the
supersession rules exist. It only works because contradictions are recorded
rather than overwritten.

## Core rule

Report the change with both positions, both dates and the evidence between them.
A conclusion without its history is just the current claim.

## Workflow

1. **Find superseded claims** across concept pages, and contradictions where the

# Import chat history

Chat history is the most underrated source a person owns and the most sensitive.
It records their reasoning, not just facts, and it also records things they would
not want in a file that gets synced, committed and backed up.

## Core rule

Privacy pass before triage, triage before ingestion. Never ingest an export
wholesale.

## Workflow

1. **Convert** with `scripts/chat_export_to_md.py` into one file per

# Analyse the graph

The graph is the search space every answer is drawn from. Its shape decides
whether retrieval reaches the relevant material in a few hops or reaches nothing.

## Core rule

Report shape and what it means, never fix anything. This skill is read-only.

## Workflow

1. **Run the scripts** rather than reading files: `scripts/vault_stats.py` for
   counts and degree, `scripts/link_check.py` for orphans and breaks,
   `scripts/graph_export.py` when deeper analysis is wanted.

# Ingest a source

An ingest that only writes a summary page produces a vault that grows without
getting smarter. The whole value is in the second half of the job: connecting
the new material to what is already there. A page that lands unlinked is
invisible within a week.

## Core rule

Nothing is ingested until it is linked. Every run ends with the new pages
connected to existing pages in both directions.

## Workflow

# Lint the vault

Structural rot is silent. Nothing errors, nothing crashes, the vault just
slowly stops answering questions well because a third of its pages are
unreachable. Linting is the only thing that catches it before the owner does.

## Core rule

Report before repairing. Fix the mechanical problems automatically, but never
delete or merge a page without listing it first and getting a yes, because the
owner may have written it by hand.

## Workflow

# Merge duplicate pages

A merge is irreversible in the way that matters: afterwards you cannot tell
which claim came from which page. Two ideas that look identical from their
summaries are often a general case and a specific one.

## Core rule

Never merge unprompted. Propose, wait for approval, then follow the procedure
exactly.

## Workflow

1. **Pick the survivor** by canonical name, not by which page is longer.

# Record metrics

A single reading tells you almost nothing. Direction over months is the
information, and nobody remembers what last quarter's orphan rate was.

## Core rule

Four numbers, appended to a dated log, compared against the last entry. Never
page count or word count.

## Workflow

1. **Run** `scripts/vault_stats.py` and `scripts/link_check.py`.
2. **Record:** orphan rate, average degree, component count, stale-concept rate,

# Audit privacy

A mature vault is one of the highest-signal documents about a person that
exists, and it lives in a folder that gets synced, committed, backed up and
occasionally shared. Every copy is another place the content exists.

## Core rule

Find and report. Delete nothing without an explicit instruction naming what to
remove.

## Workflow

1. **Scan for credentials:** API keys, tokens, passwords, connection strings.

# Set up a project

The knowledge layer answers what you know. The project layer answers what you
are doing this week. Merging them fills a wiki with dead task lists and buries
working files under conceptual notes.

## Core rule

One goal per project, stated in its own `CLAUDE.md`. A project with three goals
is three projects.

## Workflow

1. **Interview if needed.** What this produces, for whom, by when, and what the

# Prepare to publish

Once something is crawled, it is out. Every check here is cheap; the failure it
prevents is permanent.

## Core rule

Explicit opt-in only. A page publishes because it says `publish: true`, never
because nothing excluded it.

## Workflow

1. **List the opt-in set.** Every page marked for publication.
2. **Follow their links.** A published page linking to a private one either

# Query the vault

A query that quietly falls back on general knowledge is the most damaging thing
this system can do. The owner built the vault so answers would be grounded in
what they actually read, and an answer that blends the model's priors with
their notes is worse than no answer, because it cannot be checked.

## Core rule

Every claim in the answer comes from a page in the vault and names that page.
Anything you know but the vault does not is labelled as outside knowledge or
left out.

## Workflow

# Quiz from your own pages

Reading something is not learning it. A vault of well-written pages nobody
revisits is a library, and libraries do not make anyone knowledgeable.

## Core rule

Questions come from the user's pages, at the depth those pages record. Never
from general knowledge about the topic.

## Workflow

1. **Pick the scope:** a topic, a cluster, or pages updated recently.
2. **Write questions of two kinds:** recall of what the page states, and

# Rename a page

An agent renaming a file directly is the single most common source of broken
links in an agent-maintained vault. Obsidian fixes links when you rename inside
the app; writing the file directly does not.

## Core rule

A rename is four operations, not one. All four, or none.

## Workflow

1. **Check the new name** against existing pages and aliases. A rename that
   collides with an existing alias creates ambiguity the graph cannot resolve.

# Write a research report

A report that presents only findings looks stronger and is less useful, because
the reader cannot tell where it is load-bearing and where it is thin.

## Core rule

Scope against the vault first. Most of the work in a good report is knowing what
you do not need to look up.

## Workflow

1. **Inventory what exists.** Which pages cover this, what is thin, what is
   missing entirely. That answer is the research plan.

# Review the vault

Capture systems fail at the point where nothing comes back out. A review is the
loop that closes: it turns a week of ingestion into something the owner reads
and acts on, and it is what makes the vault feel alive rather than archival.

## Core rule

A review reports on the vault, not on the agent's activity. Nobody needs to
know how many tool calls ran; they need to know what they now know.

## Workflow

1. **Diff the period.** New and updated pages since the last review, from

# Clean a transcript

Concept pages built from unpunctuated caption dumps are noticeably worse,
because the model spends its attention reconstructing sentence boundaries
instead of understanding claims.

## Core rule

Clean, never summarise. Nothing is cut. This is a formatting pass on the record,
and the record has to stay faithful.

## Workflow

1. **Punctuate and paragraph.** Sentence boundaries first, then paragraphs at

# Write from the vault

The research is already done, cited and connected. What is left is the argument,
and that is the part the user should keep.

## Core rule

Assemble structure and evidence. Do not hand back finished prose as if it were
theirs.

## Workflow

1. **Find the relevant concept pages** and say what they collectively argue.
2. **Surface the disagreements.** These are where the user has something to say