Description

Implement a CLI wizard tool to help users create valid and physically sensible input YAML files for SUEWS simulations. This interactive tool will leverage the existing Pydantic-based data models to provide real-time validation and guidance.

Motivation

• The traditional way of setting up SUEWS input YAML files through manual editing is error-prone and time-consuming
• The runctrl-based table format is not user-friendly and will be deprecated
• Users need guidance to ensure their configurations are both syntactically valid and physically sensible

Proposed Solution

Create an interactive CLI wizard that:

• Guides users step-by-step through configuration creation
• Provides real-time validation using Pydantic models
• Offers templates for common scenarios (urban, suburban, rural)
• Supports undo/redo functionality
• Shows progress indicators and contextual help

Specification

Complete Kiro specification available at: .claude/specs/yaml-config-builder/

• Requirements: 16 functional + 7 non-functional requirements in EARS notation
• Design: Component architecture, UI mockups, state management
• Tasks: 5-phase implementation plan (~15-20 days effort)

Key Features

1. Interactive Wizard Interface

   • Step-by-step guidance through all configuration sections
   • Progressive disclosure of options based on user choices
   • Clear progress indicators

2. Real-time Validation

   • Immediate feedback using Pydantic models
   • Physical sensibility checks
   • Conditional validation based on model options

3. User Experience

   • Undo/redo support at each step
   • Keyboard navigation with shortcuts
   • Colour-coded validation feedback
   • Contextual help for all parameters

4. Template System

   • Pre-configured templates for common use cases
   • Import existing configurations for modification
   • Validation-only mode for existing files

Technical Approach

• CLI Framework: Click + Rich for modern terminal UI
• Architecture: State machine-based wizard flow
• Validation: Leverage existing Pydantic models in src/supy/data_model/
• Integration: Add as subcommand to existing suews CLI

Related Issues

• Pydantic Hierarchy #400: Pydantic Hierarchy - Conditional validation patterns
• Pydantic-related cleanup #392: Pydantic-related cleanup - Parameter validation mapping

Implementation Plan

Phase 1: Foundation (state management, wizard engine)
Phase 2: Core wizard steps (basic, forcing, surface, initial conditions)
Phase 3: Advanced features (conditional validation, templates)
Phase 4: User experience polish
Phase 5: Integration and documentation

Success Criteria

• Users can create valid YAML configurations in < 5 minutes
• Validation response time < 100ms
• Support for all SUEWS configuration parameters
• Positive user feedback on usability