recipe-reverse-engineer

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; include declined IDs with governing reasons and evidence in the final user report. 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 — extract and transform the fields required by the next specialist without changing supported meaning; apply Review Resolution before routing any correction

Task Registration: Register phases first using TaskCreate, then steps within each phase as you enter it. Update status using TaskUpdate.

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

Register using TaskCreate:

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

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_FOCUS_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 (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 (from $STEP_1_OUTPUT)
  Description: $PRD_UNIT_DESCRIPTION
  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
  verbose: false

Note: Omit code_paths — the verifier independently discovers code scope from the document, ensuring independent verification not constrained by scope-discoverer's output.

Store output as: $STEP_3_OUTPUT

Quality Gate:

• consistencyScore >= 70 AND verifiableClaimCount >= 20 → proceed to review
• consistencyScore >= 70 BUT verifiableClaimCount < 20 → re-run verifier (investigation too shallow)
• consistencyScore < 70 → flag for detailed review

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
  mode: composite
  code_verification: $STEP_3_OUTPUT

  ## 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)

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, and unresolved user_decision_required stops for user input.

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, then re-run document-reviewer with the latest code_verification and prior_feedback.

Unit Completion

• No apply findings remain; every other review finding has a disposition and every user_decision_required item has a recorded user decision
• 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

Register using TaskCreate:

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

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)

Map $STEP_1_OUTPUT units to Design Doc generation targets, carrying forward:

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

Store output as: $STEP_6_OUTPUT

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 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 (from $STEP_6_OUTPUT)
  Description: $UNIT_DESCRIPTION
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $UNIT_INVENTORY (routes, test files, public exports from scope discovery)

  Parent PRD: $APPROVED_PRD_PATH

  Document current architecture as-is. Use Unit Inventory as a completeness baseline — all routes and exports 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

  Feature: $UNIT_NAME (from $STEP_6_OUTPUT)
  Description: $UNIT_DESCRIPTION
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH

  Focus on: API contracts, data layer, business logic, service architecture.
  Document current architecture as-is. Use Unit Inventory as completeness baseline.

Store output as: $STEP_7a_OUTPUT

7b. Frontend Design Doc:

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

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (from $STEP_6_OUTPUT)
  Description: $UNIT_DESCRIPTION
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH
  Backend Design Doc: $STEP_7a_OUTPUT

  Reference backend Design Doc for API contracts.
  Focus on: component hierarchy, state management, UI interactions, data fetching.
  Document current architecture as-is. Use Unit Inventory as completeness baseline.

Store output as: $STEP_7b_OUTPUT

Step 8: Code Verification

Standard mode: Verify $STEP_7_OUTPUT.

Fullstack mode: Verify each Design Doc separately.

Agent tool invocation (per Design Doc):

subagent_type: dev-workflows:code-verifier
description: "Verify Design Doc consistency"
prompt: |
  Verify consistency between Design Doc and code implementation.

  doc_type: design-doc
  document_path: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)
  verbose: false

Note: Omit code_paths — the verifier independently discovers code scope from the document.

Store output as: $STEP_8_OUTPUT

Step 9: Review

Required Input: $STEP_8_OUTPUT (verification JSON from Step 8)

Agent tool invocation (per Design Doc):

subagent_type: dev-workflows:document-reviewer
description: "Review Design Doc"
prompt: |
  Review the following Design Doc considering code verification findings.

  doc_type: DesignDoc
  target: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)
  mode: composite
  review_context: as-is
  code_verification: $STEP_8_OUTPUT

  ## Parent PRD
  $APPROVED_PRD_PATH

  ## 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)

Pass $STEP_8_OUTPUT to document-reviewer as verification evidence, then apply the Review Resolution Gate to $STEP_9_OUTPUT. Run revision only when at least one finding is apply; a decline-only result completes the review, and unresolved user_decision_required stops for user input.

Agent tool invocation (per Design Doc):

subagent_type: dev-workflows:technical-designer (or dev-workflows-frontend:technical-designer-frontend for frontend Design Docs)
description: "Revise Design Doc"
prompt: |
  Update Design Doc based on review feedback and code verification results.

  Operation Mode: update
  Existing Design Doc: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_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, then re-run document-reviewer with the latest code_verification and prior_feedback.

Unit Completion

• No apply findings remain; every other review finding has a disposition and every user_decision_required item has a recorded user decision
• Human review passed (if enabled in Step 0)

Next: Proceed to next unit. After all units → 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