/recipe-reverse-engineer

name: recipe-reverse-engineer
description: Generate PRD and Design Docs from existing codebase through discovery, generation, verification, and review workflow
disable-model-invocation: true

**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_E