From 90821b51ff653475d9fb1bc70b57951d963e8841 Mon Sep 17 00:00:00 2001 From: Fahad Date: Wed, 20 Aug 2025 16:34:08 +0400 Subject: [PATCH] docs: update instructions for precommit --- docs/tools/precommit.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/tools/precommit.md b/docs/tools/precommit.md index 4c0f318..acdc420 100644 --- a/docs/tools/precommit.md +++ b/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)