recipe-reverse-engineer · git:20261019.67741b0 · 2026-10-19 · sha256 615145ee09da733a
recipe-reverse-engineer git:20261019.67741b0A
Immutable. This exact content never changes and is served at /api/v1/blob/615145ee09da733a.
--- 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-fullstack: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-fullstack: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-fullstack: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-fullstack: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-fullstack: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-fullstack: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-fullstack: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 (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: $BACKEND_UNIT_INVENTORY output_path: $BACKEND_DESIGN_DOC_OUTPUT_PATH 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-fullstack: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 (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: $FRONTEND_UNIT_INVENTORY output_path: $FRONTEND_DESIGN_DOC_OUTPUT_PATH 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-fullstack: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) unit_inventory: [the current Design Doc target's Step 6 unitInventory] ``` **Store output as**: `$STEP_8_OUTPUT` **Verification gate (per Design Doc)**: - `blocked`, missing `inventoryCoverage`, or unbalanced category counts → correct the invocation/input and rerun; stop for the user only when repository evidence cannot resolve the input defect. - Any balanced non-blocked result proceeds to document review. Carry `needs_review`, `inconsistent`, and every unaccounted item as explicit verifier evidence. #### Step 9: Review **Required Input**: $STEP_8_OUTPUT (verification JSON from Step 8) **Agent tool invocation (per Design Doc)**: ``` subagent_type: dev-workflows-fullstack: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) review_context: reverse-engineer verification_evidence: $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. **Agent tool invocation (per Design Doc)**: ``` subagent_type: dev-workflows-fullstack:technical-designer (or dev-workflows-fullstack: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, 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 → Final Report. ## Final Report Output summary including: - Generated documents table (Type, Name, Verification Status, Review Status) - Action items (undocumented features, flagged items) - Declined actionable findings with ID, governing reason, and evidence, when any occurred - 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 | | Required defect remains after Review Resolution | Report the unit incomplete with evidence. A raw verifier label or a resolved decline creates no extra approval gate; optional human review follows Step 0. |