Structure Analysis — Reverse Engineering Phase 1

Analyze the target codebase structure exhaustively. Identify ALL entry points, dependencies, modules, and components within the user-specified scope. Produce a structure map document and initialize manifest.json for pipeline chaining.

Three Principles

These principles are non-negotiable. Violating any principle invalidates the analysis.

1. Code is Truth

• Document what IS implemented, not what SHOULD be implemented
• If code appears buggy, document the behavior as-is and note it in the Question List
• Prioritize actual code over comments, variable names, or documentation

2. Traceability to Line

• Every finding MUST include a file:line reference
• If a line number cannot be determined, exclude the finding and note it in the Question List
• References without line numbers are considered hallucination

3. Behavior over Intent

• Focus on observable behavior: inputs, outputs, side effects
• Do NOT infer business intent or “why” from code
• Document “what” and “how” only

Execution

Step 1: Setup

Determine analysis name:

• Use the name argument if provided
• Otherwise derive from target: class name, directory name, or file stem

Detect language:

• If language argument is provided, use it
• Otherwise detect from file extensions and project files:
  • .cs / *.csproj → csharp
  • .py / pyproject.toml / setup.py → python
  • .ts / .tsx / package.json with typescript → typescript
  • .java / pom.xml / build.gradle → java
  • Other → generic

Load language reference:

• Check if references/{language}.md exists in this skill’s directory
• If it exists, read and apply the language-specific patterns
• If not, proceed with language-agnostic analysis

Detect tool availability:

• Check if Serena MCP tools are available (mcp__serena__find_symbol, etc.)
• If available, use Serena as primary analysis tools
• If not, use Read, Grep, Glob, Bash exclusively

Create output directory and manifest:

mkdir -p docs/reverse/{name}
mkdir -p docs/reverse/{name}/verification

Initialize manifest.json:

{
  "name": "{name}",
  "language": "{detected-language}",
  "created": "{YYYY-MM-DD}",
  "updated": "{YYYY-MM-DD}",
  "targets": {
    "entry_points": ["{user-specified targets}"],
    "classes": ["{extracted class names}"],
    "specified_by": "user"
  },
  "phase1": {
    "status": "in_progress",
    "output": null,
    "verification": null,
    "targets_for_phase2": []
  },
  "phase2": {
    "status": "pending",
    "completed": [],
    "remaining": [],
    "targets_for_phase3": []
  },
  "phase3": {
    "status": "pending",
    "completed": [],
    "remaining": []
  },
  "phase4": {
    "status": "pending",
    "output": null,
    "verification": null
  }
}

Step 2: Entry Point Detection

Identify all entry points within the target scope.

With Serena:

mcp__serena__get_symbols_overview(relative_path="{target}", depth=1)
mcp__serena__find_symbol(name_path_pattern="Main|main|__main__|app")

Without Serena:

• Use Grep to search for entry point patterns from the language reference
• Use Read to examine candidate files
• Use Glob to find project configuration files

For each entry point, record:

• File path (relative to workspace root)
• Line number
• Function/method name
• Purpose (derived from code, not inferred)

Step 3: Dependency Mapping

Identify dependencies within the target scope.

Package/library dependencies:

• Read project configuration files (language-specific: *.csproj, pyproject.toml, package.json, pom.xml)
• List external dependencies with versions

Internal module dependencies:

• Trace imports/using statements from the target files
• Build a dependency graph

Produce Mermaid diagram:

graph TD
    ModuleA --> ModuleB
    ModuleA --> ExternalLib
    ModuleB --> ModuleC

Mermaid syntax rules (prevent parse errors):

• No special characters in text (!=, >=, [], ())
• No array/generic syntax (byte[], List<string> → byte array, string list)
• No method call parentheses (Method() → Method)
• Use quotes for node text with spaces: A["Node text (L45)"]

Step 4: Module and Component Listing

List ALL classes, interfaces, functions, and significant components within the target scope.

With Serena:

mcp__serena__search_for_pattern(
    substring_pattern="class |interface |def |function ",
    restrict_search_to_code_files=true
)
mcp__serena__get_symbols_overview(relative_path="{directory}", depth=2)

Without Serena:

• Use Grep to find class/function definitions
• Use Read to examine each file
• Use Glob to enumerate source files

For each component, record:

CRITICAL: List ALL components. Selecting only “important” ones is prohibited. Partial listing invalidates the analysis for downstream phases.

Step 5: Build Phase 2 Target List

From the component list, identify classes/modules that contain methods requiring logic visualization:

• Classes with business logic methods
• Handlers/controllers with processing flows
• Services with complex operations

For each, record:

{
  "class": "OrderService",
  "file": "src/services/order.py",
  "methods": ["process_order", "validate_order", "calculate_total"]
}

Step 6: Generate Output

Write structure map to docs/reverse/{name}/01-structure-map.md:

# Structure Map: {name}

**Analysis Date**: {YYYY-MM-DD}
**Target**: {relative path}
**Language**: {language}
**Framework**: {detected framework and version}
**Confidence**: {High / Medium / Low}

**Important**: All paths are relative to workspace root.

## Technology Stack

### Framework and Language
| Component | Version | Source |
|:----------|:--------|:-------|
| {language} | {version} | {file:line} |

### Dependencies
| Package | Version | Purpose | Source |
|:--------|:--------|:--------|:-------|
| {package} | {version} | {purpose} | {config-file:line} |

## Directory Tree

{tree output with functional annotations}

## Entry Points

| Entry Point | File:Line | Purpose | Evidence |
|:------------|:----------|:--------|:---------|
| {name} | [{file}:{line}]({file}:{line}) | {purpose} | Line {N} |

## Dependency Diagram

```mermaid
graph TD
    ...

Module and Component List

{Category} (e.g., Services, Handlers, Models)

Question List

Unconfirmed Findings

• [Unconfirmed] {description} — {file}:{line}

Suspected Issues

• [Suspected Bug] {description} — {file}:{line}

Analysis Constraints

Confidence Factors

• Code comments: {sparse/moderate/rich}
• Test coverage: {estimated %}
• Architecture patterns: {observed patterns}

Evidence Strength

• ✅ Strong: Implementation + tests + clear behavior
• ⚠️ Medium: Implementation + partial tests
• ❌ Weak: Implementation only, inferred from structure

**Update manifest:**
- Set `phase1.status` to `"completed"`
- Set `phase1.output` to `"01-structure-map.md"`
- Populate `phase1.targets_for_phase2` with the Phase 2 target list
- Update `phase2.remaining` with all component names from targets_for_phase2
- Update `updated` timestamp

## Validation Before Completion

Before writing output, verify:

- [ ] Every finding has a `file:line` reference
- [ ] No speculative content (all claims verifiable in source)
- [ ] Mermaid diagrams use valid syntax (no special characters)
- [ ] All file paths are relative to workspace root
- [ ] Component list is exhaustive within target scope
- [ ] manifest.json is valid JSON with all required fields
- [ ] `targets_for_phase2` contains entries for all components with analyzable methods

## Prohibited Actions

- Do NOT execute code or run build commands
- Do NOT infer business logic from variable names alone
- Do NOT add components not present in the source code
- Do NOT modify any source files
- Do NOT include absolute file paths in output