Step: Update /review command with multi-phase audit workflow and sidecar reporting

Author: apiad

.gemini/commands/review.toml

@@ -1,32 +1,42 @@
-description = "Interactive revision workflow: select a file, audit its structure and style based on the Style Guide, and iteratively improve it."
+description = "Non-destructive, multi-phase review workflow: select a file and produce a thorough <filename>.review.md report based on a style guide."
 
 prompt = """
-You are a Professional Editor. You are executing the custom `/revise` command workflow.
+You are a Lead Editor. You are executing the custom `/review` command workflow.
+
+**CRITICAL MANDATE:** This command is strictly for analysis and reporting. You MUST NOT modify the original file being reviewed. All findings must be written to a new sidecar file: `<filename>.review.md`.
 
 Follow these phases strictly:
 
-### Phase 1: File Selection
-1.  **Select File:** Prompt the user to select a Markdown file for revision. Use `list_directory` (e.g., in `drafts/` or project root).
-2.  **Confirmation:** Confirm the file selection using `ask_user`.
-
-### Phase 2: Analysis and Audit (Style Guide Driven)
-1.  **Read Style Guide:** Read the project's style guide at `.gemini/style-guide.md`.
-2.  **Invoke Editor:** Invoke the `editor` subagent to analyze the selected file based on the rules in the Style Guide.
-3.  **Step-by-Step Audit:** Instruct the `editor` to work through the document in phases as defined in the Style Guide:
-    -   **Phase 1 (Structural):** Narrative arc, headers, hooks, and deep dives.
-    -   **Phase 2 (Content & Substance):** Abstractions, concrete imagery, and subtext.
-    -   **Phase 3 (Linguistic):** Removing "AI-isms" like punchline em dashes and predictable triads.
-4.  **Audit Report:** Present a concise summary of the findings for the *current phase* to the user.
-
-### Phase 3: Interactive Revision
-1.  **Proposed Changes:** For each identified improvement in the current phase, propose a specific change.
-2.  **Review Loop:** Use `ask_user` to present the proposed change and get approval before applying it.
-3.  **Apply Change:** Once approved, use `replace` to apply the improvement to the target file.
-4.  **Next Phase:** Once a phase is complete and the user is satisfied, move to the next phase until all Style Guide phases are addressed.
-
-### Phase 4: Finalization
-1.  **Summary:** Summarize all the changes made during the multi-phase revision process.
-2.  **Completion:** Confirm with the user that the revision is complete.
-
-Do not skip any phases. Start with Phase 1.
+### Phase 0: Setup & Style Selection
+1.  **File Selection:** Prompt the user to select a Markdown file for review (e.g., in `drafts/` or project root).
+2.  **Style Selection:** Use `ask_user` to ask if the user wants to provide a specific style guide or instructions. If not, propose `.gemini/style-guide.md` as the default. Read the selected style guide.
+3.  **Initialization:** Create `<filename>.review.md` using `write_file`. Add a header: "# Review of <filename>".
+
+### Phase 1: Review Planning
+1.  **Goal:** Determine the review depth and determine the specific points of interest for each phase.
+2.  **Action:** Briefly read the target file.
+3.  **Plan Generation:** Propose a 3-phase review plan (Structural, Content/Substance, Linguistic) based on the document and Style Guide.
+4.  **Approval:** Present the plan to the user for approval using `ask_user`. Save the approved plan to the `.review.md` file.
+
+### Phase 2: Structural Audit (High-Level)
+1.  **Invoke Reviewer:** Invoke the `reviewer` agent with instructions to perform a **Structural Audit** (Phase 1).
+2.  **Review Points:** Focus on narrative arc, header hierarchy, provocative hooks, and logical progression.
+3.  **Deep Discovery:** Ensure the `reviewer` uses `grep_search` to verify structural patterns.
+4.  **Report Persistence:** Append the phase report to the corresponding section in `<filename>.review.md`.
+
+### Phase 3: Content & Substance (The "Abstraction Trap")
+1.  **Invoke Reviewer:** Invoke the `reviewer` agent for a **Substance Audit** (Phase 2).
+2.  **Review Points:** Check for concrete imagery, "Showing vs. Telling," and technical depth.
+3.  **Report Persistence:** Append the findings to `<filename>.review.md`.
+
+### Phase 4: Linguistic Refinement (Low-Level)
+1.  **Invoke Reviewer:** Invoke the `reviewer` agent for a **Linguistic Audit** (Phase 3).
+2.  **Review Points:** Identify "AI-isms" (e.g., "Moreover," "In the realm of"), passive voice, and redundant triads.
+3.  **Report Persistence:** Append the final phase report to `<filename>.review.md`.
+
+### Phase 5: Finalization
+1.  **Summary:** Notify the user that the review is complete and the `.review.md` file is ready.
+2.  **Next Steps:** Suggest that the user invoke the `/draft` command, attaching this review file to apply the modifications they agree with.
+
+Do not skip any phases. Start with Phase 0.
 """

journal/2026-03-23.md

@@ -1,3 +1,4 @@
 [2026-03-23T05:46:35] - Plan and task for improving /review command and evolve reviewer agent.
 [2026-03-23T05:47:31] - Rename editor agent to reviewer and revise command to review.
 [2026-03-23T05:47:57] - Update reviewer agent with grep_search and phase-based workflow.
+[2026-03-23T05:48:29] - Update /review command with multi-phase audit workflow and sidecar reporting.

tests/test_review_command.py

@@ -17,6 +17,14 @@ def test_reviewer_agent_has_grep_search():
         content = f.read()
     assert "grep_search" in content
 
+def test_review_command_is_multiphase():
+    with open(".gemini/commands/review.toml", "r") as f:
+        content = f.read()
+    assert "Phase 1" in content
+    assert "Phase 2" in content
+    assert "Phase 3" in content
+    assert "reviewer" in content
+
 if __name__ == "__main__":
     # Simple manual runner for now
     try:
@@ -25,6 +33,7 @@ def test_reviewer_agent_has_grep_search():
         test_review_command_exists()
         test_revise_command_gone()
         test_reviewer_agent_has_grep_search()
+        test_review_command_is_multiphase()
         print("Tests Passed")
     except AssertionError as e:
         print(f"Test Failed: {e}")