Recipe Reverse Engineer

Required Skills [LOAD BEFORE EXECUTION]

1. [LOAD IF NOT ACTIVE] documentation-criteria — document creation rules and templates
2. [LOAD IF NOT ACTIVE] ai-development-guide — AI development patterns
3. [LOAD IF NOT ACTIVE] subagents-orchestration-guide — agent coordination and workflow flows
4. [LOAD IF NOT ACTIVE] llm-friendly-context — clear prompts, handoffs, and generated artifacts

Spawn rule: every spawn_agent call uses fork_turns="none" so the subagent receives only the task message and explicitly provided context.

Context: Reverse engineering workflow to create documentation from existing code

Target: $ARGUMENTS

Orchestrator Definition

Core Identity: "I am not a worker. I am an orchestrator."

Execution Protocol:

1. Spawn agents for all work -- your role is to invoke sub-agents, pass data between them, and report results
2. Process one step at a time: Execute steps sequentially within each unit (2 -> 3 -> 4 -> 5). Each step's output is the required input for the next step. Complete all steps for one unit before starting the next
3. Pass $STEP_N_OUTPUT as-is to sub-agents -- the orchestrator bridges data without processing or filtering it, except for steps that explicitly define a deterministic transformation with an input schema, output schema, and mapping rules

Task Registration: Register phases first, then steps within each phase as you enter it. Track status for each step.

Step 0: Initial Configuration

0.1 Scope Confirmation

Ask the user to confirm:

1. Target path: Which directory/module to document
2. Depth: PRD only, or PRD + Design Docs
3. Reference Architecture: layered / mvc / clean / hexagonal / none
4. Human review: Yes (recommended) / No (fully autonomous)

0.2 Output Configuration

• PRD output: docs/prd/ or existing PRD directory
• Design Doc output: docs/design/ or existing design directory
• Verify directories exist, create if needed

Workflow Overview

Phase 1: PRD Generation
  Step 1: Scope Discovery (unified, single pass -> group into PRD units -> human review)
  Step 2-5: Per-unit loop (Generation -> Verification -> Review -> Revision)

Phase 2: Design Doc Generation (if requested)
  Step 6: Design Doc Scope Mapping (reuse Step 1 results, no re-discovery)
  Step 7-10: Per-unit loop (Generation -> Verification -> Review -> Revision)

Phase 1: PRD Generation

Register tasks:

• Step 1: PRD Scope Discovery
• Per-unit processing (Steps 2-5 for each unit)

Step 1: PRD Scope Discovery

Spawn scope-discoverer agent: "Discover functional scope targets in the codebase. targetpath: $USERTARGETPATH. referencearchitecture: $USERRACHOICE. focusarea: $USERFOCUS_AREA (if specified)."

Store output as: $STEP_1_OUTPUT

Quality Gate:

• At least one unit discovered -> proceed
• No units discovered -> ask user for hints
• $STEP_1_OUTPUT.prdUnits exists
• All sourceUnits across prdUnits (flattened, deduplicated) match the set of discoveredUnits IDs — no unit missing, no unit duplicated
• Each discovered unit's unitInventory has at least one non-empty category. If all categories are empty, re-run discovery with focus on that unit

[STOP — BLOCKING] If human review enabled: Present $STEP_1_OUTPUT.prdUnits with their source unit mapping to user for confirmation. CANNOT proceed until user explicitly confirms.

Step 2-5: Per-Unit Processing

FOR each unit in $STEP_1_OUTPUT.prdUnits (sequential, one unit at a time):

Step 2: PRD Generation

Spawn prd-creator agent: "Create reverse-engineered PRD for the following feature. Operation Mode: reverse-engineer. External Scope Provided: true. Feature: $PRDUNITNAME. Description: $PRDUNITDESCRIPTION. Related Files: $PRDUNITCOMBINEDRELATEDFILES. Entry Points: $PRDUNITCOMBINEDENTRYPOINTS. Source Units: $PRDUNITSOURCE_UNITS. Use provided scope as an investigation starting point. If tracing entry points reveals directly connected files outside this scope, include them. Create final version PRD based on thorough code investigation."

Store output as: $STEP_2_OUTPUT (PRD path)

Step 3: Code Verification

Prerequisite: $STEP2OUTPUT (PRD path from Step 2)

Spawn code-verifier agent: "Verify consistency between PRD and code implementation. doctype: prd. documentpath: $STEP2OUTPUT. verbose: false."

Store output as: $STEP_3_OUTPUT

Quality Gate:

• consistencyScore >= 70 and verifiableClaimCount >= 20 -> proceed to review (guards against shallow verification passes with too few extracted claims)
• consistencyScore >= 70 and verifiableClaimCount re-run verifier because investigation depth is insufficient
• consistencyScore flag for detailed review

Step 4: Review

Required Input: $STEP3OUTPUT (verification data from Step 3)

Spawn document-reviewer agent: "Review the following PRD considering code verification findings. doctype: PRD. target: $STEP2OUTPUT. mode: composite. codeverification: $STEP3OUTPUT. Additional Review Focus: Alignment between PRD claims and verification evidence, resolution recommendations for each discrepancy, completeness of undocumented feature coverage."

Store output as: $STEP_4_OUTPUT

Step 5: Revision (conditional)

Trigger Conditions (any one of the following):

• Review status is "Needs Revision" or "Rejected"
• Critical discrepancies exist in $STEP_3_OUTPUT
• consistencyScore Phase 2.

Phase 2: Design Doc Generation

Execute only if Design Docs were requested in Step 0

Register tasks:

• Step 6: Design Doc Scope Mapping
• Per-unit processing (Steps 7-10 for each unit)

Step 6: Design Doc Scope Mapping

Step type: Deterministic transformation step executed by the orchestrator.

No additional discovery required. Use $STEP_1_OUTPUT.discoveredUnits (implementation-granularity units) for technical profiles. Use $STEP_1_OUTPUT.prdUnits[].sourceUnits to trace which discovered units belong to each PRD unit.

Default mapping rule: Each PRD unit maps to exactly 1 Design Doc unit.

Only split one PRD unit into multiple Design Doc units when BOTH are true:

1. The source units contain clearly separate technical boundaries with low shared-file overlap
2. Separate Design Docs would improve verification clarity (different public interfaces, dependencies, or module groups)

If the split conditions are not clearly met, keep 1 PRD unit -> 1 Design Doc unit.

Transform $STEP_1_OUTPUT into $STEP_6_OUTPUT using only the mapping rules in this step.

Map PRD units to Design Doc generation targets by resolving each PRD unit's sourceUnits back to $STEP_1_OUTPUT.discoveredUnits, carrying forward:

• technicalProfile.primaryModules -> Primary Files
• technicalProfile.publicInterfaces -> Public Interfaces
• dependencies -> Dependencies
• relatedFiles -> Scope boundary
• unitInventory -> Unit Inventory

Store output as: $STEP_6_OUTPUT

$STEP_6_OUTPUT MUST be a JSON array of Design Doc generation targets in the following shape:

[
  {
    "unitId": "DD-001",
    "parentPrdUnitId": "PRD-001",
    "unitName": "Authentication",
    "unitDescription": "Current implementation for sign-in and session management",
    "sourceUnits": ["UNIT-001", "UNIT-002"],
    "primaryModules": ["src/auth/service.ts", "src/auth/controller.ts"],
    "publicInterfaces": ["AuthService.login()", "AuthController.handleLogin()"],
    "dependencies": ["UNIT-003"],
    "scopeBoundary": ["src/auth/*"],
    "unitInventory": {
      "routes": [],
      "testFiles": [],
      "publicExports": []
    },
    "mappingRationale": "Default 1:1 mapping from PRD unit because technical scope is cohesive"
  }
]

Quality Gate:

• Every PRD unit appears in at least one $STEP_6_OUTPUT item
• Every $STEP_6_OUTPUT item references only discovered units from its parent PRD unit
• mappingRationale explicitly states whether the mapping is default 1:1 or an intentional split

Step 7-10: Per-Unit Processing

FOR each unit in $STEP_6_OUTPUT (sequential, one unit at a time):

Step 7: Design Doc Generation

Scope: Document current architecture as-is. This is a documentation task, not a design improvement task.

Spawn technical-designer agent: "Create Design Doc for the following feature based on existing code. Operation Mode: reverse-engineer. Feature: $UNITNAME. Description: $UNITDESCRIPTION. Primary Files: $UNITPRIMARYMODULES. Public Interfaces: $UNITPUBLICINTERFACES. Dependencies: $UNITDEPENDENCIES. Unit Inventory: $UNITINVENTORY. Parent PRD: $APPROVEDPRDPATH. Document current architecture as-is. Use Unit Inventory as the completeness baseline."

Store output as: $STEP_7_OUTPUT

Step 8: Code Verification

Spawn code-verifier agent: "Verify consistency between Design Doc and code implementation. doctype: design-doc. documentpath: $STEP7OUTPUT. verbose: false."

Store output as: $STEP_8_OUTPUT

Step 9: Review

Required Input: $STEP8OUTPUT (verification data from Step 8)

Spawn document-reviewer agent: "Review the following Design Doc considering code verification findings. doctype: DesignDoc. target: $STEP7OUTPUT. mode: composite. codeverification: $STEP8OUTPUT. Parent PRD: $APPROVEDPRDPATH. Additional Review Focus: Technical accuracy of documented interfaces, consistency with parent PRD scope, completeness of unit boundary definitions."

Store output as: $STEP_9_OUTPUT

Step 10: Revision (conditional)

Trigger Conditions (same as Step 5):

• Review status is "Needs Revision" or "Rejected"
• Critical discrepancies exist in $STEP_8_OUTPUT
• consistencyScore Final Report.

Final Report

Output summary including:

• Generated documents table (Type, Name, Consistency Score, Review Status)
• Action items (critical discrepancies, undocumented features, flagged items)
• Next steps checklist

Error Handling

| Error | Action | |-------|--------| | Discovery finds nothing | Ask user for project structure hints | | Generation fails | Log failure, continue with other units, report in summary | | consistencyScore verification -> review -> revision)

• [ ] Phase 2: All Design Doc units processed (if requested)
• [ ] All human review points honored (if enabled)
• [ ] Final report presented with document table, action items, and next steps

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shinpr
• Source: shinpr/codex-workflows
• License: MIT

Install and usage instructions live in the source repository linked above.