shinpr/claude-code-workflows/recipe-front-review

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: Post-implementation quality assurance for React/TypeScript frontend

Orchestrator Definition

Core Identity: "I am an orchestrator." (see subagents-orchestration-guide skill)

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 Gate: Complete Steps 1-9 in order, following only the branches activated by their stated conditions. Advance through each review, correction, and re-validation transition only at its declared convergence condition. Present the final report after every applicable finding and retained quality limitation reaches its required disposition or retry result.

Execution Method

• Implementation review → performed by code-reviewer
• Security validation → performed by security-reviewer
• Code-side fix path: Fix implementation → task-executor-frontend; Quality checks → quality-fixer-frontend; Re-validation → code-reviewer / security-reviewer
• Design-side update path: DD revision → technical-designer-frontend (update mode); DD review → document-reviewer; cross-DD consistency → design-sync (when multiple DDs exist); Re-validation → code-reviewer

The design-side path applies when the Design Doc is stale, excessive, or incorrect for the required outcome. Neither path makes the existing implementation or the prior design authoritative by default.

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.

Design Doc: $ARGUMENTS

Execution Flow

Step 1: Prerequisite Check

Derive implementationFiles from paths changed between the current branch's merge base with the repository's default branch and the current repository state, including committed changes, working-tree changes, and untracked files. implementationFiles contains each changed path whose contents implement or verify the reviewed behavior or control its schema, build, deployment, or runtime behavior, including source files, tests, migrations, executable scripts, and behavior-affecting configuration. Governing documents and Work Plans retain their dedicated roles in document selection and governing-document inputs; task files and documentation-only paths remain outside this recipe's code and security review inputs.

Use the Design Doc explicitly supplied in $ARGUMENTS. When omitted, first use a Work Plan whose declared target files or responsibilities intersect implementationFiles and take its recorded Design Doc path. When that does not produce one candidate, use the sole Design Doc under docs/design/. Present candidates only when multiple governing Design Docs remain; report a missing prerequisite when none exists.

Step 2: Execute code-reviewer

Invoke code-reviewer using Agent tool:

• subagent_type: "dev-workflows-frontend:code-reviewer"
• description: "Completed frontend implementation review"
• prompt: "Review the completed frontend implementation. governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. Return the initial review JSON."

Store output as: $STEP_2_OUTPUT

Step 3: Execute security-reviewer

Invoke security-reviewer using Agent tool:

• subagent_type: "dev-workflows-frontend:security-reviewer"
• description: "Security review"
• prompt: "governingDocuments: [\"[path]\"]. implementationFiles: [implementationFiles]. Review security compliance."

Store output as: $STEP_3_OUTPUT

Step 4: Verdict and Response

When either reviewer returns a blocked or otherwise unusable result, apply subagents-orchestration-guide Specialist Result Acceptance to its semantic cause. Carry only a remaining verification limitation into the report.

Apply the Review Resolution Gate to both outputs before reporting or routing them. Finding dispositions determine routing.

For each apply finding, compute a proposed route using the rule below. A finding takes one route, or both d and c when a selected reduction removes a design statement and the implementation it authorized:

Then present the adjudicated result to the user. Group apply findings by proposed route and list declined IDs with their reasons:

Implementation Review: [verdict from code-reviewer]
  Acceptance Criteria:
  - [fulfilled] [item]: [evidence]
  - [unfulfilled] [item] -> [corresponding finding ID under Required Corrections]
  Required Corrections:
  - [id] [category] [location]: [description] — [basis and effect] [recommended: c | d | d and c]
  Limitations:
  - [unverified judgment and effect]
 
Security Review: [status from security-reviewer]
  Findings by category:
  - [confirmed_risk] [location]: [description] — [rationale] [recommended: c]
  - [defense_gap] [location]: [description] — [rationale] [recommended: c]
 
Approve the proposed changes:
  c) Code-side correction — change implementation to reach the accepted state
  d) Design-side update   — correct a stale, excessive, or incorrect Design Doc
  d and c) Reduction     — delete the selecting design statement, then remove the implementation it authorized
  s) Decline              — record the governing reason and accept current state

This review command authorizes analysis; use AskUserQuestion to obtain separate implementation authority. The batch option is "approve all proposed `apply` routes" and its scope consists exclusively of those routes. When the approved change set is empty, proceed directly to Step 9.

Pass approved findings, routes, covered files/sections, and any stated total size budget to update or fix agents. Before re-validation, map every diff hunk to an approved finding or required consistency update. Remove accidental unmapped changes; when a necessary change would alter a confirmed value boundary or explicit size constraint, return to Requirement Change Detection.

Step 5: Design-Side Update

Run this step only when the user routed at least one finding to d. When no d routes exist, skip it; continue to Step 6 only when approved c routes remain.

1. Invoke technical-designer-frontend in update mode using Agent tool:

• subagent_type: "dev-workflows-frontend:technical-designer-frontend"
• description: "Design Doc update from review findings"
• prompt: "Update Design Doc at [path] in update mode. Apply these findings to the design: [complete d-routed finding objects from $STEP_2_OUTPUT, unchanged except for their approved routes]. Where a finding accepts the current code, reflect that behavior in the relevant sections; where it removes an unnecessary mechanism, delete the statements that selected it. Add a history entry."

1. Invoke document-reviewer to verify the updated Design Doc:

• subagent_type: "dev-workflows-frontend:document-reviewer"
• description: "Document review of updated Design Doc"
• prompt: "Review updated Design Doc at [path] for consistency and completeness. doc_type: DesignDoc. review_context: update."
• Run the Review Resolution Gate through its correction re-review and convergence transitions, using technical-designer-frontend for rerouted corrections. Proceed only at its convergence condition.

1. When more than one Design Doc exists under docs/design/, invoke design-sync:

• subagent_type: "dev-workflows-frontend:design-sync"
• description: "Cross-DD consistency check"
• prompt: "source_design: [updated DD path]"
• When sync_status: CONFLICTS_FOUND, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules.

1. After Step 5 completes:

• If the user selected d for all findings (no c routes) → skip Steps 6-7, proceed to Step 8 for re-validation
• If the user selected both d and c → re-evaluate the c-routed findings against the updated DD and drop any that are now satisfied by the DD revision; a reduction's code removal is not satisfied by the DD revision alone. Then proceed to Step 6 with the remaining c findings

Step 6: Execute Fixes

Invoke task-executor-frontend using Agent tool:

• subagent_type: "dev-workflows-frontend:task-executor-frontend"
• description: "Execute review fixes"
• direct_scope: Apply the approved frontend corrections within the confirmed review scope and stated total size budget
• governing_sources: The reviewed Design Doc, applicable UI Spec, and accepted requirement or ADR paths
• target_paths: The implementation and test paths confirmed for the approved code-side routes
• observable_verification: The focused UI behavior tests or observable contract checks named by the findings and governing sources pass
• correction_findings: Complete reviewer finding objects verbatim, with only their orchestrator dispositions added

Step 7: Quality Check

Invoke quality-fixer-frontend using Agent tool:

• subagent_type: "dev-workflows-frontend:quality-fixer-frontend"
• description: "Quality gate check"
• Copy Step 6 direct_scope, governing_sources, observable_verification, and correction_findings inputs unchanged.
• Pass Step 6 mutationEvidence.

Route the quality-fixer-frontend result:

• pass → Proceed to Step 8
• stub_detected → Return to Step 6 with incompleteImplementations unchanged, then repeat Step 7
• verification_incomplete → Retain the complete result and proceed to Step 8
• blocked → Apply Specialist Result Acceptance

Step 8: Reconcile Corrected Findings

Use the shared Re-run rule to select the owners of the findings corrected in Steps 5-7. Retain all other reviewer results. For each selected owner, invoke its original dev-workflows-frontend:code-reviewer or dev-workflows-frontend:security-reviewer with the original governing documents, current implementationFiles, and prior_feedback containing the received finding IDs, dispositions and correction evidence. Derive implementationFiles using Step 1's inclusion rule. The reviewer reconciles those findings under its existing re-review contract.

Apply Review Resolution to each returned reconciliation. Return maintained applied findings to their correction owner; proceed to Step 9 at convergence.

Before Step 9, retry each retained quality-fixer-frontend limitation once with the same Step 7 inputs and affected check. Remove a limitation when the retry passes, route newly discovered incomplete implementation through Steps 6-8, and report a repeated verification_incomplete result. Apply the shared Re-run rule, including its changed-boundary check for mutations outside received findings, before reporting.

Step 9: Final Report

Present the final report: