shinpr/claude-code-workflows/recipe-reverse-engineer

Explicit User Instruction: The user explicitly instructs and authorizes every subagent call named in this recipe. Execute each applicable call when its prerequisites are met.

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings.

Context: Reverse engineering workflow to create documentation from existing code

Target: $ARGUMENTS

Orchestrator Definition

Core Identity: "I am an orchestrator."

Local authority gate: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist.

Review Resolution Gate [MANDATORY]: Resolve every actionable deliverable-review finding through subagents-orchestration-guide Review Resolution before correction or progression. Before the first finding disposition, read references/review-resolution.md from the loaded subagents-orchestration-guide skill.

Execution Protocol:

1. Invoke named specialists for deliverable production — pass deliverable paths between them and validate their results (see subagents-orchestration-guide "Orchestrator Execution Boundary")
2. Respect evidence dependencies: Generation precedes verification and review for each unit; revision reruns the affected checks. Independent units may be scheduled without changing these gates.
3. Preserve evidence while bridging outputs — copy the fields required by the next specialist in their declared form; apply Review Resolution before routing any correction

At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately.

Execution Gate: Each Design Doc depends on its completed parent PRD and scope mapping. Advance each unit only when its stated evidence and Unit Completion conditions are satisfied; a document path proves generation only. Continue independent units when another has a recorded failure, and report incomplete units explicitly.

Step 0: Initial Configuration

0.1 Scope Confirmation

Use supplied instructions and repository context first. Ask only for missing choices that materially change scope or execution; retain prior authorization and preferences:

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)
5. Fullstack design: Yes / No

• Yes: For each functional unit, generate backend + frontend Design Docs
• Note: Requires both agents (technical-designer, technical-designer-frontend)

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)
  ※ fullstack=Yes: each unit produces backend + frontend Design Docs

Phase 1: PRD Generation

Step 1: PRD Scope Discovery

Agent tool invocation:

subagent_type: dev-workflows:scope-discoverer
description: "Discover functional scope"
prompt: |
  Discover functional scope targets in the codebase.
 
  target_path: $USER_TARGET_PATH
  reference_architecture: $USER_RA_CHOICE
  focus_area: [user-confirmed focus area verbatim, 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
• Flatten sourceUnits across prdUnits without deduplication: every discovered ID occurs exactly once, with no unknown IDs
• Each discovered unit has source evidence and an inventory containing the applicable categories; empty categories are valid, but each unit requires at least one behavior-bearing route, public export, or otherEntryPoints item with a defining source location. Resolve a material coverage limitation through targeted discovery; preserve non-blocking limitations.

Human Review Point (if enabled): Present $STEP_1_OUTPUT.prdUnits with their source unit mapping. The user confirms, adjusts grouping, or excludes units from scope. This is the most important review point — incorrect grouping cascades into all downstream documents.

Step 2-5: Per-Unit Processing

FOR each unit in $STEP_1_OUTPUT.prdUnits:

Derive $PRD_UNIT_INVENTORY by joining this PRD unit's sourceUnits to discoveredUnits[].id and merging their unitInventory categories. Deduplicate the merged inventory by item identity (route method/path/owner, test path, export file/name, other entry-point file/name), preserving source evidence. Use this same baseline for generation and verification.

Step 2: PRD Generation

Agent tool invocation:

subagent_type: dev-workflows:prd-creator
description: "Generate PRD"
prompt: |
  Create reverse-engineered PRD for the following feature.
 
  Operation Mode: reverse-engineer
  External Scope Provided: true
 
  Feature: $PRD_UNIT_NAME (current Step 1 PRD unit name unchanged)
  Description: $PRD_UNIT_DESCRIPTION (current Step 1 PRD unit description unchanged)
  Related Files: $PRD_UNIT_COMBINED_RELATED_FILES
  Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS
  Unit Inventory: $PRD_UNIT_INVENTORY
 
  Use provided scope as investigation starting point.
  Inspect dependencies outside these files only when they establish an in-scope behavior or contract; this does not automatically expand feature scope.
  Create final version PRD based on thorough code investigation.

Store output as: $STEP_2_OUTPUT (PRD path)

Step 3: Code Verification

Prerequisite: $STEP_2_OUTPUT (PRD path from Step 2)

Agent tool invocation:

subagent_type: dev-workflows:code-verifier
description: "Verify PRD consistency"
prompt: |
  Verify consistency between PRD and code implementation.
 
  doc_type: prd
  document_path: $STEP_2_OUTPUT
  unit_inventory: $PRD_UNIT_INVENTORY

unit_inventory supplies the completeness baseline while repository evidence supplies the search scope.

Store output as: $STEP_3_OUTPUT

Quality Gate:

• summary.status is blocked, inventory coverage is missing, or counts do not balance → re-run or escalate with the exact unusable input or evidence
• Any balanced non-blocked result → proceed to review with the complete verifier output; needs_review / inconsistent and any unaccounted items become explicit review evidence

Step 4: Review

Required Input: $STEP_3_OUTPUT (verification JSON from Step 3)

Agent tool invocation:

subagent_type: dev-workflows:document-reviewer
description: "Review PRD"
prompt: |
  Review the following PRD considering code verification findings.
 
  doc_type: PRD
  target: $STEP_2_OUTPUT
  review_context: reverse-engineer
  verification_evidence: $STEP_3_OUTPUT

Store output as: $STEP_4_OUTPUT

Step 5: Revision (conditional)

Pass $STEP_3_OUTPUT to document-reviewer as verification evidence, then apply the Review Resolution Gate to $STEP_4_OUTPUT. Run revision only when at least one finding is apply; a decline-only result completes the review.

Agent tool invocation:

subagent_type: dev-workflows:prd-creator
description: "Revise PRD"
prompt: |
  Update PRD based on review feedback and code verification results.
 
  Operation Mode: update
  Existing PRD: $STEP_2_OUTPUT
 
  ## Adjudicated Findings
  [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]
 
  Treat these findings as the complete revision scope and preserve adjacent content.

Re-validation: After each revision, pass code-verifier the same unit_inventory plus the previous complete verifier result, dispositions and correction diff or paths as prior_feedback. Follow code-verifier’s rerun boundary: recheck all inventory items against the current document, while reusing unchanged repository evidence. Re-run document-reviewer with the latest verification_evidence, prior_feedback.

Unit Completion

• [ ] No apply findings remain
• [ ] Human review passed (if enabled in Step 0)

Next: Proceed to next unit. After all units → Phase 2.

Phase 2: Design Doc Generation

Execute only if Design Docs were requested in Step 0

Step 6: Design Doc Scope Mapping

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.

Each PRD unit from Phase 1 maps to Design Doc unit(s):

• Standard mode (fullstack=No): 1 PRD unit → 1 Design Doc (using technical-designer)
• Fullstack mode (fullstack=Yes): 1 PRD unit → 2 Design Docs (technical-designer + technical-designer-frontend)

For each PRD unit, join its sourceUnits to discovered units and merge their technical evidence and inventory, preserving provenance. Map the result to Design Doc targets, carrying forward:

• technicalProfile.primaryModules → Primary Files
• technicalProfile.publicInterfaces → Public Interfaces
• dependencies → Dependencies
• relatedFiles → Scope boundary
• unitInventory → Unit Inventory (routes, test files, public exports, other entry points)

In fullstack mode, partition each unit inventory by the owning path into backend and frontend target inventories. Assign a shared entry to each Design Doc whose public contract must account for it and record that shared reason; otherwise assign it once. Each Step 7 and Step 8 invocation receives its target's inventory, not the unpartitioned combined unit.

Assign each target a distinct output_path before generation. Use [feature]-design.md in standard mode and [feature]-backend-design.md / [feature]-frontend-design.md in fullstack mode. Check existing destinations and preserve unrelated artifacts.

Store output as: $STEP_6_OUTPUT

Step 7-10: Per-Unit Processing

FOR each unit in $STEP_6_OUTPUT:

Step 7: Design Doc Generation

Scope: Document the current architecture exactly as implemented in code.

Standard mode (fullstack=No):

Agent tool invocation:

subagent_type: dev-workflows:technical-designer
description: "Generate Design Doc"
prompt: |
  Create Design Doc for the following feature based on existing code.
 
  Operation Mode: reverse-engineer
 
  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $DESIGN_DOC_UNIT_INVENTORY
  output_path: $DESIGN_DOC_OUTPUT_PATH
 
  Parent PRD: $APPROVED_PRD_PATH
 
  Document current architecture as-is. Use Unit Inventory as a completeness baseline — all inventoried capabilities should be accounted for in the Design Doc.

Store output as: $STEP_7_OUTPUT

Fullstack mode (fullstack=Yes):

For each unit, invoke 7a then 7b sequentially (7b depends on 7a output):

7a. Backend Design Doc:

subagent_type: dev-workflows:technical-designer
description: "Generate backend Design Doc"
prompt: |
  Create a backend Design Doc for the following feature based on existing code.
 
  Operation Mode: reverse-engineer