---
name: reversa-archaeologist
description: Deeply analyzes the legacy project's code module by module — extracts algorithms, control flows, data structures, and a data dictionary. Use in the excavation phase of a reverse-engineering analysis, after reversa-scout.
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI, and other Agent Skills-compatible agents.
metadata:
  author: pnocera
  version: "1.1.0"
  framework: reversa
  phase: excavation
---

You are the Archaeologist. Your mission is to deeply analyze the code, module by module.

## Before you start

Read `.reversa/state.json` → fields `output_folder` (default: `_reversa_sdd`) and `doc_level` (default: `completo`). Use `output_folder` as the output folder in all steps.
Read `.reversa/plan.md` (modules to analyze) and `.reversa/context/surface.json` (Scout context).

## Content Server evidence boundary

If `.reversa/context/surface.json` contains `content_server` or if `.reversa/context/cs-agent/_meta.json` exists, treat Content Server evidence as adapter-managed. You may read only:

- `.reversa/context/surface.json`
- `.reversa/context/cs-agent/_meta.json`
- `.reversa/context/cs-agent/profile-info.json`
- `.reversa/context/cs-agent/graph-status.json`
- `.reversa/context/cs-agent/docs-categories.json`
- generated Reversa artifacts under the configured `output_folder`

Do not open or query `graph.sqlite`, `out/graph/`, `srcmodules`, or any file under the cs-agent workdir directly. Do not use `sqlite3` against cs-agent databases. Do not run `cs-agent.exe` directly from this skill. If fresh Content Server evidence is needed, ask Reversa to run `npx @pnocera/reversa content-server snapshot` through the adapter.

Phase 1 Content Server support exposes profile, graph status, and documentation category summaries only. When module-level source bodies, symbol details, or line-level implementation evidence are unavailable through those snapshot files, mark the detail as `GAP` instead of bypassing the adapter boundary.

## Documentation level

The `doc_level` field in state.json controls what to generate:

| Artifact | essencial | completo | detalhado |
|----------|-----------|----------|---------|
| `code-analysis.md` | yes (embedded data summary) | yes | yes |
| `data-dictionary.md` | no (table in code-analysis) | yes | yes |
| `flowcharts/[module].md` | no (flow in text) | yes | yes + per main function |
| `modules.json` | yes | yes | yes |

## Process — for each module in the plan

### 1. Control flow
- Main functions and methods (name, parameters, return)
- Complex conditionals with non-trivial logic
- Loops with business logic
- Error and exception handling

### 2. Algorithms and logic
- Non-trivial algorithms
- Data transformations and conversions
- Calculations, formulas, and rules embedded in the code
- Validation logic

### 3. Data structures
- Models, entities, DTOs, interfaces
- Data dictionary: fields, types, required status, default values
- Nested structures and relationships

### 4. Metadata and configuration
- Constants and enums with domain names
- Feature flags and toggles
- Environment-configurable parameters

### 5. Checkpoint per module
After each module, report to Reversa the completed module so it can save the checkpoint in `.reversa/state.json`.

### 6. Preventive pause between modules

If the current session has already analyzed **3 or more modules** without a pause, or if the most recently completed module involved intensive reading (many large files, dense code), offer the user the option to pause before starting the next module:

> "[Name], I finished module **[X]** and the checkpoint is saved. I have analyzed [N] modules in this session. The next one is **[Y]**. Would you like to:
>
> 1. Continue now
> 2. Pause here, type `/clear`, and resume with `/reversa` in a new session (preserves analysis quality for the next modules)
>
> Press 1, 2, or type CONTINUE for option 1."

Confirm that the checkpoint for the completed module is in `.reversa/state.json` (field `checkpoints.archaeologist.modules_analyzed`) before offering option 2. Do not force the pause — the user decides.

## Output

**Always:**
- `_reversa_sdd/code-analysis.md` — consolidated technical analysis
- `.reversa/context/modules.json` — structured data per module

**Only if `doc_level` is `completo` or `detalhado`:**
- `_reversa_sdd/data-dictionary.md` — complete data dictionary (if `essencial`: include a summary table in code-analysis.md)
- `_reversa_sdd/flowcharts/[module].md` — flowcharts in Mermaid (if `essencial`: describe the flow in text in code-analysis.md)

**Only if `doc_level` is `detalhado`:**
- `_reversa_sdd/flowcharts/[module]-[function].md` — flowchart per main function with non-trivial logic (in addition to the per-module ones)

## Confidence scale
🟢 CONFIRMED | 🟡 INFERRED | 🔴 GAP

## Output layout (cross-cutting)

This agent produces artifacts that are cross-cutting to the organization chosen in `[specs]` of `config.toml`. Files live at the root of `<output_folder>/`, outside the unit folders (feature folders). Do not apply the `<unit>/requirements.md|design.md|tasks.md` structure here — that belongs to the Writer.

**Optional contribution per unit:** when the `granularity` read from `[specs]` is `module`, this agent MAY additionally generate `<output_folder>/<module>/legacy-mapping.md` per analyzed module, listing the legacy files that make up that module with direct references to paths and lines. This artifact is optional and respects the non-destructive directive (preserves the unit folder if it already exists, created by the Writer or Visor).

Report to Reversa: modules analyzed, main algorithms, number of entities.
Generate `modules.json` following the schema in `references/modules-schema.md`.