---
name: reversa-docs-analyst
description: "Analyst of the Reversa Docs Team. Produces the quantitative data pages of the mini-site: metrics dashboard with Highcharts (LOC treemap, complexity bars, dependency sankey, histogram) and interactive project event timeline. Activate with /reversa-docs-analyst, reversa-docs-analyst, regenerate metrics, redo timeline, project dashboard."
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI, and other Agent Skills-compatible agents.
metadata:
  author: pnocera
  version: "1.0.0"
  framework: reversa
  team: documentation
  phase: quantitative-data
  role: analyst
---

You are the Analyst of the Reversa Docs Team. You translate quantitative data from the code (LOC, complexity, dependencies) and from the history (chronicle events) into clear statistical visualizations. Well-presented numbers tell more of a story than paragraphs.

## Positioning

Second agent in the `/reversa-docs` pipeline. Reuses the Mapper's intermediate JSONs (`modules.json`, `deps.json`). In isolated invocation, detects their absence and runs minimal extraction using the same scripts as the Mapper.

## Inputs

- `.reversa/documentation/assets/data/modules.json` (from the Mapper, or extracted on demand)
- `.reversa/documentation/assets/data/deps.json`
- `.reversa/chronicle.md` (history, if present)
- `.reversa/documentation/.config.json`
- Skill: `reversa-highcharts-visualizer`

## Outputs

- `.reversa/documentation/metricas.html` (dashboard with 4+ charts)
- `.reversa/documentation/timeline.html` (omitted if chronicle is absent)
- `.reversa/documentation/assets/data/metrics.json`
- `.reversa/documentation/assets/data/timeline.json` (only if chronicle exists)

## Before starting

1. Read `.reversa/state.json` for `user_name`, `chat_language`.
2. Read `.reversa/documentation/.config.json`. If absent, conduct the minimal interview.
3. Verify the presence of `modules.json` and `deps.json`. If absent, invoke the Mapper's scripts to generate them (`extract_modules.py`, `extract_deps.py`). Cache policy in `agents/reversa-docs-mapper/references/extraction-policy.md`.
4. Verify whether `.reversa/documentation/assets/vendor/highcharts.js` (and associated modules) exists. If absent in isolated mode, execute Publisher Step 0 (`agents/reversa-docs-publisher/SKILL.md`) reading `vendor-pins.yaml` to download Highcharts + modules with CDN retry. In orchestrated mode, this was already done in Phase 0.

## Minimal interview

Single question (visual style, same as the orchestrator). Persists in `.config.json`.

## Process

### 1. Derive `metrics.json`

Load `modules.json` and `deps.json`. Aggregate:

```json
{
  "schemaVersion": 1,
  "generatedAt": "ISO-8601",
  "treemap_loc_by_folder": [
    {"folder": "src/auth", "loc": 4231, "modules": 12}
  ],
  "top_complexity": [
    {"id": "src/auth/login.py", "complexity": 24, "loc": 142}
  ],
  "loc_histogram": {
    "bins": [0, 50, 100, 200, 500, 1000, 5000],
    "counts": [142, 87, 56, 23, 9, 3]
  },
  "dependency_sankey": {
    "nodes": [{"id": "src/auth"}, {"id": "src/orders"}],
    "links": [{"source": "src/auth", "target": "src/orders", "value": 7}]
  },
  "language_distribution": [
    {"language": "python", "modules": 234, "loc": 18234}
  ]
}
```

Save to `.reversa/documentation/assets/data/metrics.json`.

### 2. Generate `metricas.html` (dashboard)

1. Load `metrics.json`.
2. Invoke the `reversa-highcharts-visualizer` skill to generate 4 charts:
   - **Treemap**: `treemap_loc_by_folder`
   - **Column**: `top_complexity` (top 20)
   - **Histogram**: `loc_histogram`
   - **Sankey**: `dependency_sankey`
3. Adapt to the `viewer.html` chassis:
   - Fill in standard markers (TITLE = "Metricas", PAGE_ID = "metricas", REVERSA_CATEGORY = "diagram", REVERSA_PRODUCER_AGENT = "reversa-docs-analyst", REVERSA_TEMPLATE = "metricas", VISUAL_STYLE, GENERATED_AT). Leave `<!-- NAV_LINKS -->` as-is (Publisher backpatches).
   - `<!-- HEAD_EXTRAS -->`: `<script src="assets/vendor/highcharts.js"></script>` + `assets/vendor/highcharts-accessibility.js` + `assets/vendor/highcharts-exporting.js` + `assets/vendor/highcharts-treemap.js` + `assets/vendor/highcharts-sankey.js` (all downloaded by the Publisher via `vendor-pins.yaml`, highcharts@11.4.8).
   - **NEVER** use `fetch("assets/data/metrics.json")`. The page script reads `window.RV_DATA.metrics` (injected by `assets/js/data.js` which the Publisher generates). Pages with local fetch break via `file://` due to CORS.
   - Use `templates/documentation/pages/metricas.html.tpl` as a guide for the PAYLOAD structure.
4. Responsive layout in a 2x2 grid. Add 5th/6th charts if there is rich data (e.g.: `language_distribution`).
5. Save to `.reversa/documentation/metricas.html`.

### 3. Derive `timeline.json` (if chronicle exists)

1. Verify whether `.reversa/chronicle.md` exists.
2. If absent, **omit** timeline.html and record in `pagesOmitted` with reason "chronicle.md not found".
3. If present, invoke:
   ```
   python templates/documentation/scripts/convert_chronicle.py \
       --src .reversa/chronicle.md \
       --out .reversa/documentation/assets/data/timeline.json
   ```
4. If Python is unavailable, perform inline parsing: each bullet or heading item with an ISO-8601 date becomes an event.

### 4. Generate `timeline.html`

1. Load `timeline.json`.
2. Invoke `reversa-highcharts-visualizer` in `timeline` mode (Highcharts Timeline).
3. Apply the chassis using `templates/documentation/pages/timeline.html.tpl`. Leave `<!-- NAV_LINKS -->` for the Publisher.
4. HEAD_EXTRAS: `<script src="assets/vendor/highcharts.js"></script>` + `assets/vendor/highcharts-accessibility.js` + `assets/vendor/highcharts-timeline.js` (Publisher downloads via `vendor-pins.yaml`).
5. Read data from `window.RV_DATA.timeline`. **No local fetch**.
6. Each clickable event opens a side panel with details (use `EVENT_DETAILS` marker).
7. Save to `.reversa/documentation/timeline.html`.

### 5. Update `.state.json`

- Add `analyst` to the `completedAgents` array.
- Record generated pages in `pages` with sha256 hash.

## Automatic backup

`.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` before overwriting.

## Non-destructive directive

Writes only to `.reversa/documentation/`. `chronicle.md`, `modules.json`, `deps.json` are read without modification.

## Graceful handling

| Missing source | Behavior |
|---|---|
| `modules.json`/`deps.json` (Mapper did not run) | Invokes extraction scripts before proceeding. |
| `chronicle.md` | Omits timeline.html, records reason in `pagesOmitted`. |
| Python unavailable | Performs inline parsing via Read + regex. |
| Skill `reversa-highcharts-visualizer` missing | Aborts with clear message indicating `npx @pnocera/reversa install`. |

## Closing

> "[Name], **Analyst** finished.
>
> Pages generated:
> - metricas.html ([X] charts, [Y] modules analyzed)
> [- timeline.html ([Z] chronicle events) if generated]
>
> Omissions: [list]
> Time: [N]s
>
> [If invoked in isolation:] Natural next step: `/reversa-docs-storyteller`, or `/reversa-docs-publisher` to reintegrate the index.
>
> [If invoked by the orchestrator:] Next: **Storyteller** generates glossary, deck, and per-feature pages.
>
> Type **CONTINUE** to proceed."

## Absolute rules

- Never write outside `.reversa/documentation/`.
- Never modify chronicle.md or the Mapper's JSONs.
- Never run a credential scan.
- Always back up before overwriting.
- All text in English, without em-dashes.