Step: Update /draft command with branching logic for initial drafting and review-driven refinement

Author: apiad

.gemini/commands/draft.toml

@@ -1,36 +1,49 @@
-description = "Interactive drafting workflow: gather context, create an outline based on the Style Guide, and generate a technical draft section-by-section."
+description = "Interactive drafting and refinement workflow: create a new technical draft from an outline or refine an existing one based on editorial feedback (.review.md)."
 
 prompt = """
 You are an expert technical writer. You are executing the custom `/draft` command workflow.
 
 Follow these phases strictly:
 
-### Phase 1: Context Gathering
-1.  **Analyze Request:** Identify the topic the user wants to draft.
+### Phase 1: Context & Mode Selection
+1.  **Identify Topic/File:** Determine the topic the user wants to draft or the existing file they want to refine.
 2.  **Search Context:** Search for existing context in `research/`, `plans/`, `TASKS.md`, and `journal/`. Use `list_directory` and `read_file`.
-3.  **Read Style Guide:** Read the project's style guide at `.gemini/style-guide.md`.
-4.  **Validate Context:** If no relevant research or planning context is found, use `ask_user` to suggest running `/research` or `/plan` first, or ask for more specific details.
+3.  **Check for Review:** Search for a corresponding `<filename>.review.md` file for the target file.
+4.  **Mode Branching:**
+    -   **Refinement Mode:** If a `.review.md` file exists, propose entering **Refinement Mode** to apply the suggested changes.
+    -   **Initial Drafting Mode:** If no review exists (or if the user explicitly wants to start fresh), follow the **Initial Drafting** workflow.
 
-### Phase 2: Title and Path
-1.  **Propose Metadata:** Based on the gathered context, propose a title for the document and a target file path (e.g., `drafts/your-title.md`).
-2.  **Confirmation:** Use `ask_user` to get approval for the title and path.
+---
 
-### Phase 3: Outline Creation (Style Guide Driven)
-1.  **Generate Outline:** Based on the context and the rules in `.gemini/style-guide.md` (e.g., hooks, hierarchical headers, deep dives), generate a detailed Markdown outline.
-2.  **Review Loop:** Present the outline to the user and ask for feedback or approval. Use `ask_user` to refine the outline until the user is satisfied.
+### [Initial Drafting Mode]
 
-### Phase 4: Initialization
-1.  **Create Skeleton:** Once the outline is approved, create the target file (if it doesn't exist) with the approved title and sections.
-2.  **Placeholders:** Use placeholders like `<!-- [Section Name] Placeholder -->` for each section that needs to be filled.
+### Phase 2: Metadata & Outline
+1.  **Propose Title/Path:** Suggest a title and file path (e.g., `drafts/your-title.md`). Confirm with `ask_user`.
+2.  **Generate Outline:** Based on the Style Guide (`.gemini/style-guide.md`) and project context, create a detailed Markdown outline. Get user approval.
 
-### Phase 5: Section-by-Section Drafting
-1.  **Iterative Drafting:** For each section in the outline, invoke the `reporter` subagent.
-2.  **Instructions:** Instruct the `reporter` to fill the specific placeholder with detailed, high-quality prose based on the gathered context. Ensure the `reporter` adheres to the general tone defined in the Style Guide.
-3.  **Review Progress:** After each section is filled, briefly update the user on the progress.
+### Phase 3: Initialization & Expansion
+1.  **Create Skeleton:** Create the target file with placeholders for each section.
+2.  **Section-by-Section Drafting:** For each section, invoke the `writer` subagent to fill the placeholders with detailed prose that adheres to the Style Guide.
 
-### Phase 6: Conclusion
-1.  **Final Summary:** Once all sections are filled, notify the user that the draft is complete.
-2.  **Next Steps:** Suggest using the `/review` command to perform a non-destructive, multi-phase audit of the new draft and produce a `<filename>.review.md` report. Mention that they can then use `/draft` again attaching the review to apply the changes.
+---
+
+### [Refinement Mode]
+
+### Phase 2: Review Analysis
+1.  **Read Review:** Read the target file and its `.review.md` sidecar.
+2.  **Identify Tasks:** Analyze the Structural, Substance, and Linguistic findings in the review.
+3.  **Propose Refinement Plan:** Use `ask_user` to present a plan for applying the changes (e.g., "I will first fix the narrative arc, then address the abstract nouns in Section 2").
+
+### Phase 3: Direct Refinement
+1.  **Invoke Writer:** Invoke the `writer` subagent for each set of identified improvements.
+2.  **Surgical Application:** Instruct the `writer` to use the `replace` tool to apply the improvements directly to the target file.
+3.  **Verification:** Briefly report progress to the user after each major refinement.
+
+---
+
+### Phase 4: Conclusion (Common)
+1.  **Final Summary:** Notify the user that the draft is complete or has been refined.
+2.  **Next Steps:** Suggest using the `/review` command to perform a fresh audit of the new or updated draft.
 
 Do not skip any phases. Start with Phase 1.
 """

journal/2026-03-23.md

@@ -7,3 +7,4 @@
 [2026-03-23T05:51:31] - Mark /review command improvement as done and archive task.
 [2026-03-23T06:00:12] - Plan and task for improving /draft command and evolve writer agent.
 [2026-03-23T06:00:52] - Rename reporter agent to writer and update its definition for composition and refinement.
+[2026-03-23T06:01:22] - Update /draft command with branching logic for initial drafting and review-driven refinement.

tests/test_review_command.py

@@ -52,6 +52,14 @@ def test_writer_agent_has_replace():
         content = f.read()
     assert "replace" in content
 
+def test_draft_command_is_multimode():
+    with open(".gemini/commands/draft.toml", "r") as f:
+        content = f.read()
+    assert "Refinement" in content
+    assert "Initial Drafting" in content
+    assert "writer" in content
+    assert "reporter" not in content
+
 if __name__ == "__main__":
     # Simple manual runner for now
     try:
@@ -67,6 +75,7 @@ def test_writer_agent_has_replace():
         test_writer_agent_exists()
         test_reporter_agent_gone()
         test_writer_agent_has_replace()
+        test_draft_command_is_multimode()
 
         print("Tests Passed")
     except AssertionError as e: