source-explorer

# source-explorer Reads a product's source code and builds a plain-language summary of its public surface. The writer can then ask follow-up questions interactively ("what does `loadLevel` actually do?", "what are all the valid states?", "are there any flags with conditional defaults?"). **This skill produces no structured output, runs no diff, and files no tickets.** It is a comprehension tool, not a validation tool. ## Scope This skill covers products whose public surface is declared in code: CLI flags, config options, HTTP API request/response shapes, enums, and states. UI-driven products (those whose primary public interface is affordances in a web or desktop UI) are out of scope. ## Inputs One argument: a property name. Two cases: - **Manifest exists** (`references/manifests/<property>.yaml` in the `docs-drift` skill directory): use its `source.repos` and `source.surface_hints` as the reading guide. - **No manifest yet**: ask the user for a repo URL and a brief description of where the public surface lives before proceeding. Use these ad-hoc hints as the reading guide; do not scaffold a manifest (that is Discovery mode in `docs-drift`). ## What to read Guided by `source.surface_hints` (or the ad-hoc hints provided), read the source exhaustively — do not sample. Walk every surface location the hints point to: - Every CLI flag / config option definition site - Every public API request/response struct and its fields - Every enum and state declaration - Every conditional default and behavioral constraint enforced in source Also note anything marked with an intent marker (e.g. `// internal`, `// external-only`) — these are intentionally undocumented and worth flagging to the writer so they are not confused by their absence from the docs. ## Output After reading, present a structured plain-language summary: ### Summary format **Product:** `<property>` **Source:** `<repo>` @ `<ref or branch>` #### Public flags / options For each: name, type, default (including conditional defaults), any behavioral constraints, and a one-line description of what it does. #### Public API endpoints / request shapes For each endpoint: path, method, request fields (name, type, required/optional, default), response fields. #### States and enums For each: name, allowed values, and what each value means in plain language. #### Intentionally hidden surface Items found in hidden-surface locations or carrying intent markers — listed so the writer knows they exist but are excluded by design. #### Gaps and questions Anything the hints pointed to that you could not find, or anything that looked ambiguous. Flag these for the writer. --- After presenting the summary, remain interactive. Answer follow-up questions by reading additional source context as needed. Do not invent details — if a question requires reading a file you have not yet seen, read it. ## Relationship to docs-drift This skill and `docs-drift` share manifest inputs but serve different purposes: - Use `source-explorer` **before** running `docs-drift` on a new property, especially in Discovery mode. Understanding the codebase first leads to better `surface_hints` and `intent_markers` in the manifest. - Use `source-explorer` standalone when a writer needs to understand a product's source without running a full drift audit. - `docs-drift` Stage 2 (structured extraction) is a separate, focused task — it does not call this skill. The two read the same source independently.