/reverse-engineer

name: reverse-engineer
description: 'Tear down an authorized competitor repo, binary or product into a feature inventory and adoption choices. Use when: comparing an external system; local questions go to Research.'
practices:
- legacy-code-seams
- ddd-bounded-context
- adr
hexagonal_role: supporting
consumes: []
produces:
- '.agents/scratch/reverse-engineer/*/'
context_rel: []
skill_api_version: 1
user-invocable: true
context:
  window: fork
  intent:
    mode: task
  sections:
    exclude:
    - HISTORY
metadata:
  dependencies: []
  capabilities: [reverse_engineer]
  effects: [clone_upstream_repo, authorized_binary_execution, write_teardown_artifacts]
  canonical_status: canonical
  disposition: keep_specialist
  tier: execution
  internal: false
output_contract: validated phase-1 teardown directory, followed by a caller-authored and validated phase-2 steal-map.md

Reverse Engineer

Reverse-engineer an external system into two things: a **mechanically-verifiable teardown** (feature inventory + registry + specs, optionally a security audit) and a **steal-map** — what to adopt into our surfaces, what to leave behind. The teardown is the evidence; the steal-map is the decision. Separating them works because a decision row that must cite a registry entry can be re-checked by anyone, while a decision made from impressions cannot be re-checked by its own author. The original failure mode this skill exists to prevent: reading a competitor's README and "deciding" from vibes.

**Triggers:** "reverse-engineer X", "tear down Y", "what should we steal from Z", "evaluate competitor/upstream", "should we fork/adopt/build-native".

Prompt

Reverse-engineer the beads CLI (github.com/steveyegge/beads, tag v2.1.0)
in repo mode, then author steal-map.md comparing its dependency-graph
reconciler against our cli/internal/gates/ package. I own this analysis
and have authorization for the clone.

It's working if

Observable in the trace, without reading the prose:

• `feature-registry.yaml` and `clone-metadata.json` land under

`.agents/scratch/reverse-engineer/<product>/` with the resolved upstream commit recorded.

• Every `steal-map.md` row cites a teardown registry entry and our

matching surface, using the full `have`/`gap`/`steal`/`park`/`reject` set.

• `bash skills/reverse-engineer/scripts/validate-output.sh --output-dir

"$output_dir" --phase complete` exits 0 before handoff.

• A one-way-door adoption row is routed to Plan instead of decided

inside `steal-map.md`.

⚠️ Constraints — Hard Guardrails (MANDATORY)

• Only operate on code/binaries you own or have **explicit written authorization** to analyze — this matters because unauthorized teardown is the legal/IP line.
• Do not provide steps to bypass protections/ToS or to extract proprietary source/system prompts.
• Do not output reconstructed proprietary source or embedded prompts (index only; redact in reports) — to prevent reproducing protected IP.
• Redact secrets/tokens/keys if encountered; run the secret-scan gate over outputs to prevent credential leakage.
• Always separate **docs say** vs **code proves** vs **hosted/control-plane**.

Phase 1 — Mechanical teardown (the script)

Produce evidence, not vibes. The script clones (pinned), scans CLI/config/artifact surface, and writes a feature inventory + machine-checkable registry + spec set.

python3 skills/reverse-engineer/scripts/reverse_engineer.py <product> --mode=repo \
  --upstream-repo="https://github.com/org/repo.git" --upstream-ref=v1.0.0 \
  --output-dir=".agents/scratch/reverse-engineer/<product>/"

Binary mode requires `--authorized` (see Invocation Contract + Self-Test). Use the bundled demo fixture if you lack authorization for a real binary.

Phase 2 — The steal-map (the decision)

Map each capability the teardown found onto **our** surfaces. This is the part that turns research into a decision. Emit `.agents/scratch/reverse-engineer/<product>/steal-map.md` with a table; every row cites the teardown evidence **and** the matching surface in our repo.

The mechanical script intentionally stops after validating Phase 1. It cannot truthfully decide whether our live tree has, lacks, or should adopt a capability. The caller authors `steal-map.md` from the generated registry plus a fresh read of our repository, then runs the complete-output validator below. A missing or malformed map is therefore an incomplete skill result, not a script success silently relabelled as a decision.

| Their capability | Our surface today | Verdict | |---|---|---| | `<feature>` | `<our file / skill / CLI, or "none">` | **have** / **gap** / **steal** / **park** / **reject** |

Verdict rules (hard-won — apply them, do not skip):

• **steal** — we lack it and it advances our core. Steal the *pattern*, not the storage engine: re-express in our primitives, never vendor their runtime.
• **park** — real, but it's substrate we deliberately delegate (e.g. orchestration per ADR-0009) or downstream of an unproven bet. Name it, don't build it.
• **reject** — it conflicts with our doctrine (e.g. a self-reported completion edge where we require a verdict — "no verdict = not done").
• **have** — we already do this; confirm it still holds, move on.
• **gap** — we should have it and don't. These are the steal candidates.

Discipline that makes the map trustworthy:

• **Independently checked, not self-report.** Get facts on *how* they implement

each capability from code, cross-checked by a fresh reader — never from a README or one context's summary. Model family is optional metadata, not a trust requirement.

• **Probe the real state, don't argue from stale.** Re-verify our side against the live tree before calling something a gap; every "X is missing" carries the search that proved it.
• **The steal is the pattern, not the platform.** Their robustness is usually one idea (unification, a gate, a reconcile loop). Steal the idea; leave the scaffolding.

Route one-w