Build Brain

Parse arguments as:

• SOURCE = first positional path. Required. Points to EITHER (a) an existing skill folder (a SKILL.md plus references/), OR (b) a folder or set of data files: .md, .json, .xlsx/.csv.
• --out = REQUIRED output directory for the rebuilt skill. The user always specifies this. NEVER write outside it.
• --apply = write files for real. If absent, do everything up to and including the proposal + before/after preview, then STOP without writing.
• --no-gate = skip the confirmation gate in PHASE 3 and write immediately after the proposal.

If SOURCE or --out is missing, ask for it in one line and stop. Do not guess paths.

/ SKILL.md # the MAP: lean, ~under 150 lines. Loaded every time. references/ # the BRAIN: many small notes. Loaded on demand only. .md # one concept per file, Obsidian-style frontmatter + [[wikilinks]] ... maps/ index.json # master navigation map — the single source of truth for "what exists + when to load it" tags.json # tag -> [note ids], for tag search links.json # note id -> [linked note ids], the Obsidian-style graph manifest.json # build metadata: source, timestamp, version, counts, token estimates REPORT.md # before/after improvement report, junior-engineer voice

The point of this shape: an AI reads SKILL.md + index.json (cheap), then loads ONLY the one or two reference notes it needs (cheap). It never has to read the whole brain to answer one question. That is the token efficiency. Protect it in every decision.

PHASE 0 — INGEST (read only)

• Resolve SOURCE and --out.
• Recursively list SOURCE. Read every file. For .xlsx/.csv, extract each sheet/table as structured rows.
• Detect source type: "existing-skill" (a SKILL.md is present) or "raw-data".
• Build a raw inventory: path, type, line count, rough token estimate (~chars/4), and a one-line summary of each file's content.
• Do NOT modify SOURCE. SOURCE is read-only, always.

PHASE 1 — ANALYZE THE "BEFORE" Build an honest picture of the current state. Capture:

• Total files, total tokens, largest files, and how many tokens an AI must load today to answer a typical question.
• Structural problems: oversized files (one file doing many jobs), duplicated content, stale/contradictory info, missing or flat tags, dead or absent links, no machine-readable index.
• If existing-skill: is SKILL.md lean or bloated? Does it act as a map, or does it dump everything inline?
• If raw-data: what natural concepts exist? What is the smallest sensible unit to atomize into? State numbers, not adjectives. "SKILL.md is 1,900 tokens and inlines 6 topics" — not "it's a bit big".

PHASE 1.5 — TRIPLE CHECK (mandatory, three distinct passes) Re-examine your PHASE 1 analysis THREE times, each pass with a different lens. Write one short finding line per pass.

• Pass 1 — Completeness: Did I read every file? Any content I ignored, any sheet I skipped, any concept I missed?
• Pass 2 — Correctness: Are my token counts, file sizes, and "duplicate" claims actually true? Re-check the two biggest claims against the raw text.
• Pass 3 — Tradeoffs: For every change I am about to propose, what does it COST? (More files = more links to maintain. Aggressive dedup = risk of losing nuance. Smaller SKILL.md = more on-demand loads.) Name the cost honestly. Only after all three passes may you propose anything.

PHASE 2 — PROPOSE (with tradeoffs and before/after) Output the plan as text BEFORE writing. Include:

• Proposed reference list: each new note's slug + the one concept it owns + the tags it gets.
• The tag taxonomy (hierarchical, e.g. domain/subtopic).
• The exact JSON schemas you will write (index/tags/links/manifest).
• A BEFORE → AFTER table: file count, total tokens, tokens-to-answer-a-typical-question, # of dead links, has-machine-index (no/yes).
• A TRADEOFFS section: 3-6 bullets, each "We gain X, we pay Y."

PHASE 3 — GATE, THEN BUILD

• If --no-gate is set OR --apply is absent: handle accordingly.
• Otherwise print the proposal and ask exactly: "Proceed to write the brain to ? (yes / edit / no)". Wait for the answer. On "no" or "edit", stop and take direction.
• On approval (and only with --apply), write the full structure described in .
• Atomize per the rules in . Build the JSON maps per . Validate every JSON file parses and every [[wikilink]] resolves to a real note id.

PHASE 4 — REPORT (junior-engineer voice) Write REPORT.md. See . It must show before → after, what changed, why, the token savings, and the tradeoffs you accepted.

• One concept per reference note. If a note covers two ideas, split it.
• Keep each reference note small — target under ~300 lines / ~1,500 tokens. Bigger means split.
• Every reference note starts with Obsidian-style YAML frontmatter:

  ---

  id: title: summary: <one sentence, max 25 words — this is what the AI reads to decide whether to open the file> tags: [domain/subtopic, ...] aliases: [optional search terms] load_when: links: [[other-note-id]], ...

  ---

• Use [[wikilinks]] in body text to connect related notes. Every wikilink must point to a real note id.
• SKILL.md is a MAP, not a container. It holds: what this skill is, when to use it, and a table of every reference note with its summary + load_when. It must NOT inline the reference content.
• Prefer many small notes over a few big ones — but respect the tradeoff you named in Pass 3; do not shatter a coherent idea just to raise the file count.

tags.json — tag search index: { "tag/name": ["note-id", "note-id"] }

links.json — the note graph: { "note-id": ["linked-note-id", "linked-note-id"] }

manifest.json — build metadata: { "source": "path", "source_type": "existing-skill | raw-data", "built_at": "ISO-8601", "version": "1.0", "counts": { "notes": 0, "tags": 0, "links": 0 }, "tokens": { "skill_md": 0, "index_json": 0, "references_total": 0 } }

Write JSON minified or 2-space indented, no trailing commas. Validate every file parses before finishing.

1. "What I was given" — one short paragraph.
2. "What I noticed" — the real problems, with numbers.
3. "Before vs After" — a table (file count, total tokens, tokens to answer a typical question, dead links, machine index yes/no).
4. "What I changed and why" — short bullets. Each: the change, then "...because..." in one breath.
5. "Tradeoffs I made" — honest. "I split X into 4 notes. Upside: cheaper loads. Downside: 4 files to keep in sync. I thought it was worth it because..."
6. "How this is better for the AI" — explain, like to a teammate, why the new shape costs fewer tokens and is easier to search.
7. "Stuff I wasn't sure about" — anything you'd want a senior to double-check.

Example of the voice (match this register, not the content): "So the old SKILL.md was carrying everything itself — about 1,900 tokens, every single time, even if you only needed one fact. I pulled the six topics out into their own notes and left SKILL.md as just a map. Now the AI loads ~300 tokens to orient, then grabs the one note it actually needs. I think that's a big win, but I'll be honest — it's six files to maintain now instead of one, so if these topics change together a lot, tell me and I'll merge a couple back."

NEVER modify, move, or delete anything in SOURCE. NEVER write any file before PHASE 3 approval (unless --no-gate with --apply). NEVER inline reference content into SKILL.md. NEVER invent content that isn't supported by the source; if the source is thin, say so in the report rather than padding. NEVER drop information silently — if you cut or merge something, name it in REPORT.md under tradeoffs. NEVER skip a verification pass to save time. NEVER add apologies, filler, or "great idea!" — go straight to the work.

• /SKILL.md is a lean map (no inlined reference bodies).
• references/ holds atomized notes, each with valid frontmatter and resolvable [[wikilinks]].
• maps/{index,tags,links,manifest}.json all parse and agree with the files on disk.
• REPORT.md shows before → after with numbers, changes, and honest tradeoffs, in junior-engineer voice.
• SOURCE is untouched.

Made by HasBrains — https://hasbrains.com/