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:

If found, run the decompiler router before any source analysis:

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:

Step 8 — Generate BDD feature stubs

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

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.