Pre-flight Plan Auditor

Validates implementation plans and task specifications before Claude begins executing them, catching scope issues, missing requirements, and ambiguous instructions early.

When to Use This Hook

Attach this hook when you need to:

• Verify that implementation plans contain all required sections before work begins
• Catch ambiguous or incomplete task specifications that could lead to wasted effort
• Enforce a structured planning discipline with mandatory acceptance criteria

Consider alternatives when:

• Your team uses lightweight, informal task descriptions intentionally
• The overhead of plan validation slows down quick one-off fixes

Quick Start

Configuration

Copy
name: pre-flight-plan-auditor
type: hook
trigger: PreToolUse
category: quality-gates

Example Trigger

Copy
# Hook triggers before Claude starts implementing from a spec file
claude> Read and implement tasks.spec.md
# Auditor validates the spec structure before execution begins

Example Output

Pre-flight Plan Audit: tasks.spec.md
  Objective statement: FOUND
  Acceptance criteria: FOUND (4 criteria)
  Files to modify: FOUND (6 files listed)
  Edge cases: MISSING
  Rollback plan: MISSING
Audit result: 2 warnings. Proceeding with advisory.

Core Concepts

Audit Checklist Overview

Aspect	Details
Objective Statement	Clear description of what the plan aims to achieve
Acceptance Criteria	Measurable conditions that define completion
File Scope	Explicit list of files to create or modify
Edge Cases	Documented edge cases and how they are handled
Rollback Plan	Steps to revert changes if implementation fails

Audit Workflow

Plan File Detected
       |
  Parse Sections
       |
  ┌────┼────┬─────┐
  |    |    |     |
 Obj  AC  Files  Edge
  |    |    |   Cases
  └────┼────┴─────┘
       |
  Score Completeness
       |
  ┌────┴────┐
  |         |
 Pass     Warnings
  |         |
Proceed  Proceed +
         Advisory

Configuration

Parameter	Type	Default	Description
required_sections	string[]	["objective","acceptance_criteria","files"]	Sections that must be present
advisory_sections	string[]	["edge_cases","rollback"]	Sections that generate warnings if missing
block_on_missing	boolean	false	Block execution if required sections are missing
min_criteria_count	number	2	Minimum number of acceptance criteria required
spec_patterns	string[]	["*.spec.md","*.plan.md"]	File patterns recognized as plan documents

Best Practices

1. Start Advisory, Then Strict - Begin with the auditor in advisory mode (warnings only) while your team develops the habit of writing structured plans. Switch to blocking mode once plans consistently pass.

2. Define a Plan Template - Provide a plan template with all required sections pre-filled. Teams fill in specifics rather than remembering section names, making the auditor a validator rather than a learning curve.

3. Require Acceptance Criteria - The most impactful section to enforce is acceptance criteria. Without them, there is no objective measure of whether the implementation succeeded.

4. Include Rollback Plans for Large Changes - Any plan touching more than 3 files should include rollback steps. The auditor can enforce this with a conditional rule based on file count.

5. Audit at the Right Granularity - Audit high-level implementation plans, not individual edit operations. The hook should trigger when reading spec files, not on every file edit.

Common Issues

1. Over-Validation on Simple Tasks - Requiring full specs for one-line bug fixes creates friction. Add a complexity tag to plans and relax requirements for tasks marked as simple.

2. Section Detection Heuristics - The auditor uses heading text to identify sections. Non-standard heading names (e.g., "Goals" vs "Objective") may not be recognized. Support aliases for each required section.

3. Stale Plans After Changes - Plans written at the start may diverge from the actual implementation. Consider a post-implementation audit that compares completed work against the original plan.