# Retro Engineer

> Use to perform automated structural analysis of a codebase — runs tools/retro/main.py, produces retro-report.md, and delegates to hardware-analyst for any hardware-domain signals. The fast, tool-assisted path for reverse engineering.

- Skill: `deagentic/retro-engineer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add deagentic/retro-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deagentic/retro-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: deagentic (https://skillmd.com/u/deagentic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deagentic/retro-engineer

---

Perform a comprehensive reverse engineering analysis of the codebase.

Target path: $ARGUMENTS (use current working directory if not provided)

---

## What you will produce

1. **Technology Stack** — language(s), build system, platform, hardware APIs
2. **Architecture Map** — directory tree, modules, entry points, public API surface
3. **Call Tree** — who calls whom, from entry points down to hardware APIs
4. **External API Inventory** — every system/hardware API call with location and arguments
5. **Software Decision Log** — every hardcoded constant, protocol byte, timing choice, threading decision
6. **Cross-platform Porting Notes** — what must change to run on a different OS

---

## Execution Steps

### Step 1 — Run the automated analysis tool (if available)

Check if `tools/retro/main.py` exists relative to the target path or in the current working directory.

If it exists, run:
```
python tools/retro/main.py <TARGET_PATH> --output retro-report.md --json
```

Read the generated `retro-report.md` and `retro-report.json`.

If the tool does NOT exist, proceed with manual analysis below.

---

### Step 2 — Technology detection (if running manually)

**Binary artifact check (run first):** Scan for compiled artifacts before reading source:

| Glob pattern | Type | Decompiler |
|---|---|---|
| `**/*.dll`, `**/*.exe` | .NET / VB.NET | `ilspycmd` |
| `**/*.jar`, `**/*.class` | Java bytecode | CFR → Procyon fallback |
| `**/*.pyc` | Python bytecode | `decompyle3` → `uncompyle6` fallback |

If found, run the decompiler router before any source analysis:
```bash
python tools/software/discovery/decompiler_manager.py <file>
# Decompiled source → output/decompiled/<language>/<stem>/
```

Then continue analysis against the decompiled output.

Use Glob to find files by extension. Count occurrences to determine primary language:
- `**/*.py`, `**/*.c`, `**/*.cpp`, `**/*.cs`, `**/*.java`, `**/*.go`, `**/*.rs`, `**/*.js`, `**/*.ts`

Use Grep to find hardware/system API patterns:
- `SCardEstablishContext`, `SCardConnect`, `SCardTransmit`, `SCardControl`
- `WinSCard`, `pcsclite`, `libnfc`, `libusb`, `hidapi`
- `CreateFile`, `DeviceIoControl`, `RegisterDeviceNotification`

Use Glob to find build/config files:
- `CMakeLists.txt`, `Makefile`, `package.json`, `*.csproj`, `setup.py`, `Cargo.toml`

---

### Step 3 — Structure mapping

Use Glob to list all source files.

For each source file, use Read to extract:
- `import` / `#include` / `using` statements
- Class definitions
- Function/method definitions and their signatures
- Entry points (`main`, `WinMain`, `if __name__ == '__main__'`, etc.)

Build a module dependency map from the import statements.

---

### Step 4 — Call tree generation

For each function found in Step 3, use Grep to find:
```
<function_name>\s*\(
```
inside the codebase. This reveals who calls that function.

Trace from entry points downward. Stop at:
- External API calls (WinSCard, OS calls, etc.)
- Maximum depth of 8

Present as an indented tree:
```
main()
  └─ initialize()
       └─ SCardEstablishContext()   [WinSCard]
  └─ read_card()
       └─ SCardConnect()            [WinSCard]
       └─ SCardTransmit()           [WinSCard]
```

---

### Step 5 — External API inventory

Use Grep for each known API function. For every match, record:
- File path and line number
- The full line (to see arguments)
- The surrounding context (2 lines before/after)

Group by API family (WinSCard, WinAPI, libnfc, libusb, etc.)

---

### Step 6 — Software decision extraction

Use Grep to find:

**Hardcoded constants and byte sequences:**
```
0x[0-9A-Fa-f]{4,}
```

**Timing decisions:**
```
(?i)(timeout|delay|sleep|wait|interval)\s*[=:]\s*\d+
```

**Intent comments:**
```
(?i)(TODO|FIXME|HACK|WORKAROUND|NOTE|BUG|IMPORTANT)
```

**PC/SC share mode choices:**
```
SCARD_SHARE_(SHARED|EXCLUSIVE|DIRECT)
```

**Card disposition choices (critical for the RF field timing issue):**
```
SCARD_(LEAVE_CARD|RESET_CARD|UNPOWER_CARD|EJECT_CARD)
```

For each match: document what it is, where it is, and WHY it matters.

---

### Step 7 — Cross-platform analysis

For every Windows-specific API found, provide the Linux equivalent:

| Windows | Linux | Notes |
|---------|-------|-------|
| `winscard.dll` | `libpcsclite` | Same function names |
| `SCARD_*` constants | Same (pcsc-lite) | Header: `PCSC/winscard.h` |
| `SCardControl` escape | Same (pcsc-lite) | Works with ACR122U |
| `CreateFile` (device) | `open()` or `libusb_open()` | Different device paths |
| `DeviceIoControl` | `ioctl()` | Different signature |
| `RegisterDeviceNotification` | `libudev` | Different event model |

---

### Step 8 — Generate BDD feature stubs

For each major hardware operation found, generate a Gherkin stub:

```gherkin
Feature: <operation name>
  As a user of the NFC system
  I want to <action>
  So that <outcome>

  Scenario: <happy path>
    Given <precondition>
    When <action>
    Then <expected result>

  Scenario: <failure path>
    Given <precondition>
    When <failure condition>
    Then <expected error handling>
```

---

## Output format

Present results in this order:
1. **Tech Stack Summary** (table)
2. **Directory Tree** (condensed)
3. **Entry Points** (list)
4. **Call Tree** (indented tree from each entry point)
5. **External API Calls** (table: function | file | line | purpose)
6. **Software Decisions** (table: decision | location | impact)
7. **Cross-platform Porting Notes**
8. **BDD Feature Stubs**

Save full report to `retro-report.md` in the target directory.
Save call graph to `retro-report.dot` (Graphviz format).

---

## Special focus for hardware event handlers

If WinSCard / PC/SC APIs are detected, pay extra attention to:

1. **RF field control** — is `SCardControl` used to send escape commands to the reader?
2. **Transaction wrapping** — are `SCardBeginTransaction` / `SCardEndTransaction` used?
3. **Card disposition** — what value is passed as `dwDisposition` to `SCardDisconnect`?
4. **Polling loop** — how is `SCardGetStatusChange` used? What timeout?
5. **APDU commands** — what byte sequences are sent via `SCardTransmit`?
6. **Error recovery** — what happens on `SCARD_E_NO_SMARTCARD` or `SCARD_W_REMOVED_CARD`?

These six points are the difference between a card being readable for milliseconds vs. seconds.

## Collaboration & Learning Mandate

You are part of a unified, evolving agent team operating inside the Cornerstone
repository. You **MUST** follow these principles in every session:

1. **Share the Knowledge:** When you learn a domain quirk, solve a recurring
   issue, or find a reusable workaround, update the `learning-protocol` or your
   own `SKILL.md`. Knowledge hoarding is an anti-pattern.
2. **Domain Specialization:** Do not hallucinate skills outside your domain.
   If a task falls outside your expertise, delegate to the appropriate
   specialist agent — do not attempt it yourself.
3. **Use and Improve:** Before solving a problem, check whether another agent's
   `SKILL.md` already covers it. If an existing skill is flawed or incomplete,
   **refactor and improve that `SKILL.md`** rather than bypassing it.
4. **Just-In-Time Instantiation:** Be invoked exactly when your specific domain
   context is needed. Avoid accumulating massive monolithic contexts.

> Authority: `AGENTS.md § 1b — Collaborative Agentic Philosophy`.
> These rules apply to every agent, every session, no exceptions.