patch-verification

name	patch-verification
description	Use after applying any patch to thoroughly verify the agent codebase has no bugs — checks syntax, imports, runtime behavior, docstrings, templates, hooks, and logical correctness

Patch Verification

Overview

A patch that crashes or introduces bugs at runtime is worse than no patch at all. Every patch must pass thorough verification before being committed.

Only fix what would actually crash or produce incorrect behavior — do NOT change the patch's intent.

When to Use

After applying ANY patch type (capability or steering).

Verification Procedure

Step 1: Review the Diff

git diff

• Does the diff match your intent? No unintended changes?
• Are there leftover debug statements, commented-out code, or TODOs?
• Are there any files modified that should not have been changed?

Step 2: Syntax and Import Check

For every modified Python file:

python3 -m py_compile <modified_file>
python3 -c "import <modified_module>"

• No SyntaxError, IndentationError, or TabError
• No ImportError or ModuleNotFoundError
• No NameError from undefined variables or functions at module level

Step 3: Docstring Integrity

Docstrings are the agent's only interface to tools — errors here directly cause agent failures.

• No placeholder values ([...], {...}, <placeholder>) — these crash downstream parsers
• All examples use concrete, valid values
• Parameter names in the docstring match the actual method signature
• Return value description matches what the implementation actually returns
• No stale documentation from copy-paste (e.g., wrong tool name, wrong parameter list from another method)
• No literal escape sequences (\n, \t, etc.) used to represent multi-line examples or formatting inside docstrings — these produce actual control characters in the parsed string and can cause SyntaxError or silently corrupt the docstring text. Use triple-quoted strings with real newlines instead

Step 4: Template String Safety

If the patch modifies any string that uses .format() or f-string interpolation:

• Every {placeholder} has a corresponding .format() argument
• No extra or missing placeholders from copy-paste
• No unescaped curly braces in literal text (use {{ and }} to escape)
• No cross-file contamination between template variables

Step 5: Hook JSON Validation

If the patch modifies hook configuration:

python3 -c "import json; json.load(open('<hook_file>'))"

• Valid JSON syntax (no trailing commas, unquoted keys, etc.)
• Correct schema structure (hooks array with matcher + handler entries)
• Each matcher regex compiles without error:

  python3 -c "import re; re.compile('<matcher_value>')"
  

• Handler type matches the expected type for the hook category (e.g., "reminder" for PreToolUse hooks)
• Each handler has non-blank text content

Step 6: Logic and Correctness

Read each modified function/method end-to-end and verify:

• Control flow: No unreachable code, no missing return statements, no infinite loops
• Edge cases: Does the code handle empty inputs, None values, missing keys, and boundary conditions?
• Type consistency: Are function arguments and return values used consistently with their expected types?
• Variable scope: No shadowed variables, no use-before-assignment, no stale references to renamed variables
• Side effects: Does the change unintentionally modify shared state, global variables, or mutable default arguments?
• Dependencies: If the modified function is called by other modules, verify the signature change is backward-compatible (e.g., new parameters have defaults)

Step 7: Integration Check

• If a new tool was added, verify it is discoverable by the agent (registered, decorated, or configured correctly per the codebase's conventions)
• If a tool signature changed, verify all existing callers pass the correct arguments
• If prompt text was modified, verify the complete prompt still renders correctly (no broken concatenation, no missing sections)

Step 8: Preserve Intent

After all verification, re-read git diff one final time:

• Only fix runtime crash or correctness issues found during verification
• Do NOT remove functionality or change patch behavior
• Do NOT alter logic beyond what prevents crashes or bugs