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.

<core_objective> Produce, inside --out, an "AI-optimized skill" with this shape:

/ 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. </core_objective>

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: