tpu_performance_autoresearch_wiki

Ingest a code repo into a grounded, lint-clean markdown wiki an agent can answer internals questions from. Idempotent reconcile — first build, version bump (--ref), or an added concept are all the same operation. Trigger when the user asks to wikify/ingest a repo, build an internals wiki, or update one. Accepts a repo URL or local path as the argument and bootstraps `config/<slug>.md` itself — the user never hand-writes config.

Connect ingested code silos on the concept axis — cross-link the same concept (a Pallas kernel, an optimization technique) across repos, inline like a normal wiki: the host wiki's concept page links down to each repo's implementation, and each implementation links back up. Selective by design — you choose WHICH concepts to connect (connecting everything drowns the pages). Trigger at the tail of an ingest (from the 2nd repo on) or when the user asks to connect / cross-link the ingested repos. No new page types; idempotent and re-runnable.

Run the LINT operation defined in SCHEMA.md across the wiki. Checks every invariant the schema declares — orphan pages, broken links, missing profile/HLO sections, missing hypothesis-firing audits, stuck `status: in_progress` stubs, missing stub labels (Hypothesis/Mechanism/Predicted signal/Falsification criterion), log routing violations (loop-iteration in global log; ingest in per-lane log), stale codebase commit pins, model-page variant-matrix drift, knobs-translation-matrix coverage gaps, model-optimization-index catalog rot, per-model refuted-patterns referencing non-existent v-IDs, experiment commits on the code-repo side missing `exp:` footer, and more. Fixes mechanical issues automatically; surfaces judgment calls as a punch list for the user. Invoke periodically (every few days during active iteration), from `/stop-experiment` at session end (already wired), or whenever the wiki shape changed substantially (post-rename, post-bulk-import, post-SCHEMA-update).

Ingest a paper, article, blog post, talk, or documentation page into the wiki. Encodes SCHEMA's INGEST-SOURCE operation as a callable skill. Reads the raw source (PDF/HTML under raw/sources/ or fetched from URL), confirms emphasis with the human before writing, files wiki/sources/<year>-<slug>.md, updates connections (concepts/codebases/models that touched the source), generates hypothesis candidates if applicable, and updates wiki/index.md + wiki/log.md per the operations contract. Invoke when ingesting any new perf-relevant source — the discussion step prevents misemphasis and the connection updates keep the wiki graph coherent. NOT for codebases (use INGEST-CODEBASE / a future /ingest-codebase skill) or per-experiment notes (those live in wiki/experiments/).

Bootstrap a new model family for the autoresearch loop. Creates the folder structure under wiki/experiments/, scaffolds the model-level program.md from a template (asking the user about lanes, sizes, hardware targets, sequence length, and architecture invariants), optionally creates lane-level program.md stubs, and creates model page stubs under wiki/models/. Invoke once per new model family before /start-experiment can run on it.

Generate a comprehensive retrospective for a `(model, lane)` pair that maps the explored search space, identifies coverage gaps from the topic taxonomy (`model-optimization-index.md`) and Pallas kernel catalog, surfaces premature-exhaustion signals (single-axis-probe vs kernel-port imbalance, frontier-stuck duration), and proposes ranked next directions. **Reads ALL experiment pages in the lane** — not a sample — because the retrospective's value depends on comprehensive coverage of what's been tried. Includes a lightweight cross-lane brief by default. Manually callable; intended to be invoked when the agent reports "out of ideas" or hits the stuck-frontier signature, BEFORE concluding the lane is exhausted. Output is a dated analysis page at `wiki/analyses/<YYYY-MM-DD>-<model>-<lane>-retrospective.md`; the skill does NOT act on its own recommendations — it produces analysis, the loop / `/formulate-hypothesis` acts.

Coding-discipline guidelines for surgically modifying model code inside a per-experiment fork in the autoresearch loop. Adapts Andrej Karpathy's LLM-coding guidelines (think before coding, simplicity first, surgical changes, goal-driven execution) to this project's invariants — no semantics drift, one mechanism per experiment, the training run is the test, no kernel fallbacks. Invoke BEFORE opening any model-code file in the experiment fork (step 4 of program.md's "experiment loop"). Helps weaker LLMs stay disciplined under autoresearch-loop pressure where the agent is autonomous and can't ask clarifying questions. NOT for wiki edits, infra scripts, or trunk merges — those are out of scope.

Refresh the GKE TPU cluster inventory for one or more GCP projects. Runs `.claude/scripts/scan-gke-clusters.sh` to enumerate clusters with TPUs in each project (status, XPK presence, ready-node count, XPK type, topology, machine type), writes a per-project Markdown summary at `.env/<project>-gke-tpu-cluster-scan.md`, and merges the project's rows into the combined `.env/gke-tpu-cluster-scan.md` (preserving the existing TPU-gen breakdown + sort rules + prose between tables). Invoke when a new cluster has been added to a project, when an existing cluster's XPK status or pool composition has changed, or for periodic batch refresh across multiple projects. NOT for occupancy checks ("which clusters have free capacity right now?") — that's `/start-experiment`'s Step 6 job and uses live `xpk workload list`.

Start the autoresearch optimization loop for a specific model + lane. Resolves the hierarchical program.md (root → model → lane), asks the user for hardware (local TPU VM or GKE cluster of a specified TPU type + topology), discovers available clusters from .env/, checks occupancy with USER_PREFIX-aware attribution, and starts /loop with the bounded-iteration prompt. Invoke at the beginning of an autoresearch session.

Stop the autoresearch optimization loop cleanly. Cancels pending ScheduleWakeup, reaps orphan workloads on the project's cluster pool, files any missing experiment pages, runs lint, and appends a clean-shutdown marker to wiki/log.md. Invoke at the end of an autoresearch session.