Reverse Engineering C and C++ modules into validated use-case, module, and C++-to-Java migration artifact packages. Generates evidence-backed traces, sequence/class/state/activity/architecture diagrams, entry-point/interface/data/business-rule/error/concurrency catalogs, parity mappings, risks, tests, reviews, and coverage; exhaust mind_mcp and graph_mcp before Serena, and use native source tools only as a final fallback.
Reverse-engineer behavior from evidence, not symbol-name guesses. FalkorDB plus Qdrant Graph-RAG is the primary engine, Serena is source-level enrichment, native tools are the final gap filler. Run scripts from the skill directory with Node.js 18+.
Runtime
Select usecase, module, or migration.
Validate the catalog: npx --yes --offline --package=. hi-reverse-plan --check-catalog.
For usecase, read PROFILE-USECASE.md; for module or migration, use the generated manifest as the profile guide.
Generate the plan: npx --yes --offline --package=. hi-reverse-plan --profile <p> --module <m> [--use-case <slug>] [--condition <c>] --output <manifest> --summary. Require ARTIFACT_PLAN_GATE: PASS. Do not read ARTIFACT-CATALOG.yaml directly — the script is the capability authority.
Activate the C++ parser, FalkorDB context, and one Qdrant collection.
Require DATA_CONTEXT_GATE: PASS.
Run Graph-RAG to saturation. Semantic search seeds anchors only; graph traversal must expand those anchors into caller/callee and trigger/handler/outcome paths before Serena.
Use Serena only for retained anchors and named gaps.
Rerun the plan only when discovery adds a new use-case slug or evidenced condition.
Generate artifacts one at a time via the loop below.
Require REVERSE_PACKAGE_GATE: PASS before delivery.
For usecase, read PROFILE-USECASE.md; for module or migration, use the generated manifest as the profile guide.
Read only the technique file returned by --next for the current artifact.
Read MCP-TOOLS.md only when live metadata is ambiguous, a wrapper rejects parameters, or provider routing must be diagnosed.
Do not read ARTIFACT-CATALOG.yaml unless the planner reports a catalog error.
If a higher-priority repository instruction defines a stricter order, obey it.
Data Context Gate
Lock the data context before any analysis query. Confirm FalkorDB is active, select one C/C++ Qdrant collection from project/repository/language metadata, and validate it with a scoped semantic_search, explore_graph probe (module-local hits required). If rejected, bind the next candidate and repeat only the probe.
DATA_CONTEXT_GATE: PASS|BLOCKED
parser=cplus
graph_provider=falkordb
graph_context=active|unavailable
qdrant_collection=<validated collection or unavailable>
qdrant_context=active|unavailable
PASS is required before any discovery, tracing, mapping, glossary, or review query. Reuse it for the same repository, module, parser, and collection; re-list collections or re-run validation probes only when scope changes, context is stale, or module-local evidence fails. Every later semantic_search, explore_graph, and vertical graph traversal must use the bound collection or retained graph anchors. BLOCKED stops analysis instead of issuing unscoped queries.
PASS requires a validated collection, all applicable query families, vertical graph traversal for retained anchors, two saturation passes, and FalkorDB graph evidence. PARTIAL permits Serena only after every working Graph-RAG capability is exhausted and names the missing evidence category. BLOCKED means code evidence cannot be established; stop instead of guessing.
Never call graph_mcp.list_databases. Never hardcode or display a graph key, endpoint, port, protocol, or driver. Provider-safe calls are listed in GRAPH-RAG-PROTOCOL.md §6.
Quiet Routing
Fast-fail once per capability. Retry once only for invalid_parameters, using the callable wrapper schema.
Never echo raw backend exceptions, host, port, graph key, protocol, driver, or other infrastructure details.
Never narrate routing with phrases such as "I will retry", "marking traversal unavailable", "then use Serena", or equivalent fallback commentary.
Execute the next allowed layer silently. Show completed calls and evidence in the retrieval trace, not operational detours.
In user-facing output, summarize graph coverage only as FalkorDB + Qdrant, Qdrant only, or Graph-RAG unavailable.
Keep provider failures in internal retrieval data as normalized capability statuses.
Context Discipline
Never read the full artifact catalog during normal execution.
Keep at most one profile and one artifact technique active at a time.
Keep the loaded protocol/profile/technique in working context; do not reopen unchanged files.
Do not read templates until generating their selected artifact.
Retain Graph results as node IDs, symbols, paths, scores, and WHY summaries.
Move normalized evidence into evidence-ledger.json.
Do not repeat full code snippets after recording source locations.
Report deltas, not the complete accumulated frontier.
Use compact script output (--summary) unless diagnosing a failure.
Artifact Generation Loop
Generate one artifact at a time. Do not read all techniques selected by a profile at once.
Ask the planner for the next pending artifact:
npx --yes --offline --package=. hi-reverse-plan --next <manifest>
Compact output: ARTIFACT_ID, TECHNIQUE, OUTPUT, EVIDENCE_GAPS.
Read only that artifact's technique file.
Retrieve only the missing evidence listed in EVIDENCE_GAPS.
Generate the artifact from its template (read the template only now).
Release the technique details and continue to the next --next.
Exit 1 from --next means all artifacts are validated; proceed to the package gate.
Use-Case Bundle
Every documented use case must produce: ucXXX_<slug>.md, trace_<slug>.json, seq_<slug>_<YYYYMMDD>_v1.mmd, class_<slug>_<YYYYMMDD>_v1.mmd. The Markdown must contain ## Sequence Diagram and ## Class Diagram sections linking the exact two Mermaid files. UC bundle link checks are enforced by hi-reverse-validate-package (it verifies each use-case document links its sequence and class artifacts). If native execution is forbidden, apply the checklist manually, record ARTIFACT_GATE_MODE: manual, and never claim the hook ran.
Evidence Contract
Maintain one evidence ledger shared by all phases. Each claim records: status, graph_provider, node_ids, symbols, edges, locations, retrieved_by, serena_support, uncertainties.
PROVEN: trigger, handler, and terminal side effect connected by FalkorDB path evidence and source support.
LIKELY: at least two of the three connected; the missing bridge is named.
TENTATIVE: semantic or source evidence exists, but the executable path is not established.
REJECTED: evidence shows utility, dead path, duplicate, or unrelated module.
Gates
ARTIFACT_PLAN_GATE — catalog valid and manifest generated.
DATA_CONTEXT_GATE — FalkorDB and one Qdrant collection active.
FALKOR_GRAPH_GATE — query matrix and saturation complete.
ARTIFACT_GATE — single artifact structurally valid.
REVERSE_PACKAGE_GATE — all required profile instances validated.
Never claim completion while a required gate fails. Structural validation does not prove semantic correctness; the evidence ledger and review remain mandatory.
User Constraints
No existing documents: record mind_mcp documents: skipped by user; still run code Graph-RAG.
MCP tools only: stop after Serena and report evidence gaps without native tools.
Possible use cases: label every result; never present a name-only hit as proven behavior.
Never claim exhaustive coverage when a collection, edge family, or source area lacks evidence.
Script Reference
All commands run via npx --yes --offline --package=. <command> from the skill directory (zero dependencies, offline). Use --summary for compact output unless diagnosing.
The main agent performs blocking preflight and collection validation. Sub-agents receive the repository root, module, constraints, selected collection, Graph-RAG anchors, prior artifacts, and output path. They follow the same routing, return retrieval traces and evidence deltas, and never activate the skill directory as the Serena project.
../
wiki/en/hi-reverse-skill.md
Wiki guide
Hi Reverse Skill: Complete Guide
hi-reverse reverse-engineers a C/C++ module into validated package artifacts: use cases, traces, sequence/class/state/activity/architecture diagrams, catalogs, evidence ledger, C++→Java parity/mapping, migration waves/risks/tests, and package review.
1. This is not "read code, then draw diagrams"
hi-reverse requires behavior to be inferred from evidence, not guessed from symbol names. Graph-RAG with FalkorDB + Qdrant is the primary engine; Serena enriches at the source level; native tools are only the final fallback.
Goals:
full discovery with saturation evidence;
trace trigger → handler → outcome;
keep a claim-level evidence ledger;
generate artifacts per profile;
validate each artifact;
independent review;
package gate before delivery;
migration mapping that does not lose parity semantics.
2. Profiles
Choose one:
Profile
Goal
usecase
Reverse an observable business/use case
module
Produce a module overview/catalog/diagrams
migration
Map C++ behavior/types/interfaces to Java
The runtime requires Node.js 18+ and commands run from the skill directory using npx --yes --offline --package=..
3. Gate-driven pipeline
Loading diagram…
Required gates:
ARTIFACT_PLAN_GATE;
DATA_CONTEXT_GATE;
FALKOR_GRAPH_GATE;
ARTIFACT_GATE;
REVERSE_PACKAGE_GATE.
Do not claim completion when a required gate fails.
4. Preflight and planning commands
hi-reverse-plan --check-catalog;
read PROFILE-USECASE.md for use case, or the generated manifest profile guide for module/migration;
Do not read ARTIFACT-CATALOG.yaml directly during normal execution; the script planner is the capability authority.
5. Data Context Gate
Before any analysis query:
activate the C++ parser, usually cplus;
confirm the FalkorDB context is active;
select one C/C++ Qdrant collection;
validate the collection with a scoped semantic probe;
module-local hits must include at least two hits containing local paths/qualified names.
Record:
DATA_CONTEXT_GATE: PASS|BLOCKED
parser=cplus
graph_provider=falkordb
graph_context=active|unavailable
qdrant_collection=<validated collection or unavailable>
qdrant_context=active|unavailable
If a candidate is rejected, bind the next collection and repeat only the validation probe. Do not run a query matrix over multiple/unscoped collections.
PARTIAL only allows Serena after Graph-RAG capabilities are exhausted and missing evidence is named. BLOCKED stops code analysis.
8. Saturation
After each pass, measure:
new unique nodes/relationships;
path variants/entry candidates;
triggers/handlers/outcomes;
upstream/downstream coverage;
connected trigger-handler-outcome paths;
IPC/messages/external modules;
states/modes/guards;
use-case candidates;
remaining gaps.
Only pass saturation after two consecutive passes add no material high-confidence items. A stable candidate count is not enough if paths/errors/messages/states are still growing.
9. Serena enrichment
Only start after FALKOR_GRAPH_GATE: PASS or PARTIAL:
serena.initial_instructions once;
activate the target repository root;
symbols overview on Graph-RAG files;
find retained classes/symbols;
bodies only for key triggers/guards/handlers/outcomes/gaps;
## Sequence Diagram linking the exact sequence file;
## Class Diagram linking the exact class file;
actor/trigger/precondition/mode/guard;
main flow with symbol/node/relation/state/evidence;
alternate/error/timeout/recovery;
postconditions/side effects;
IPC/callback/shared-state uncertainties;
retrieval trace/saturation/gaps;
artifact gate/version history.
hi-reverse-validate-package --update checks bundle links and the package gate.
13. Module and migration artifacts
Module
Usually includes:
module map/overview;
entrypoint/interface catalog;
class/state/activity/architecture diagrams;
data dictionary/business rules/errors/concurrency;
tests/review/open questions.
Migration
Generate only after the module package is structurally valid and evidence-reviewed. Requires:
behavioral parity;
type mapping;
interface/IPC mapping;
migration waves;
risks;
test scenarios.
Do not present a Java redesign as required parity. Intentional changes must be separated.
14. Detailed migration mapping
Behavioral parity
Map:
use case;
rule;
state transition;
side effect;
error path;
timing contract;
required Java behavior;
acceptance evidence.
Type mapping
Map C++:
width/signedness;
pointer/reference;
ownership/lifetime;
enum/union/layout;
encoding/serialization.
Interface mapping
Map:
API;
IPC message/payload;
callbacks;
timeout/retry;
external contract.
Do not silently change protocol semantics.
Migration waves
Order by:
runtime dependencies;
shared data;
cycles;
contract ownership;
independently testable boundaries;
cycle-breaking strategy;
entry/exit criteria.
Migration risks/tests
Rank compatibility, data, concurrency, performance, operational, security, testability. Each test scenario must have source behavior, expected Java behavior, observable outcome, and traceability IDs.
15. Review workflow
Independent review:
validate the package first, stop if REVERSE_PACKAGE_GATE fails;
sequence diagram follows the trace order;
class diagram only has evidenced participants/relations;
A UC is Reviewed only when the artifact gate passes, the diagrams agree with the evidence ledger, no material unsupported/contradicted claims remain, and applicable dimensions are evidenced/unresolved explicitly.
16. Metrics
Do not use file counts as coverage. Required metrics:
QUERY_FAMILY_COVERAGE;
ENTRY_CANDIDATE_COVERAGE;
ANCHOR_EXPANSION_COVERAGE;
TRIGGER_HANDLER_OUTCOME_COVERAGE;
ALT_ERROR_COVERAGE;
IPC_CALLBACK_COVERAGE;
SOURCE_SUPPORT_COVERAGE;
PROVEN_UC_RATIO;
UNRESOLVED_GAPS;
SATURATION_STATUS;
GRAPH_RAG_ROUTE;
PROFILE_ARTIFACT_COVERAGE;
REVERSE_PACKAGE_STATUS.
Append a dated snapshot to trace_metrics.md, including raw counts, formulas, percentages, route, gaps, and highest-priority gaps. Do not report 100% when scope/evidence is unresolved.
Use --summary for compact output; do not read the validator's implementation instead of running the validator.
18. Constraints and quiet routing
Do not echo backend exceptions, host/port/key/protocol/driver.
Do not narrate fallback/retry operational details to the user.
Fast-fail once per capability; retry only once for invalid_parameters per the wrapper schema.
User constraints:
no existing docs: record mind_mcp documents: skipped by user, still run code Graph-RAG;
MCP-only: stop after Serena, report gaps, no native;
possible use case: label every result, do not turn a name-only hit into proven;
do not claim exhaustiveness when collection/edge/source areas lack evidence.
19. Verify hi-reverse
Catalog check passes.
Artifact plan gate passes.
Parser is correctly cplus.
One collection validated with module-local hits.
Data context gate passes.
Applicable query matrix complete.
Semantic seed paired with graph expansion.
Vertical traversal with retained anchors.
Two saturation passes with zero delta.
Falkor graph gate pass/partial with clear gaps.
Serena only enriches retained anchors/gaps.
Evidence ledger complete at claim level.
Each artifact validated.
Use-case bundle links exact files.
Review claim status has no material unsupported/contradicted claims.
Package gate passes.
Metrics snapshot appended.
20. Limitations
Graph-RAG depends on the parser/index/collection.
Dynamic callbacks/IPC/function pointers may not be resolved.
Static evidence does not prove every runtime path.
Saturation is evidence convergence, not mathematical exhaustiveness.
A structural validator does not prove semantic correctness.
Migration parity does not mean a Java redesign is automatically correct.
Missing evidence must not be hidden with pretty prose/diagrams.
21. Relationship with other skills
Loading diagram…
22. Summary
hi-reverse does not translate class names to Java or draw diagrams from guesses; it locks the context, retrieves Graph-RAG to saturation, keeps a claim-level ledger, validates each artifact, and only delivers the package when evidence, review, and gates all pass.