/lumin-repo-lens

name: lumin-repo-lens
description: "Audit TypeScript/JavaScript repos for structural debt with machine evidence: dead exports, cycles, oversized modules, duplicate helpers/types, barrels, naming drift, refactor plans, 'what should I clean up next?', and 'does X exist anywhere?'"

Lumin Repo Lens

Default Surface

This is the read-only audit and refactor-plan surface of an LLM-facing repo evidence engine. Claude or another coding assistant reads the artifacts, then answers the human in a vibe-coder-friendly voice. Default chat is kind, plain, short, and action-first. Keep cold evidence behind the answer: mention artifact names only as compact proof. Expand raw JSON paths, FP ids, tiers, canonical jargon, HCA, or P-phase names only when the user asks for proof, formal handoff, CI output, or maintainer/debug detail.

Voice Anchor

Operator: the model reading this skill. Reader: a person who may be two months into coding and just wants to know what to do next. Use everyday words, not insider tool labels. Compress like a headline, not a press release — file/line/count stay visible, padding drops. Use hedging like "looks like" only when the internal label is `degraded` or `unknown`; strict evidence rules still apply.

Core Contract

Run the tool, read artifacts, then make the claim. The skill emits machine evidence; the model turns it into scoped, helpful review language.

NO STRUCTURAL CLAIM WITHOUT MACHINE EVIDENCE
NO ABSENCE CLAIM WITHOUT STATED SCAN RANGE
NO STRUCTURAL REVIEW WITHOUT A CHECKLIST GATE

If you have not run the relevant script in this session, do not claim a count. If an artifact is missing or degraded, say so. Tier C means "no consumer was found in the constructed graph," not "definitely dead." If terms such as FP23, HCA, P4, Tier C, or SAFE_FIX are unfamiliar, read `references/glossary.md` before expanding the answer.

Hand Off Code-Change Requests

Use sibling skills for lifecycle changes: `lumin-repo-lens-write-gate` owns add/edit/move/rename plus post-write checks; `lumin-repo-lens-canon` owns canon draft/drift. This surface stays read-only except audit artifacts and pre-existing or explicitly requested living audit docs.

Public Surface

Use the recommended orchestrator first. Use `<audit-repo>` for the current context: generated skill package = `node scripts/audit-repo.mjs`; maintainer checkout = `node audit-repo.mjs`. Below, `<audit-repo>` means the command path for the current context.

This surface owns `audit`, `welcome`, and `refactor-plan`. The shared engine still exposes `pre-write`, `post-write`, `canon-draft`, and `check-canon` through sibling skill surfaces.

When installed as a Claude Code plugin, these same flows are exposed as namespaced slash commands, including `/lumin-repo-lens:welcome`, `:audit`, `:full`, `:pre-write`, `:post-write`, `:canon-draft`, `:check-canon`, and `:refactor-plan`. Those command files are thin delegators. For slash-command entrypoints, read `references/command-routing.md` first; it is runtime control, not optional background reading.

The engine preserves cold artifacts on disk, but the chat surface still starts with plain next steps unless the user asks for maintainer/debug detail. `refactor-plan` is a coaching mode for human-in-the-loop planning; it has no CLI flag, producer, or JSON artifact of its own.

Generated public wrappers live in `scripts/`; runtime internals live in `_engine/` and are not a stable user API. The runtime canon spine lives in `canonical/`; templates live in `templates/`; self-contained operating guides live in `references/`. Use `canonical/` for invariant/spec contracts and `references/` for CLI, routing, policy, and language-support details. Maintainer-only history, tests, corpora, drafts, and self-audit fact snapshots are not user-facing skill surfaces.

When To Use

Use this skill for repository-structure questions that need scan-wide evidence:

• dead exports, over-exported symbols, or safe cleanup candidates
• cyclic dependencies, topology, cross-submodule coupling, barrel fan-out
• god modules, oversized functions, feature envy, duplicate shapes
• questions about existing canonical drift artifacts; use

`lumin-repo-lens-canon` to draft or check canon

• multi-repo comparison
• structural review against the checklist
• tracked/living audit docs across runs
• any "does X exist anywhere" or "how many X" question where manual

reading would be unreliable

Do not use it for pure taste questions unless the user provides an explicit convention to check.

Default to the vibe-coder surface: choose profile by cadence, name at most three things worth smoothing next, include a copy/paste coding prompt when useful, and keep raw JSON, FP ids, tiers, and canonical jargon in reserve unless proof is requested.

Best Fit And Boundaries

This skill works best on JS/TS workspaces that use npm, pnpm, yarn, or Bun workspaces; package public surfaces through `exports`, `main`, `module`, `browser`, `types`, `typings`, or `bin`; and tsconfig or Node `#imports` aliases. `package.json#exports` subpaths are protected by the `publicApi_FP23` policy.

For framework conventions, codegen files, Python/Go boundaries, and marketplace wording gates, read `references/language-support.md`, `references/false-positive-index.md`, and `references/operational-gates.md`. The long FP case ledger is maintainer-only, not ordinary skill context.

In `lumin-repo-lens-write-gate`, planned file paths are checked for sibling domain clusters and shape reuse before code changes. This audit surface only hands off to that sibling skill; it does not restate the write-gate protocol here.

Audit And Review Routing

For audit cadence, checklist gating, output shape, and claim discipline, read `references/structural-review-workflow.md`. It owns the detailed rules that keep this SKILL.md small:

• when to run `quick`, `full`, or `ci`
• how to treat `manifest.json` and `audit-summary.latest.md`
• when to use `templa