docs: update instructions for precommit

docs/tools/precommit.md

@@ -13,10 +13,11 @@ The `precommit` tool provides thorough validation of git changes before committi
 The precommit tool implements a **structured workflow** for comprehensive change validation:
 
 **Investigation Phase (Claude-Led):**
-1. **Step 1**: Claude describes the validation plan and begins analyzing git status across repositories
-2. **Step 2+**: Claude examines changes, diffs, dependencies, and potential impacts (minimum 2 steps)
-3. **Throughout**: Claude tracks findings, relevant files, and issues
-4. **Completion**: Once investigation is thorough, Claude signals completion
+1. **Step 1**: Claude states validation strategy using direct statements ("I will examine..." not "Let me examine...")
+2. **Step 2**: Claude examines changes, diffs, dependencies with MANDATORY deeper investigation
+3. **Step 3+**: Claude performs final verification (minimum 3 steps enforced)
+4. **Throughout**: Claude tracks findings, relevant files, and issues with CRITICAL step validation
+5. **Completion**: Only after minimum steps, Claude signals completion and creates changeset file
 
 **For Continuations**: When using `continuation_id` with external validation, Claude will immediately gather git changes and proceed to expert analysis without minimum step requirements.
 
@@ -27,7 +28,11 @@ After Claude completes the investigation (unless precommit_type is **internal**)
 - Requirement compliance assessment
 - Final recommendations for safe commit
 
-**Special Note**: If you want Claude to perform the entire pre-commit validation without calling another model, you can include "don't use any other model" in your prompt, or set the precommit_type to "internal", and Claude will complete the full workflow independently.
+**Special Notes**: 
+- Default validation type is **external** (uses expert model for additional review)
+- To skip expert validation, explicitly request "don't use any other model" or set precommit_type to "internal"
+- **CRITICAL**: Minimum 3 steps are enforced - tool will prevent setting `next_step_required=false` before final step
+- **MANDATORY**: Changeset file (zen_precommit.changeset) must be created for external validation
 
 ## Model Recommendation
 
@@ -120,21 +125,21 @@ Use zen and perform a thorough precommit ensuring there aren't any new regressio
 ## Tool Parameters
 
 **Workflow Investigation Parameters (used during step-by-step process):**
-- `step`: Current investigation step description (required for each step)
-- `step_number`: Current step number in validation sequence (required)
-- `total_steps`: Estimated total investigation steps (adjustable)
-- `next_step_required`: Whether another investigation step is needed
-- `findings`: Discoveries and evidence collected in this step (required)
+- `step`: Technical brief to another engineer using direct statements (required, FORBIDDEN: large code snippets)
+- `step_number`: Current step number in validation sequence (required, starts at 1)
+- `total_steps`: Estimated total investigation steps (minimum 3 enforced)
+- `next_step_required`: Whether another investigation step is needed (CRITICAL: must be true until final step)
+- `findings`: Specific discoveries and evidence from actual investigation (required, no vague language)
 - `files_checked`: All files examined during investigation
 - `relevant_files`: Files directly relevant to the changes
 - `relevant_context`: Methods/functions/classes affected by changes
 - `issues_found`: Issues identified with severity levels
-- `precommit_type`: Type of validation to perform (external/internal, default: external)
+- `precommit_type`: Type of validation to perform (external/internal, default: external - ALWAYS use external unless explicitly told otherwise)
 - `backtrack_from_step`: Step number to backtrack from (for revisions)
 - `images`: Screenshots of requirements, design mockups for validation
 
 **Initial Configuration (used in step 1):**
-- `path`: Starting directory to search for repos (default: current directory, absolute path required)
+- `path`: Starting directory to search for repos (REQUIRED for step 1, must be absolute path)
 - `prompt`: The original user request description for the changes (required for context)
 - `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5|gpt5-mini|gpt5-nano (default: server default)
 - `compare_to`: Compare against a branch/tag instead of local changes (optional)