feat(commands): refactor /maintenance into a read-only audit workflow

Author: apiad

.gemini/commands/maintenance.toml

@@ -1,22 +1,33 @@
-description = "Analyze and propose refactoring plans to improve code readability and maintainability."
+description = "Perform a deep, read-only audit of the codebase to identify technical debt and maintenance issues."
+
 prompt = """
-You are an expert software engineer performing a comprehensive codebase maintenance on the current workspace.
+You are a Lead Maintenance Engineer. You are executing the custom `/maintenance` command workflow.
+
+**CRITICAL MANDATE:** This command is strictly for analysis and reporting. You MUST NOT modify any source files. Your goal is to produce a "Maintenance Report Card."
+
+Follow these phases strictly:
 
-**Phase 1: Deep Analysis & Planning**
-Run a deep analysis of the current codebase focusing on performance, security, readability, and overall maintainability.
-**Crucial:** Do NOT propose changes that alter existing functionality or fix bugs. This is strictly a maintenance, clean-up, and refactoring operation.
+### Phase 1: Clarification & Scope
+1.  **Analyze Request:** Identify if the user provided specific instructions or a target area for the maintenance audit.
+2.  **Clarify:** If the scope is ambiguous, use `ask_user` to define the focus (e.g., "Should I focus on DRY violations in the hooks, or general documentation coverage?").
 
-Create a detailed and expressive plan with the following priorities:
-1. **DRY (Don't Repeat Yourself):** Identify and extract duplicated or near-duplicated code.
-2. **Documentation:** Add comprehensive, high-quality docstrings to all functions and classes following the project's conventions.
-3. **Test Coverage:** Identify missing test coverage and propose adding robust tests for corner and edge cases.
-4. **Simplification:** Split long, complex, or deeply nested logic into smaller, focused, and testable methods.
+### Phase 2: Deep Analysis (Codebase Investigator)
+1.  **Invoke Investigator:** Invoke the `codebase_investigator` subagent to perform a comprehensive, non-destructive audit.
+2.  **Audit Priorities:**
+    -   **DRY (Don't Repeat Yourself):** Identify logic duplication across files.
+    -   **Documentation Coverage:** Check for missing docstrings or outdated comments.
+    -   **Test Gaps:** Identify complex functions without corresponding tests.
+    -   **Simplification:** Find deeply nested or overly long methods that need refactoring.
+3.  **User Context:** Ensure the investigator accounts for any specific instructions provided in Phase 1.
 
-Your proposed plan must be highly expressive and detailed. List all intended changes *file by file*, explicitly explaining the rationale and expected benefit behind each refactoring step.
+### Phase 3: Report Card Generation
+1.  **Synthesize Findings:** Consolidate the investigator's findings into a structured "Maintenance Report Card."
+2.  **Persistence:** Save the report to `research/maintainance-report-<date>.md` using `write_file`.
+3.  **Content:** Include a high-level summary, a file-by-file list of detected issues, and specific, actionable suggestions for fixing them.
 
-**Phase 2: User Agreement**
-Stop and present your complete plan to the user. Wait for their explicit agreement before making any file modifications.
+### Phase 4: Advisory
+1.  **Next Steps:** Inform the user that the audit is complete and the report is saved.
+2.  **Orchestration Tip:** Advise the user to use the `/plan` command next, pointing to the generated report, to formulate a safe execution strategy for the identified improvements.
 
-**Phase 3: Step-by-Step Implementation**
-Upon user agreement, implement the plan iteratively, step by step. Ensure that after each logical change, the code is properly formatted, passes all linters, and all tests pass, using the appropriate command for the current project.
-"""
+Do not skip any phases. Start with Phase 1.
+"""

README.md

@@ -75,7 +75,7 @@ The `.gemini/commands/` directory defines specialized workflows that automate ev
 ### 🧹 Phase 3: Content Generation, Maintenance & Documentation
 *   **`/draft`**: Multi-phase workflow to turn research and plans into detailed, high-quality technical documents or articles section-by-section using the `writer` subagent.
 *   **`/review`**: Uses the `reviewer` subagent to perform non-destructive, multi-phase structural and linguistic audits based on the project's style guide.
-*   **`/maintenance`**: Performs a deep scan of the codebase to identify technical debt, refactoring opportunities, and areas to improve test coverage.
+*   **`/maintenance`**: Performs a deep, read-only audit of the codebase using the `codebase_investigator` to identify technical debt and generate a "Maintenance Report Card" in `research/`.
 *   **`/document`**: Analyzes the codebase and journals to generate or update comprehensive project documentation in the `docs/` folder.
 *   **`/cron`**: Manages repetitive background tasks (e.g., health checks, automated reports) using **systemd user timers**.
 

docs/user-guide.md

@@ -198,7 +198,8 @@ Your background automation layer.
 
 Your defense against context rot.
 
-- **How it works:** Performs a comprehensive audit of the codebase to identify technical debt, outdated implementations, or deviations between code and documentation. It presents a detailed refactoring plan for your approval before making any changes, ensuring the repository remains a clean environment for the AI to operate within.
+- **How it works:** Performs a comprehensive, read-only audit of the codebase to identify technical debt, outdated implementations, or documentation gaps using the `codebase_investigator`. It generates a "Maintenance Report Card" in the `research/` directory.
+- **Why it works:** It separates the audit from the implementation, ensuring the codebase remains a clean environment. After an audit, use the `/plan` command to safely execute the suggested improvements.
 
 ---
 

journal/2026-03-23.md

@@ -10,3 +10,4 @@
 [2026-03-23T06:01:22] - Update /draft command with branching logic for initial drafting and review-driven refinement.
 [2026-03-23T06:07:18] - Align README, Style Guide, Docs, and historical entries with writer/reviewer naming.
 [2026-03-23T06:08:20] - Archive completed /draft command and writer agent improvement task.
+[2026-03-23T06:50:29] - Refactor /maintenance command into a read-only audit workflow using codebase_investigator.

tests/test_review_command.py

@@ -60,6 +60,16 @@ def test_draft_command_is_multimode():
     assert "writer" in content
     assert "reporter" not in content
 
+def test_maintenance_command_is_audit():
+    with open(".gemini/commands/maintenance.toml", "r") as f:
+        content = f.read()
+    assert "codebase_investigator" in content
+    assert "Maintenance Report Card" in content
+    assert "research/maintainance-report-" in content
+    assert "Phase 3" in content
+    # Ensure it doesn't mention Step-by-Step Implementation or modification
+    assert "Step-by-Step Implementation" not in content
+
 if __name__ == "__main__":
     # Simple manual runner for now
     try:
@@ -76,6 +86,8 @@ def test_draft_command_is_multimode():
         test_reporter_agent_gone()
         test_writer_agent_has_replace()
         test_draft_command_is_multimode()
+
+        test_maintenance_command_is_audit()
 
         print("Tests Passed")
     except AssertionError as e: