[Code Quality] Enhance UV package validation error message with context and bypass option

[github-actions]

Description

The UV package validation error message (pkg/workflow/pip_validation.go:176-181) provides installation instructions but lacks context about when validation runs, why it's checking packages, and how to bypass for experimental/private packages. This blocks users in legitimate scenarios without providing a clear escape hatch.

Problem

Current State:

• Error message explains how to fix (install uv, cache packages)
• Missing context about compile-time validation
• No bypass option for experimental packages or air-gapped environments
• Doesn't explain why validation exists (catch typos early)

User Impact:

• Developers in air-gapped environments blocked without workaround
• Users with experimental packages can't proceed
• No clear understanding of when validation occurs
• Friction for legitimate use cases

Suggested Changes

Enhance the error message at lines 176-181 to include timing context and bypass option:

Before:

return NewValidationError(
    "uv.packages",
    fmt.Sprintf("%d packages require validation", len(errors)),
    "uv package validation requires network access or local cache",
    fmt.Sprintf("Ensure network access or cache uv packages locally:\n\n%s\n\nCache packages:\n$ uv pip install (package-name) --no-cache\n\nOr connect to network for validation", strings.Join(errors, "\n")),
)

After:

return NewValidationError(
    "uv.packages",
    fmt.Sprintf("%d packages require validation", len(errors)),
    "uv package validation requires network access or local cache to verify packages exist on PyPI",
    fmt.Sprintf("Failed to validate uv packages:\n\n%s\n\nThis validation runs at compile-time to catch typos early.\n\nTo fix:\n1. Connect to network for PyPI access\n2. Cache packages locally: $ uv pip install (package-name) --no-cache\n3. For experimental packages, skip validation: GH_AW_SKIP_UV_VALIDATION=true gh aw compile", strings.Join(errors, "\n")),
)

Files Affected

• pkg/workflow/pip_validation.go (lines 176-181) - Enhance error message

Success Criteria

• Error message includes "compile-time" context
• Bypass option documented with environment variable GH_AW_SKIP_UV_VALIDATION
• Three-step fix process clearly numbered
• Maintains professional, helpful tone
• Existing error structure preserved (NewValidationError pattern)
• All existing pip validation tests pass
• Quality rating improves (per UX analysis)

Source

Extracted from User Experience Analysis Report discussion #13799

Task 2: "Enhance Error Context in UV Package Validation"

• Addresses professional communication + efficiency and productivity design principles
• Medium frequency: affects users with custom Python dependencies or network restrictions

Priority

Low - Improves error message quality but not blocking. Nice-to-have for better user experience.

Notes

• Single-file change: pkg/workflow/pip_validation.go only
• Can be completed in 15-20 minutes
• No functional changes, only error message improvement
• Follows error message style guide for validation errors
• Consider implementing the GH_AW_SKIP_UV_VALIDATION environment variable check if not already present

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 6, 2026, 1:25 PM UTC