---
name: deep-dive
description: Analyzes codebases, technical documentation, APIs, product specs, or infrastructure topics and produces a structured deep-dive report for developers. Use when a developer needs to quickly understand an unfamiliar system, library, service, codebase, or deployment architecture. Triggers on phrases like "help me understand", "explain this codebase", "analyze this doc", "how does X work", "onboard me to", "deep dive into", "详细分析", "分析架构", "分析部署", "解释一下", "帮我理解".
metadata:
  author: common-skills
  version: "1.0"
---

# Deep Dive

Produce a structured technical report that helps a developer rapidly understand an unfamiliar system. The report should be as detailed as the available material allows — depth is the goal.

## Inputs

Accept any combination of:
- Local file paths (source code, markdown docs, OpenAPI/Swagger specs, config files)
- Pasted text (README, architecture notes, API docs)
- A topic or product name (research from general knowledge)
- A URL (fetch and analyze if possible)

If the user provides a directory, scan key files: `README*`, `ARCHITECTURE*`, `docs/`, entry-point source files, config files (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, etc.).

## Output

Use the report template at [assets/report-template.md](assets/report-template.md) as the structure for every report.

**Output location:**
- If the user specifies a path, write the report there
- Otherwise, write to `./deep-dive-{subject}.md` in the current working directory (replace spaces with hyphens, lowercase)

Fill in all template sections that are relevant to the material. Skip sections where there is genuinely nothing to say. Always include at least: Overview, Architecture, and Further Reading.

Section-specific guidance:
- **Architecture**: label diagram arrows with protocol/data type; group by layer; include external dependencies
- **Data Model**: only include if the system has a meaningful schema or domain model
- **Core Flows**: pick the 2–4 most important user journeys; one sequence diagram each
- **API Reference**: group endpoints by resource; note auth mechanism, pagination, versioning
- **Further Reading**: 5–8 items, ordered most-to-least important, each with a concrete location (file path, URL, or search term)

---

## Quality Standards

- **Depth over breadth**: detailed analysis of the most important parts beats shallow coverage of everything
- **Concrete over abstract**: use actual class names, file paths, endpoint names from the material — not generic placeholders
- **Accurate diagrams only**: if you lack enough information to make a diagram correct, omit it and say what's missing
- **Honest gaps**: if a section cannot be filled, write one sentence explaining what additional material is needed
- **Developer-first language**: assume a competent reader; skip basics, focus on what is non-obvious