browzer-bootstraper

browzer-bootstraper — onboard a repo with docs that tell the truth

This skill turns an arbitrary repo into a Browzer-powered RAG workspace after its existing documentation has been reconciled against the codebase. The order matters: the index is built last, so it captures the cleaned docs — not the stale ones.

The skill never creates new files. No blueprint generators, no drift reports, no scratch artefacts. It only edits or deletes existing markdown. If the repo has no docs to reconcile, the skill says so and proceeds to indexing.

The operator confirms the diff before any commit lands. The skill respects that gate absolutely.

What this skill changes vs. what it leaves alone

Changes: existing markdown files in the repo where the doc's claim no longer matches the code (wrong path, wrong API shape, wrong env var, wrong port, wrong command, wrong version). Stale content gets DELETED — outright, no > ⚠️ STALE markers, no <!-- TODO: verify --> annotations, no "delete candidate" tags. Duplicated content (same claim in three places) collapses to the most authoritative location with the duplicates deleted; cross-links only when they're genuinely useful.

Leaves alone:

• Code, tests, configuration, CI workflows.
• Historical artifacts (CHANGELOG.md, retro notes, ADRs already labelled as historical).
• Doc subtrees explicitly marked archived (retrospectives/, archive/, history/, old/, status: archived frontmatter).
• Style and prose voice — the skill rewrites factual claims, not tone.
• Anything outside the repo's working tree.

Phase 1 — Preflight

browzer status --json --save /tmp/browzer-bootstrap-status.json 2>&1

Decision tree from the status output:

• exit 2 → not authenticated. STOP and hand off to use-rag-cli (browzer login). Do not proceed.
• exit 3 OR no active workspace in the JSON → no workspace yet. Do NOT run browzer init here. Phase 4's index step handles that, AFTER the docs are clean.
• Workspace present and healthy → continue.

If the repo has uncommitted changes, surface that fact in chat (one line, not a panel) and ask: proceed (the doc reconciliation will land mixed with existing changes — confirm), or stop so the operator can stage/stash first.

Phase 2 — Audit existing docs against the code (code is source of truth)

The audit runs over every existing markdown file in the repo's working tree, excluding archived subtrees. The plan order is:

1. Inventory. List every *.md / *.mdx under the repo. Filter out:

   • Files inside any subtree marked historical (retrospectives/, archive/, history/, old/).
   • Files with status: archived in YAML frontmatter.
   • Generated docs (typed-docs output, autogenerated API references).
   • The repo-root CHANGELOG.md is reconciled but never deleted — it's append-only history. Reconcile means: leave existing entries alone; only correct factually-wrong forward-looking claims (e.g. "the next release will add X" when X already shipped or got removed).

2. Per-doc claim extraction. For each non-archived doc, identify the factual claims that depend on the code: file paths, exported symbols, env vars, ports, commands, CLI flags, dependency versions, architectural assertions, "how it works" descriptions. These are the verifiable surface; prose framing around them is left as-is unless the framing implies a wrong fact.

3. Code lookup, every claim. For each claim, ground it in the codebase. Use browzer explore "<symbol or concept>" --json --save /tmp/explore.json first; fall back to Read on a concrete file only when explore points there. Don't grep-walk the tree — that's what the index is for, and the bootstraper is meant to use the existing index, not bypass it.

4. Verdict per claim — apply this matrix:

   Claim status	Action
   Matches the code today	Keep verbatim.
   Wrong but the right answer is obvious from the code	Rewrite the claim in place.
   Wrong AND no claim is needed (the doc was describing something that no longer exists)	Delete the claim outright. No marker. No TODO.
   Duplicated across 2+ docs	Pick the most authoritative location (typically the closest CLAUDE.md / package README), keep it there, delete the duplicates.
   Confusing / contradictory across two docs	Resolve against code. Rewrite the surviving copy. Delete the contradicting fragments.
   Cannot verify (no relevant code found)	Treat as wrong. Delete. The bar is "demonstrably true today", not "plausible".

5. Documents that survive the audit empty. When every factual claim in a doc was deleted, the doc itself is deleted (rm <path>). A doc with only its title and zero useful content adds noise to retrieval; deletion is the right answer. The audit trail (Phase 4's diff) shows exactly what went.

The audit MUST NOT introduce ambiguity. "Stale" is not a status the skill emits; the skill either fixes the claim or removes it. Markers like > ⚠️ STALE, <!-- delete candidate -->, [needs verification] are explicitly banned outputs.

When two docs disagree, code wins. Always. If the code itself is unclear, deletion is preferred to leaving a guess in the doc — a missing claim is fixable on the next edit; a wrong claim is silently misleading.

Phase 3 — Show the diff and ask once

After the audit completes, summarise the changes in chat (terse, one paragraph at most) and surface the unified diff for review:

git diff --stat
git status --short

Optionally, when the operator wants the full diff: git diff (the operator can scroll). Don't paste a multi-thousand-line diff into chat by default.

Then ask, once:

AskUserQuestion:
  Doc reconciliation produced <N> edits + <D> deletions across <F> files.
  How do you want to proceed?
    (a) commit  — invoke /commit with the diff as-is
    (b) modify  — tell me what to add, remove, or change before committing
    (c) skip    — leave changes staged but don't commit (you'll commit manually)

Wait for the operator's reply. Do NOT proceed past this gate without an explicit answer. If the operator picks modify, apply the requested adjustments, re-show git diff --stat, and ask again.

Phase 4 — Commit, then index/sync

The order is: commit FIRST, index SECOND. The index built in this phase reflects the cleaned docs — that's the entire point of bootstrapping in this order.

4.1 Commit (only when the operator picked commit)

Invoke the commit skill using the Claude Code Skill tool (not a bash command):

Use the Skill tool: skill name = commit.

The commit skill writes a Conventional Commits message (typically docs(bootstrap): reconcile existing docs against codebase or similar — let it choose based on the repo's recent log). When no feat dir exists for this skill's run, commit operates standalone — that's the expected path.

Skip the commit entirely when:

• Operator picked skip in Phase 3.
• The audit produced zero edits AND zero deletions (git status --short is empty after Phase 2). Tell the operator "docs already match the code; no commit needed."

4.2 Index or sync the workspace

Now that the docs are clean (or were already clean), build the structural + document index:

• No prior workspace (Phase 1 found exit 3 or empty) → browzer init then browzer workspace index. The init step creates .browzer/config.json and may modify .gitignore and append a KB section to a top-level CLAUDE.md. Those changes are real edits to the repo and DO need a commit; if the operator already approved Phase 4.1, run browzer init BEFORE commit so init's writes ride along with the doc reconciliation. Otherwise, after init runs, surface the new files in chat and ask whether to commit them now.
• Workspace already healthy → browzer sync. Re-indexes both code and the just-cleaned docs.

Result on completion:

browzer status --json --save /tmp/browzer-bootstrap-status.json

The status JSON should show the workspace as current (commitsBehind: 0 or equivalent, depending on CLI version).

4.3 One-line confirmation

browzer-bootstraper: reconciled <E> edits, <D> deletions across <F> docs; <commit-action>; workspace <action> (<N> code files indexed)

Where <commit-action> is one of commit <sha> | commit skipped per operator | no commit (docs already clean), and <action> is created | synced | unchanged.

Failures use the standard two-line stop contract:

browzer-bootstraper: stopped at <phase> — <one-line cause>
hint: <single actionable next step>

Idempotency

• Phase 1: re-running on a healthy workspace skips init.
• Phase 2: docs already matching the code produce zero edits — re-running is cheap.
• Phase 3: when the audit finds nothing, the skill tells the operator "no changes" and skips the prompt.
• Phase 4: browzer sync is a no-op when nothing changed.

A second run on the same repo, with no source-code drift since the first, produces no commit and no index change.

Hard constraints (non-negotiables)

• Never create new markdown files in the repo. The skill's job is to RECONCILE existing docs, not invent new ones. If a missing topic is genuinely needed, that's generate-task → execute-task work, not bootstraper work.
• Never leave staleness markers in the repo (STALE, delete candidate, <!-- TODO: verify -->, etc.). Either fix the claim or delete it.
• Never preserve "historical record" prose in non-historical docs. Runbooks, READMEs, architecture docs, and CLAUDE.md children describe the system as it is today; out-of-date paragraphs are deleted, not annotated. Genuine historical artefacts (CHANGELOG, retro notes) are left alone per Phase 2.
• Never push from inside this skill. The commit skill stops at the commit; pushing is a human decision.
• Never run browzer workspace delete from inside this skill. Workspace lifecycle is workspace-management's job.
• Never skip the operator gate in Phase 3. Auto-committing without operator review is the pattern this constraint exists to prevent.
• Code is source of truth on every conflict. When two docs disagree, the code resolves it. When a doc and the code disagree, the code wins and the doc is rewritten or deleted. When the code itself is unclear, deletion is preferred to a guess.

When to refuse

• The repo has no .git — Browzer works on directories, but the commit step requires git. Offer to run Phase 2 (reconciliation in-place, leave changes staged) and skip Phase 4.
• The user asks to run this against a repo they don't own (public OSS read-only clone) — call out that uploading its docs to their workspace is technically fine but worth knowing.
• The user invokes the skill in their home directory or /. Refuse — the audit would walk into territory it shouldn't.

Output contract

The skill emits ONE confirmation line on success, or the two-line stop contract on failure. Banned from chat output: phase-by-phase summaries, multi-line ✅ banners, "Next steps" blocks, full diff dumps. The diff lives in git; the chat line is the cursor.

Related skills

• use-rag-cli — install + authenticate (anchor skill; this skill assumes auth).
• embed-workspace-graphs — browzer init + browzer workspace index (Phase 4.2 wraps these).
• commit — Conventional-Commits formatter for Phase 4.1.
• finalize-feature — workflow phase that patches host docs (Phase A) and renders the feat README (Phase B); complements bootstraper but operates on a single change rather than the whole repo.
• sync-workspace — lighter-touch re-index for incremental changes after the initial bootstrap.
• workspace-management — when the operator actually wants to delete / relink a workspace.