# deep-dive

A Kiro agent skill that analyzes codebases, documentation, APIs, or product specs and produces a structured technical report for developers.

## Architecture

![Architecture](assets/deep-dive-architecture.svg)

## Workflow

![Workflow](assets/deep-dive-workflow.svg)

## What it does

Given any technical material — source code, README, OpenAPI spec, pasted docs, or just a topic name — the agent produces a detailed Markdown report covering:

- System overview and design philosophy
- Architecture diagram (PlantUML)
- Key concepts & terminology glossary
- Data model with ER diagram
- Core flows with sequence diagrams
- API / interface reference
- Configuration & deployment notes
- Extension and integration points
- Observability (logging, metrics, tracing)
- Known limitations and trade-offs
- Actionable further reading recommendations

## When to Use

Activate this skill when a developer says things like:
- "help me understand this codebase"
- "deep dive into X"
- "onboard me to this service"
- "how does X work"
- "analyze this doc / spec"
- "详细分析 X 架构 / 部署流程"

## Accepted Inputs

| Input type | Example |
|---|---|
| File path(s) | `src/`, `docs/api.yaml`, `main.go` |
| Pasted text | README content, architecture notes |
| Topic name | "Kafka consumer groups", "Redis internals" |
| URL | Link to documentation or spec |

When given a directory, the skill automatically scans `README*`, `docs/`, entry-point files, and package manifests.

## Example Prompts

```
Give me a deep dive on the Kafka consumer group rebalancing protocol.
```

```
Analyze this FastAPI service and explain how it works: [paste README]
```

```
Help me understand the worker pool in src/worker/pool.go
```

## File Structure

```
skills/deep-dive/
├── SKILL.md
├── README.md                  # this file
├── assets/
│   ├── report-template.md
│   ├── workflow.puml
│   └── deep-dive-workflow.svg
└── evals/
    └── evals.json
```

## Evals

```bash
python scripts/run_evals.py deep-dive
```