docs: add plan and task for /draft command improvement

Author: apiad

TASKS.md

@@ -18,6 +18,8 @@ Put done tasks into the Archive.
 
 ## Active Tasks
 
+- [ ] Improve the `/draft` command and evolve the `writer` agent to include a review-driven "Refinement Phase." (See plan: plans/improve-draft-command-and-writer-agent.md)
+
 ---
 
 ## Archive

journal/2026-03-23.md

@@ -5,3 +5,4 @@
 [2026-03-23T05:48:51] - Update /draft command to suggest /review instead of /revise.
 [2026-03-23T05:50:16] - Update README, Style Guide, and User Guide to reflect /review and reviewer agent.
 [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.

plans/improve-draft-command-and-writer-agent.md

@@ -0,0 +1,71 @@
+# Plan: Improve `/draft` Command and Evolve `writer` Agent
+
+This plan outlines the migration and enhancement of the legacy `reporter` agent into a more capable `writer` agent, and the corresponding upgrade of the `/draft` command to handle both initial content generation and a new, review-driven "Refinement Phase."
+
+## Objective
+Promote the `reporter` agent to `writer` and upgrade the `/draft` command to implement a full feedback loop. This allows the `writer` agent to ingest `.review.md` files (generated by the `/review` command) and apply suggested improvements directly to the target file.
+
+## Architecture
+- **Agent Evolution:** The `reporter` agent is renamed to `writer`, expanding its role from section expansion to sophisticated refinement and style alignment.
+- **Feedback Loop:** This change closes the loop between the non-destructive `/review` command and the content generation process.
+- **Direct Refinement:** The `/draft` command will include a dedicated "Refinement Phase" that uses the `writer` agent to apply suggested changes from a `.review.md` file directly to the target document.
+
+---
+
+## Detailed Workflow
+
+### Phase 1: Context & Mode Selection
+- **Analyze Request:** Identify the target file for drafting or refinement.
+- **Check for Review:** Search for a corresponding `<filename>.review.md` file.
+- **Branching Logic:**
+    - **Initial Drafting:** If no review exists, follow the current Outline -> Skeleton -> Expansion workflow.
+    - **Refinement Mode:** If a review exists, initiate the Refinement Phase.
+
+### Phase 2: Initial Drafting (Existing Workflow)
+- **Outline Creation:** Generate a detailed Markdown outline based on the Style Guide.
+- **Skeleton Initialization:** Create a target file with placeholders.
+- **Section-by-Section Drafting:** Use the `writer` agent to fill placeholders with detailed prose.
+
+### Phase 3: Refinement Phase (New Mode)
+- **Goal:** Apply suggested improvements from a `.review.md` file.
+- **Action:** The `/draft` command reads the target file and its `.review.md` sidecar.
+- **Agent Invocation:** Invoke the `writer` agent with instructions to process the review findings.
+- **Direct Modification:** The `writer` agent identifies suggested changes (Structural, Substance, or Linguistic) and uses the `replace` tool to update the target file directly.
+- **Consistency Check:** Ensure the modifications maintain a consistent tone and adhere to the Style Guide.
+
+### Finalization
+- **Summary:** Notify the user that the draft has been updated or refined.
+- **Next Steps:** Suggest a final `/review` if significant changes were made.
+
+---
+
+## Implementation Steps
+
+### Step 1: Agent Evolution (Rename & Refactor)
+1.  **Rename File:** Move `.gemini/agents/reporter.md` to `.gemini/agents/writer.md`.
+2.  **Update Agent Definition:** 
+    - Change name from `reporter` to `writer`.
+    - Update the prompt to reflect its role as a "Full-Blown Writer" capable of both original composition and deep refinement.
+    - Explicitly instruct the agent on how to interpret and apply findings from `.review.md` files using the `replace` tool.
+
+### Step 2: Upgrade `/draft` Command (`.gemini/commands/draft.toml`)
+1.  **Update References:** Change all calls from `reporter` to `writer`.
+2.  **Implement Branching:** Update the prompt to check for `.review.md` files and offer a "Refinement Mode."
+3.  **Refine Refinement Logic:** Provide clear instructions for the `writer` agent to perform direct, surgical updates during the Refinement Phase.
+
+### Step 3: Global Alignment
+1.  **Documentation:** Update `docs/user-guide.md` and `docs/design.md` to reflect the new agent name and workflow.
+2.  **Cross-References:** Update mentions of "reporter" in `README.md`, `TASKS.md`, and `CHANGELOG.md`.
+
+---
+
+## Verification Strategy
+
+### 1. Functional Testing
+- **Initial Draft:** Verify `/draft` still works for new documents using the renamed `writer` agent.
+- **Refinement Detection:** Ensure `/draft` correctly identifies a `.review.md` file and enters Refinement Mode.
+- **Direct Replacement:** Confirm the `writer` agent successfully uses `replace` to apply a suggestion from a review file.
+
+### 2. Quality Audit
+- **Style Consistency:** Verify that refined sections still adhere to the project's Style Guide.
+- **Technical Depth:** Ensure the `writer` agent maintains a high level of technical detail (7-8/10) during both drafting and refinement.