--- name: feature-explorer description: > Use this skill when the user wants to understand a feature, subsystem, or component in a codebase. Triggers: "explain X", "how does X work", "understand X", "deep dive into X", "how to debug X", "how to add X", "walk me through X", "reverse engineer X". Produces internal-documentation- quality output that lets a developer confidently modify, debug, review, or extend the feature. compatibility: "antigravity, Claude Desktop, Cowork — any surface with filesystem access" license: MIT --- # Feature Explorer Skill Reverse engineer a subsystem until a developer understands it well enough to confidently modify, debug, review, or extend it. The output should read like internal engineering documentation written by one of the original maintainers — not a code summary. --- ## Trigger Phrases | User Input | Mode | |---|---| | "Explain Bitswap" | full | | "How does DHT work?" | full | | "Deep dive into GossipSub" | full | | "Walk me through the transport layer" | full | | "Quick overview of the peerstore" | quick | | "How do I debug connection failures?" | debug | | "How do I add a new transport?" | modify | | "How to extend the protocol handler?" | modify | --- ## Execution Pipeline Run these phases in strict order. ``` User asks about a feature │ ▼ Phase 1 — Repository Reconnaissance │ ▼ Phase 2 — Scope the Feature │ ▼ Phase 3 — Entry Points │ ▼ Phase 4 — Call Graph │ ▼ Phase 5 — Architecture and Components │ ▼ Phase 6 — Data Flow │ ▼ Phase 7 — State Machines │ ▼ Phase 8 — Object Lifecycle │ ▼ Phase 9 — Design Decisions │ ▼ Phase 10 — Patterns │ ▼ Phase 11 — External Dependencies │ ▼ Phase 12 — Error Handling │ ▼ Phase 13 — Testing Strategy │ ▼ Phase 14 — Modification Guide │ ▼ Phase 15 — Debugging Guide │ ▼ Phase 16 — Reading Order │ ▼ Phase 17 — Mental Model │ ▼ Phase 18 — Diagrams │ ▼ Phase 19 — Questions to Validate Understanding │ ▼ Generate Report → Save Report ``` --- ## Step 1 — Parse Intent Extract from the user's message: - `FEATURE` — the subsystem, component, or concept to explore. May be vague ("transport layer") or specific ("TCP transport dial"). If too vague to locate in code, ask one clarifying question before proceeding. - `REPO` — from current working directory or user input. - `MODE` — one of: `full | quick | debug | modify`. Default: `full`. Load mode file before proceeding: - full → read `modes/full.md` - quick → read `modes/quick.md` - debug → read `modes/debug.md` - modify → read `modes/modify.md` --- ## Step 2 — Run the Pipeline Read `phases/discovery.md` and execute Phases 1–3. Read `phases/internals.md` and execute Phases 4–8. Read `phases/understanding.md` and execute Phases 9–13. Read `phases/guide.md` and execute Phases 14–19. The mode file specifies which phases to run and at what depth. Always run Phase 1 (reconnaissance) regardless of mode. --- ## Step 3 — Generate Report Load `templates/report.md`. Fill all 24 sections that apply to the current mode. For sections not covered by the current mode, write: `"Not covered in mode."` The report must read like documentation written by an original maintainer. Use concrete file paths, function names, and line references. Never write vague generalities — every claim must be traceable to actual code. Mark inferences explicitly: `[INFERRED]` when reasoning about intent without direct evidence in code or comments. --- ## Step 4 — Save Report Save to EXACTLY this path (do not change it or rename the file): `downloads/FEATURE-EXPLORER/--exploration.md` Normalize `FEATURE` to lowercase-hyphenated (e.g., `gossipsub`, `tcp-transport`, `dht`). Confirm the save path to the user. --- ## Global Rules - Do not summarize. Explain. - Do not describe what you see. Explain why it is designed that way. - Every phase output must be grounded in actual code read from the repository. - Never fabricate function names, file paths, or behavior not found in the code. - When the feature interacts with external standards or protocols, name the spec (e.g., "this implements section 4.2 of the libp2p connection establishment spec"). - Mark all design-decision reasoning as `[INFERRED]` unless a comment, commit message, issue, or doc confirms it. - Prefer depth over breadth — one well-explained component is more valuable than five shallow summaries. - STRICT SCOPING: Stay focused entirely on the requested feature. Even if you discover major architectural flaws or related issues, document them *within* the feature's report under the relevant section. Do NOT broaden the scope to analyze the entire architecture. - STRICT FILE PATH: You MUST save the report EXACTLY to the path specified in Step 4. Never rename the file based on your findings.