C++ Reverse Engineering

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

1. Select usecase, module, or migration.
2. Validate the catalog: npx --yes --offline --package=. hi-reverse-plan --check-catalog.
3. For usecase, read PROFILE-USECASE.md; for module or migration, use the generated manifest as the profile guide.
4. 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.
5. Activate the C++ parser, FalkorDB context, and one Qdrant collection.
6. Require DATA_CONTEXT_GATE: PASS.
7. 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.
8. Use Serena only for retained anchors and named gaps.
9. Rerun the plan only when discovery adds a new use-case slug or evidenced condition.
10. Generate artifacts one at a time via the loop below.
11. Require REVERSE_PACKAGE_GATE: PASS before delivery.

Retrieval Order

mind_mcp → graph_mcp/Qdrant → graph_mcp/FalkorDB → Serena → native

• Read GRAPH-RAG-PROTOCOL.md once when retrieval starts.
• 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 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.

Falkor Graph Gate

Record before entering Serena:

FALKOR_GRAPH_GATE: PASS|PARTIAL|BLOCKED
provider=falkordb
collection=<validated collection or unavailable>
semantic_search_calls=<count>
explore_graph_calls=<count>
vertical_graph_trace_calls=<count>
query_families=<completed/applicable>
graph_expansion=<available|no-evidence|unavailable>

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.

1. 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.
2. Read only that artifact's technique file.
3. Retrieve only the missing evidence listed in EVIDENCE_GAPS.
4. Generate the artifact from its template (read the template only now).
5. Validate: npx --yes --offline --package=. hi-reverse-validate-artifact <id> <path> --summary. Require ARTIFACT_GATE: PASS.
6. 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.

Command	Function
hi-reverse-init <output-dir>	Create output workspace and copy templates
hi-reverse-plan --check-catalog	Validate catalog integrity
hi-reverse-plan --profile <p> --module <m> --output <f> --summary	Generate compact manifest
hi-reverse-plan --next <manifest>	Return next pending artifact + technique + evidence gaps
hi-reverse-plan --list-capabilities	List artifact ID, status, scope, output, technique
hi-reverse-validate-artifact <id> <path> --summary	Validate one artifact
hi-reverse-validate-package <manifest> --update	Set REVERSE_PACKAGE_GATE; also enforces UC bundle link checks (--verbose for full rows)
hi-reverse-metrics [usecase-dir] [metrics-file] [package-manifest]	Append UC and profile/package coverage

Orchestration

CATALOG → PROFILE → PLAN → DISCOVERY → TRACING → UC/SEQ/CLASS/ACTIVITY → MODULE MAP → OVERVIEW/ENTRYPOINTS/INTERFACES → STATE/DATA/RULES/ERRORS/CONCURRENCY → MIGRATION PARITY/MAPPINGS/WAVES/RISKS/TESTS → REVIEW → VALIDATION → PACKAGE GATE → METRICS.

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.