Technical Design: plan-validation-checks

Technical Design: plan-validation-checks

Metadata

• Feature: plan-validation-checks
• Status: APPROVED
• Created: 2026-02-05
• Updated: 2026-02-06
• Author: Factory Design Mode

1. Overview

1.1 Summary

Phase 0 validation sections already exist in both plan.core.md and design.core.md. The remaining work is adding the --skip-validation flag (NFR-2) to both commands so users can bypass validation when needed.

1.2 Goals

• Add --skip-validation flag to /z:plan Flags section
• Add --skip-validation flag to /z:design (new Flags section + Help section update)
• Wire flag into Phase 0 conditional skip logic

1.3 Non-Goals

• Modifying existing Phase 0 validation logic (already correct)
• Adding Python code (prompt instructions only)
• Adding tests (markdown command files, not code)

2. Architecture

2.1 High-Level Design

Documentation-only change. Each command file gets 3 edits:

plan.core.md:
  1. Add --skip-validation to ## Flags section
  2. Add conditional skip at top of Phase 0
  3. Add --skip-validation to ## Help section

design.core.md:
  1. Add new ## Flags section with --skip-validation
  2. Add conditional skip at top of Phase 0
  3. Add --skip-validation to ## Help section

2.2 Component Breakdown

2.3 Data Flow

1. User invokes /z:plan feature --skip-validation or /z:design --skip-validation
2. Command parses $ARGUMENTS for --skip-validation
3. If present: skip Phase 0 entirely, continue to next phase
4. If absent: run Phase 0 as normal

3. Detailed Design

3.1 plan.core.md Changes

Edit 1 — Flags section (line ~18):

## Flags

- `--socratic` or `-s`: Use structured 3-round discovery mode (see details file)
- `--rounds N`: Number of rounds (default: 3, max: 5)
- `--skip-validation`: Skip Phase 0 pre-execution validation checks

Edit 2 — Phase 0 section (line ~45), add at start:

## Phase 0: Pre-Execution Validation

If `--skip-validation` is in $ARGUMENTS, skip this phase entirely and continue to Enter Plan Mode.

Before proceeding, validate this plan hasn't been superseded:
...

Edit 3 — Help section (line ~200):

/zerg:plan — Capture complete requirements for a feature.

Flags:
  -s, --socratic        Use structured 3-round discovery mode
  --rounds N            Number of rounds (default: 3, max: 5)
  --skip-validation     Skip pre-execution validation checks
  --help                Show this help message

3.2 design.core.md Changes

Edit 1 — Add new Flags section after Pre-Flight, before Phase 0:

## Flags

- `--skip-validation`: Skip Phase 0 pre-execution validation checks

Edit 2 — Phase 0 section (line ~30), add at start:

## Phase 0: Pre-Execution Validation

If `--skip-validation` was specified, skip this phase entirely and continue to Load Context.

Before proceeding, validate this design is still needed:
...

Edit 3 — Help section (line ~710):

/zerg:design — Generate technical architecture and prepare for parallel execution.

Flags:
  --skip-validation     Skip pre-execution validation checks
  --help                Show this help message

4. Key Decisions

4.1 Flag in $ARGUMENTS vs. Separate Mechanism

Context: How should --skip-validation be parsed?

Options Considered:

1. Check $ARGUMENTS string for "--skip-validation"
2. Environment variable ZERG_SKIP_VALIDATION
3. Config option in .zerg/config.yaml

Decision: Option 1 — Check $ARGUMENTS

Rationale: Consistent with existing --socratic and --rounds flags in plan.core.md. No code needed — the Claude prompt just checks if the string is present.

Consequences: Simple, per-invocation control. No persistent config needed.

5. Implementation Plan

5.1 Phase Summary

5.2 File Ownership

5.3 Dependency Graph

graph TD
    T001[TASK-001: Plan --skip-validation] --> T003[TASK-003: Changelog + wiring]
    T002[TASK-002: Design --skip-validation] --> T003

6. Risk Assessment

7. Testing Strategy

7.1 Unit Tests

N/A — prompt instruction changes, not Python code.

7.2 Integration Tests

Manual: run /z:plan test-feature --skip-validation and verify Phase 0 is skipped.

7.3 Verification Commands

• grep -q 'skip-validation' zerg/data/commands/plan.core.md
• grep -q 'skip-validation' zerg/data/commands/design.core.md

8. Parallel Execution Notes

8.1 Safe Parallelization

• TASK-001 and TASK-002 modify different files — fully parallel
• TASK-003 depends on both completing first

8.2 Recommended Workers

• Minimum: 1 worker
• Optimal: 2 workers
• Maximum: 2 workers

8.3 Estimated Duration

• Single worker: 10 min
• With 2 workers: 7 min
• Speedup: 1.4x

9. Approval