validation-standards

What this skill does

## Overview

This skill provides comprehensive validation standards for Claude Code tool usage, documentation consistency, and execution flow validation. It defines rules for detecting failures before they occur, identifying common error patterns, and ensuring compliance with best practices.

**When to apply**: Before any file modification, after errors occur, during documentation updates, or when ensuring quality and consistency.

## Tool Usage Validation Standards

### Edit Tool Requirements

**Rule**: Must read file before editing
```
REQUIRED SEQUENCE:
1. Read(file_path)
2. Edit(file_path, old_string, new_string)

VIOLATION SYMPTOMS:
- Error: "File has not been read yet"
- Error: "Read it first before writing"

PREVENTION:
- Track files read in current session
- Validate Read was called before Edit
- Maintain session state of file operations

AUTO-FIX:
IF Edit fails with "not read yet" error
THEN Call Read(file_path) first
THEN Retry Edit operation
```

**Rule**: old_string must exist and be unique
```
REQUIRED:
- old_string appears in file exactly once
- OR use replace_all=true for multiple occurrences

VIOLATION SYMPTOMS:
- Error: "old_string not found"
- Error: "old_string not unique"

PREVENTION:
- Use larger context for uniqueness
- Search file content before editing
- Verify exact match with line numbers

AUTO-FIX:
IF old_string not unique
THEN Expand context with surrounding lines
OR Use replace_all=true parameter
```

### Write Tool Requirements

**Rule**: Read before overwriting existing files
```
REQUIRED FOR EXISTING FILES:
1. Check if file exists (Glob or Bash ls)
2. If exists: Read(file_path) first
3. Then Write(file_path, content)

VIOLATION SYMPTOMS:
- Error: "File has not been read yet"
- Warning: "Overwriting without reading"

PREVENTION:
- Always check file existence first
- Read existing files before writing
- Use Edit instead of Write for modifications

BEST PRACTICE:
- Write: Only for new files
- Edit: For modifying existing files
```

**Rule**: Verify parent directory exists
```
REQUIRED:
- Parent directory must exist before Write
- Use Bash mkdir -p if needed

VIOLATION SYMPTOMS:
- Error: "No such file or directory"
- Error: "Parent directory doesn't exist"

PREVENTION:
- Verify directory structure before Write
- Create directories with mkdir -p
- Use absolute paths to avoid ambiguity

AUTO-FIX:
Extract parent directory from file_path
Check if parent exists
If not: mkdir -p parent_directory
Then: Proceed with Write
```

### NotebookEdit Tool Requirements

**Rule**: Verify cell ID exists
```
REQUIRED:
- cell_id must exist in notebook
- For insert: Specify position or cell_id
- For delete: cell_id must be valid

PREVENTION:
- Read notebook structure first
- Verify cell_id in notebook
- Check cell_type matches operation
```

### Bash Tool Requirements

**Rule**: Use specialized tools instead of Bash
```
PREFER SPECIALIZED TOOLS:
- Read instead of cat/head/tail
- Edit instead of sed/awk
- Write instead of echo > or cat <<EOF
- Grep instead of grep/rg commands
- Glob instead of find/ls

EXCEPTION:
Only use Bash when specialized tool unavailable
- git operations
- npm/pip package managers
- docker/system commands
```

**Rule**: Chain dependent commands with &&
```
REQUIRED FOR DEPENDENCIES:
command1 && command2 && command3

VIOLATION:
command1; command2; command3  # Continues on failure

PREVENTION:
- Use && for sequential dependencies
- Use ; only when failures acceptable
- Use parallel calls for independent commands
```

## Documentation Consistency Standards

### Version Consistency

**Rule**: Synchronize versions across all files
```
FILES REQUIRING VERSION SYNC:
1. .claude-plugin/plugin.json → "version": "X.Y.Z"
2. CHANGELOG.md → ## [X.Y.Z] - YYYY-MM-DD
3. README.md → Version mentions (if any)
4. pattern database → .metadata.plugin_version

VALIDATION:
- Extract version from each file
- Compare all versions
- Flag any mismatches

AUTO-FIX:
Identify canonical version (plugin.json)
Update all other references to match
Create consistency report
```

### Path Consistency

**Rule**: Use consistent paths across documentation
```
COMMON INCONSISTENCIES:
- Standardize to .claude-patterns/ throughout
- learned-patterns.json vs patterns.json
- relative vs absolute paths

VALIDATION:
- Grep for path patterns in all .md files
- Extract unique path variations
- Flag conflicting references

DETECTION REGEX:
\.claude[/-]patterns?/[a-z-]+\.json
\.claude[/-][a-z-]+/

AUTO-FIX:
Determine actual implementation path
Replace all variations with canonical path
Update all documentation files
Verify consistency across project
```

### Component Count Accuracy

**Rule**: Documentation matches actual component counts
```
COMPONENTS TO COUNT:
- Agents: Count agents/*.md files
- Skills: Count skills/*/SKILL.md files
- Commands: Count commands/*.md files

VALIDATION:
actual_agents = count(agents/*.md)
actual_skills = count(skills/*/SKILL.md)
actual_commands = count(commands/*.md)

FOR EACH doc IN [README, CHANGELOG, CLAUDE.md]:
  Extract mentioned counts
  Compare with actual counts
  Flag discrepancies

AUTO-FIX:
Update documentation with actual counts
Add note about component inventory
```

### Cross-Reference Integrity

**Rule**: All referenced files/components must exist
```
REFERENCE TYPES:
- File paths: "See `path/to/file.md`"
- Components: "uses `agent-name` agent"
- Skills: "leverages `skill-name` skill"
- Commands: "run `/command-name`"

VALIDATION:
- Extract all references
- Verify each target exists
- Check naming matches exactly

DETECTION:
- Markdown links: [text](path)
- Inline code: `filename.ext`
- Component names: agent-name, skill-name

AUTO-FIX:
IF reference broken
THEN Search for similar names
OR Remove reference with note
OR Create missing component
```

## Execution Flow Validation

### Dependency Tracking

**Session State Management**:
```python
session_state = {
  "files_read": set(),
  "files_written": set(),
  "tools_used": [],
  "errors_encountered": []
}

# Update on each operation
def track_operation(tool, file_path, result):
    if tool == "Read" and result.success:
        session_state["files_read"].add(file_path)
    elif tool in ["Write", "Edit"]:
        session_state["files_written"].add(file_path)
    session_state["tools_used"].append({
        "tool": tool,
        "file": file_path,
        "timestamp": now(),
        "success": result.success
    })
    if not result.success:
        session_state["errors_encountered"].append({
            "tool": tool,
            "file": file_path,
            "error": result.error_message
        })
```

**Pre-flight Validation**:
```python
def validate_edit(file_path):
    if file_path not in session_state["files_read"]:
        return {
            "valid": False,
            "error": "File has not been read yet",
            "fix": f"Call Read('{file_path}') first"
        }
    return {"valid": True}

def validate_write(file_path):
    file_exists = check_file_exists(file_path)
    if file_exists and file_path not in session_state["files_read"]:
        return {
            "valid": False,
            "warning": "Overwriting without reading",
            "recommendation": f"Read '{file_path}' before overwriting"
        }
    return {"valid": True}
```

### Error Pattern Detection

**Common Error Patterns**:

**Pattern 1: Edit Before Read**
```
Signature:
- Tool: Edit
- Error: "File has not been read yet"

Root Cause:
- Attempted Edit without prior Read

Detection:
- Monitor Edit tool results
- Check for specific error message
- Verify file_path not in files_read set

Auto-Fix:
1. Call Read(file_path)
2. Retry Edit with same parameters
3. Track successful recovery

Learning:
- Store pattern for future prevention
- Increment pre-flight validation confidence
```

**Pattern 2: Path Not Found**
```
Signature:
- Any file tool
- Error: "No such file or directory"

Root Cause:
- Invalid path or typo
- Parent directory doesn't exist

Detection:
- Monitor file operation results