---
name: reverse-engineer-electron
description: Reverse-engineer Electron apps by creating a runnable modified-app workspace, deterministically unminifying code without behavior change, decomposing modules, and iteratively renaming modules with runtime debugging and human verification gates.
---

## Purpose

Reverse-engineer a target Electron app while preserving behavior at every stage.

The workflow is resumable. Do not assume a fresh workspace. Detect current state, continue from there.

## Non-Negotiable Rules

- Behavior preservation is mandatory in every step.
- Any transformation must be deterministic and semantics-preserving.
- Every hard gate is human-verified.
- No app-specific assumptions in the process itself. Adapt to each app's actual structure.
- All semantic renaming is strictly gated behind active debugger connections through the electric-cherry MCP server.
- If CDP and V8 are not both connected, do not perform any renames.
- All semantic renaming is strictly gated behind deterministic unminification of the target file first.
- Renaming on minified files is completely forbidden.

## Canonical Process

### 1. Project Setup: Create a Runnable Modified-App Workspace

Goal: run the app using modified resources from the workspace.

What to establish:

- A workspace layout that mirrors how the target app actually loads resources.
- A reliable run path that uses modified code/resources, not untouched upstream assets.
- A reproducible launch method suitable for iterative reverse engineering.

Allowed setup patterns (choose the one that works for the app):

- Run from extracted resources directly.
- Run from a dev build/compile flow when the app supports it.
- Repack changed resources back into an asar and run from a copy of the app bundle.

Preferred reliability fallback:

- Repack into asar and run from a copied app bundle when direct-extracted runtime is fragile.

Outcome required:

- You can launch the app with modified resources applied.

### Gate 1 (Hard, Human Verified)

Proceed only after recorded human approval for this gate.

### 2. Deterministic Unminification (No Behavior Change)

Goal: make code readable while preserving exact behavior.

Requirements:

- Apply deterministic formatting/unminification only.
- Do not alter control flow, data flow, logic, side effects, or ordering.
- Do not introduce refactors during this stage.

Outcome required:

- Code is consistently unminified/readable with behavior unchanged.

### Gate 2 (Hard, Human Verified)

Proceed only after recorded human approval for this gate.

### 3. Module Decomposition (No Behavior Change)

Goal: split/organize into modules while preserving behavior.

Requirements:

- Decompose according to actual dependency and execution structure.
- Preserve all runtime behavior and boundaries.
- Produce a dependency hierarchy that can drive rename order.

Outcome required:

- Modules are separated and dependency relationships are clear.

### Gate 3 (Hard, Human Verified)

Proceed only after recorded human approval for this gate.

### 4. Iterative Semantic Reverse Engineering

Goal: rename modules and symbols semantically, one module at a time, with runtime evidence.

Absolute precondition:

- Connect via electric-cherry MCP to both:
- CDP debugger (renderer)
- V8 debugger (main process)
- If either connection is missing, stale, or broken, renaming is forbidden until both are reconnected.
- Ensure the target file was deterministically unminified first (for example via Prettier).
- If the file is still minified, renaming is forbidden.
- Debugger connections must remain active while rename work is being performed. If a connection drops, stop renaming immediately.

Per-iteration workflow:

- Launch the app.
- Attach CDP debugger (renderer) and V8 debugger (main process).
- Choose next module by dependency order:
- First preference: module with no dependents.
- If none exist (for example circular graph), choose module with the least dependents.
- If multiple modules are tied for least dependents, break the tie by flipping a coin.
- Perform semantic renaming for that module using runtime/static evidence.
- If needed, perform safe cross-module rename updates required by dependency links.
- During this stage, non-rename logic edits are forbidden.

Hard rule per module:

- After every single module rename, stop for human verification before continuing.

### Gate 4 (Hard, Human Verified, Repeats Every Module)

Proceed only after recorded human approval for each module gate.

Then proceed to the next module.

### 5. Completion

Continue until every module has semantic names and the app remains functionally correct.

Done criteria:

- All modules renamed semantically.
- No unresolved modules remain in the dependency hierarchy.
- Final recorded human approval is present.

## Resume Expectations

This process is explicitly resumable from any stage.

On resume:

- Detect which stage is already complete.
- Continue from the next incomplete stage.
- Never reset progress just because workspace is not at step 0.

## Failure Protocol

- If any gate or rename step fails, wait for human instructions and follow them exactly.
- Restarting the app or continuing work is gated on recorded human approval.
- Before continuing semantic renaming after a failure, both CDP and V8 debugger connections must be active again.

## What This Skill Must Never Do

- Assume a fresh empty workspace.
- Require arbitrary artifact-based "gates" as proof of progress.
- Tie the process to one app's structure.
- Skip human verification at hard gates.
- Perform semantic renaming without active CDP and V8 connections through electric-cherry MCP.
- Perform semantic renaming on minified files.
- Perform non-rename logic edits during iterative semantic renaming.