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. 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. 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: Complete Phase 1 before Phase 2. Within each phase, complete one unit's generation, verification, review, and required revision to convergence before starting the next unit. Advance only when the current step's stated output and quality gate are satisfied. At each loop boundary, select the first unit in the current phase's declared order whose Unit Completion conditions are unsatisfied and that is not logged as a generation failure. A document path proves generation only.

Step 0: Initial Configuration

0.1 Scope Confirmation

Use AskUserQuestion 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)
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
• 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 (routes, testFiles, or publicExports). Units with all three empty indicate incomplete discovery — re-run scope-discoverer with focus on that unit's relatedFiles

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 (sequential, one unit at a time):

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

  Use provided scope as investigation starting point.
  If tracing entry points reveals 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: $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: [the current unit's Step 1 unitInventory]

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, re-run code-verifier on the revised document with the original unit_inventory, then re-run document-reviewer with the latest verification_evidence and 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