[repository-quality] 🎯 Repository Quality Improvement Report - Error Message Quality & User Experience #33768

2026-05-21T13:58:44Z

github-actions[bot]
Bot May 21, 2026

Analysis Date: 2026-05-21
Focus Area: Error Message Quality & User Experience
Strategy Type: Custom
Custom Area: Yes — Error messaging is critical for CLI tools; this analysis evaluates consistency, actionability, and adherence to the error-messages skill guidelines.

Executive Summary

gh-aw demonstrates strong error wrapping practices (65.2% of errors use %w for proper context propagation) and has established comprehensive error message guidelines in .github/skills/error-messages/SKILL.md. However, analysis reveals significant inconsistencies in user-facing error output patterns:

Key Findings:

1,844 raw fmt.Errorf calls vs only 70 console-formatted error messages
64 instances of diagnostic output incorrectly using fmt.Println (stdout) instead of stderr
37 of 31 CLI command files use console.FormatErrorMessage, but many still mix raw error output
Validation files (38,838 total LOC) show mixed adherence to the error-messages skill template

Impact: Inconsistent error formatting degrades user experience, makes errors harder to scan in terminal output, and violates the repository's own console formatting standards documented in AGENTS.md.

Full Analysis Report

Focus Area: Error Message Quality & User Experience

Current State Assessment

The repository has established strong foundations:

Comprehensive error message guidelines in .github/skills/error-messages/SKILL.md
Console formatting package with dedicated message types
Validation architecture with structured error handling
Good error wrapping practices (65.2% adoption rate)

Metrics Collected:

Metric	Value	Status
Raw `fmt.Errorf` calls	1,844	⚠️ High volume
Console-formatted errors	70	❌ Low adoption
Error wrapping rate (`%w`)	65.2%	✅ Good
`fmt.Println` in CLI (diagnostic)	64	❌ Should use stderr
Console formatting helpers used	1,514 total	✅ Good infrastructure
Validation code size	38,838 LOC	i️ Large surface area
CLI command files	31	i️ Baseline
Commands with Examples section	26/31	✅ Strong (84%)

Findings

Strengths

Strong error wrapping: 65.2% of errors use %w for proper context propagation
Established guidelines: .github/skills/error-messages/SKILL.md provides clear patterns
Console infrastructure: pkg/console/ package supports consistent formatting
Good help text: 84% of CLI commands include Examples sections
Validation examples: Files like docker_validation.go show excellent actionable error messages

Areas for Improvement

High Severity:

Inconsistent error formatting — Only 70 console-formatted errors vs 1,844 raw errors
- Impact: Users see inconsistent terminal output; errors harder to visually scan
- Location: Across pkg/workflow/*validation*.go (38,838 LOC) and pkg/cli/
Diagnostic output to stdout — 64 fmt.Println calls should use stderr
- Impact: Violates Unix conventions; breaks pipeable workflows
- Location: pkg/cli/audit_cross_run_render.go, compile_stats.go, etc.

Medium Severity:
3. Bare return err without context — ~20 instances in compile/run commands

Impact: Loses error context when propagating failures
Location: pkg/cli/compile_infrastructure.go:29,59, compile_pipeline.go, etc.

Generic error messages — Many "invalid X" or "failed to Y" messages lack examples
- Impact: Users don't know how to fix configuration errors
- Location: Validation files with short error messages

Low Severity:
5. Missing error message audit — No systematic check for guideline compliance

Impact: Guidelines exist but no enforcement mechanism

Detailed Analysis

1. Console Formatting Adoption Gap

Current state: The repository has excellent console formatting infrastructure:

// Available but underutilized
FormatSuccessMessage: 214 uses
FormatInfoMessage: 659 uses  
FormatWarningMessage: 536 uses
FormatErrorMessage: 70 uses ← Only 3.8% of errors!

Problem: Validation code returns raw errors:

// ❌ Current pattern in validation files
return fmt.Errorf("invalid engine.model for engine '%s': %w", engine.GetID(), err)

// ✅ Should format at CLI boundary
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))

Root cause: Validation functions correctly return structured errors, but CLI commands don't consistently apply console formatting before display.

2. Output Stream Violations

Files with incorrect stdout usage (should use stderr):

pkg/cli/audit_cross_run_render.go — 13+ diagnostic fmt.Println calls
pkg/cli/compile_stats.go — Recovery plan output to stdout
pkg/cli/domains_command.go — Status messages to stdout
pkg/cli/forecast.go — Analysis output to stdout (1,142 LOC file)
pkg/cli/hash_command.go — Hash output correctly uses stdout ✅

Unix convention violation:

// ❌ WRONG - Diagnostic to stdout
fmt.Println("## Executive Summary")
fmt.Println("## Metrics Trends")

// ✅ CORRECT - Diagnostic to stderr, structured to stdout
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Generating report..."))
fmt.Println(jsonOutput) // Only structured data to stdout

3. Error Context Loss

Pattern: Bare return err loses context:

// pkg/cli/compile_infrastructure.go:29,59
if err != nil {
    return err  // ❌ No context about what failed
}

// ✅ Better
if err != nil {
    return fmt.Errorf("failed to validate workflow structure: %w", err)
}

Impact: Error chains become opaque; users can't determine root cause.

4. Error Message Quality Examples

Excellent (follows skill guidelines):

// docker_validation.go - actionable, with example
return fmt.Errorf(
    "container image '%s' not found and could not be pulled: %s. " +
    "Please verify the image name and tag.\n\n" +
    "Example:\ntools:\n  my-tool:\n    container: \"node:20\"\n\n" +
    "Or:\ntools:\n  my-tool:\n    container: \"ghcr.io/owner/image:latest\"\n\n" +
    "See: %s",
    image, outputStr, constants.DocsToolsURL,
)

Needs improvement (too generic):

// Various validation files
return fmt.Errorf("invalid cache-memory scope %q: must be one of %v", entry.Scope, validCacheMemoryScopes)
// ❌ Missing: example of valid configuration

// ✅ Better
return fmt.Errorf(
    "invalid cache-memory scope '%s': must be one of %v.\n\n" +
    "Example:\ncache-memory:\n  - id: state\n    scope: repository\n\n" +
    "See: %s",
    entry.Scope, validCacheMemoryScopes, constants.DocsCacheMemoryURL,
)

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Audit and Fix CLI Error Formatting

Priority: High
Estimated Effort: Medium
Focus Area: Error Message Quality

Description: Systematically audit all CLI command files to ensure errors are formatted using console.FormatErrorMessage() before output to stderr. Fix the 37 command files that currently use raw error output.

Acceptance Criteria:

All fmt.Fprintln(os.Stderr, err) patterns replaced with console.FormatErrorMessage(err.Error())
No bare fmt.Fprintln(os.Stderr, err) calls in pkg/cli/*_command.go files
All error outputs go to stderr with console formatting
Run make lint && make test-unit successfully
Verify visually that errors display with proper styling in terminal

Code Region: pkg/cli/*_command.go, specifically files matching grep -l 'fmt\.Fprintln.*os\.Stderr.*err' pkg/cli/*.go

---
workflow: fix-cli-error-formatting
engine: copilot
---

You are a Go developer improving error message consistency in the gh-aw CLI tool.

## Task

Audit and fix all CLI command files to use console formatting for errors:

1. Find all instances where errors are output to stderr without console formatting
2. Replace patterns like `fmt.Fprintln(os.Stderr, err)` with `fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))`
3. Ensure all diagnostic error output goes to stderr (not stdout)
4. Verify that structured output (JSON, hashes, graphs) correctly uses stdout

## Files to Fix

Run this command to identify affected files:
```bash
grep -l 'fmt\.Fprintln.*os\.Stderr' pkg/cli/*.go | grep -v '_test.go'

Priority files:

pkg/cli/access_log.go
pkg/cli/add_command.go
pkg/cli/audit.go
pkg/cli/compile_*.go (multiple files)
All other CLI command files with raw error output

Guidelines

Error Formatting Rule (from AGENTS.md):

// ❌ WRONG
fmt.Fprintln(os.Stderr, err)

// ✅ CORRECT  
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))

Output Routing (from AGENTS.md):

Diagnostic output (messages, warnings, errors) → stderr with console formatting
Structured data (JSON, hashes, graphs) → stdout (no formatting)

Validation

After making changes:

Run make build && make fmt
Run make lint and verify zero errors
Run make test-unit to ensure tests pass
Manually test a command to verify error styling

Example Fix

Before:

if err := validateConfig(cfg); err != nil {
    fmt.Fprintln(os.Stderr, err)
    return err
}

After:

if err := validateConfig(cfg); err != nil {
    fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))
    return err
}

Work systematically through the affected files and create a single PR with all fixes.


---

#### Task 2: Fix Diagnostic Output Stream Violations

**Priority**: High
**Estimated Effort**: Medium
**Focus Area**: User Experience

**Description:** Fix the 64 instances where diagnostic output incorrectly uses `fmt.Println` (stdout) instead of stderr. Structured output (JSON, hashes) should remain on stdout, but all diagnostic messages must move to stderr.

**Acceptance Criteria:**
- [ ] All diagnostic `fmt.Println` calls replaced with `fmt.Fprintln(os.Stderr, console.Format*Message(...))`
- [ ] Structured output (JSON, hashes, graphs) correctly uses stdout
- [ ] Users can pipe command output without diagnostic noise
- [ ] Run `make test-unit` successfully
- [ ] Verify `gh aw compile workflow.md | jq` works without JSON parsing errors

**Code Region:** `pkg/cli/audit_cross_run_render.go`, `pkg/cli/compile_stats.go`, `pkg/cli/domains_command.go`, `pkg/cli/forecast.go`, and others identified by `grep -n 'fmt\.Println' pkg/cli/*.go | grep -v '_test.go' | grep -v 'json\|hash'`

```markdown
---
workflow: fix-output-stream-violations
engine: copilot
---

You are a Go developer fixing Unix convention violations in the gh-aw CLI tool.

## Task

Fix all instances where diagnostic output incorrectly goes to stdout instead of stderr:

1. Identify all `fmt.Println` calls that output diagnostic messages (not structured data)
2. Replace with `fmt.Fprintln(os.Stderr, console.Format*Message(...))`
3. Preserve stdout for structured output (JSON, hashes, Mermaid graphs)
4. Ensure commands are pipeable without diagnostic noise

## Unix Output Convention

**From AGENTS.md:**
- **Diagnostic output** (messages, warnings, errors) → stderr
- **Structured data** (JSON, hashes, graphs) → stdout
- **Rationale**: Allows users to pipe/redirect data without diagnostic noise

## Files to Fix

Run this command to identify affected files:
```bash
grep -n 'fmt\.Println' pkg/cli/*.go | grep -v '_test.go' | grep -v 'json\|hash'

Priority files:

pkg/cli/audit_cross_run_render.go — Markdown report headers to stderr
pkg/cli/compile_stats.go — Recovery plan output to stderr
pkg/cli/domains_command.go — Status messages to stderr
pkg/cli/forecast.go — Analysis output to stderr (large file: 1,142 LOC)

Guidelines

Diagnostic Output:

// ❌ WRONG - Diagnostic to stdout
fmt.Println("## Executive Summary")
fmt.Println("Processing workflow...")

// ✅ CORRECT - Diagnostic to stderr with formatting
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("## Executive Summary"))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Processing workflow..."))

Structured Output (keep on stdout):

// ✅ CORRECT - JSON/hash/graph to stdout
fmt.Println(string(jsonBytes))  // JSON output
fmt.Println(hash)                // Hash output  
fmt.Println(mermaidGraph)        // Graph output

Validation

After making changes:

Run make build && make fmt
Test piping: ./gh-aw compile workflow.md 2>/dev/null should show only structured output
Test diagnostics: ./gh-aw compile workflow.md >/dev/null should show progress to terminal
Run make test-unit to ensure tests pass

Example Fix

Before:

fmt.Println("## Audit Report — Cross-Run Analysis")
fmt.Println()
fmt.Println("## Executive Summary")

After:

fmt.Fprintln(os.Stderr, console.FormatInfoMessage("## Audit Report — Cross-Run Analysis"))
fmt.Fprintln(os.Stderr)
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("## Executive Summary"))

Work systematically through the affected files and create a single PR with all fixes.


---

#### Task 3: Improve Validation Error Messages with Examples

**Priority**: Medium  
**Estimated Effort**: Large
**Focus Area**: Error Message Quality

**Description:** Enhance validation error messages to follow the error-messages skill guidelines: include what's wrong, what's expected, and a concrete example. Focus on the top 10 most frequently triggered validation errors.

**Acceptance Criteria:**
- [ ] Top 10 validation errors include concrete YAML examples
- [ ] Error messages follow the template: `[what's wrong]. [what's expected]. [example]`
- [ ] Each error includes a docs URL when available
- [ ] Run `make test-unit` successfully (update tests if needed)
- [ ] Validation tests verify error message content includes examples

**Code Region:** `pkg/workflow/*validation*.go` files, prioritizing `agent_validation.go`, `docker_validation.go`, `tools_validation_github.go`, `cache_validation.go`

```markdown
---
workflow: improve-validation-error-messages  
engine: copilot
---

You are a Go developer improving error message quality in gh-aw validation code.

## Task

Enhance validation error messages to be more actionable and example-driven:

1. Review error messages in validation files for adherence to guidelines
2. Add concrete YAML examples to error messages that lack them
3. Follow the error-messages skill template: [what's wrong]. [what's expected]. [example]
4. Include docs URLs where available (constants.Docs* URLs)

## Error Message Skill Guidelines

Read the full guidelines at `.github/skills/error-messages/SKILL.md`.

**Template:**

[what's wrong]. [what's expected]. [example of correct usage]


**Constructive language:**
- Avoid only-negative: "invalid", "cannot", "must", "failed"  
- Prefer constructive: "expected" + format, "requires" + precondition, "should" + example

## Priority Files

Focus on these validation files with high error frequency:
1. `pkg/workflow/agent_validation.go` — Engine configuration errors
2. `pkg/workflow/docker_validation.go` — Container image errors (already has good examples)
3. `pkg/workflow/cache_validation.go` — Cache-memory configuration errors
4. `pkg/workflow/tools_validation_github.go` — GitHub toolset errors
5. `pkg/workflow/command_dispatch_validation.go` — Workflow dispatch errors

## Example Improvements

**Before (too generic):**
```go
return fmt.Errorf("invalid cache-memory scope %q: must be one of %v", 
    entry.Scope, validCacheMemoryScopes)

After (actionable with example):

return fmt.Errorf(
    "invalid cache-memory scope '%s': must be one of %v.\n\n" +
    "Example:\ncache-memory:\n  - id: state\n    scope: repository\n\n" +
    "See: %s",
    entry.Scope, validCacheMemoryScopes, constants.DocsCacheMemoryURL,
)

Before (missing example):

return fmt.Errorf("engine.model is required for engine '%s' and must use " +
    "provider/model format (for example: copilot/gpt-5, anthropic/claude-sonnet-4, " +
    "openai/gpt-4.1)", engine.GetID())

After (with YAML example):

return fmt.Errorf(
    "engine.model is required for engine '%s' and must use provider/model format.\n\n" +
    "Example:\nengine:\n  id: %s\n  model: anthropic/claude-sonnet-4\n\n" +
    "Valid formats: copilot/gpt-5, anthropic/claude-sonnet-4, openai/gpt-4.1\n\n" +
    "See: %s",
    engine.GetID(), engine.GetID(), constants.DocsEnginesURL,
)

Validation

After making changes:

Run make build && make fmt
Run make lint and verify zero errors
Run make test-unit — update test expectations if error messages changed
Manually trigger validation errors to verify improved messages

Notes

Start with 5-10 high-impact errors rather than all validation errors
Update corresponding test files if error message assertions need changes
Use existing docker_validation.go as a reference for good error messages
Keep examples minimal and valid YAML (2-space indentation)

Create a single PR with improved error messages for the top validation errors.


---

#### Task 4: Add Error Context to Bare Return Statements

**Priority**: Medium
**Estimated Effort**: Small
**Focus Area**: Error Message Quality

**Description:** Fix instances where errors are returned without context (bare `return err`) in compile and run commands. Add descriptive context so users understand what operation failed.

**Acceptance Criteria:**
- [ ] No bare `return err` in `pkg/cli/compile*.go` and `pkg/cli/run*.go` files
- [ ] All error returns include operation context via `fmt.Errorf("failed to X: %w", err)`
- [ ] Error chains are traceable from CLI command to root cause  
- [ ] Run `make test-unit` successfully

**Code Region:** `pkg/cli/compile_infrastructure.go:29,59`, `pkg/cli/compile_pipeline.go`, `pkg/cli/run.go`, `pkg/cli/run_workflow_execution.go`

```markdown
---
workflow: add-error-context
engine: copilot  
---

You are a Go developer improving error context in the gh-aw CLI tool.

## Task

Add descriptive context to bare `return err` statements in compile and run commands:

1. Find all `return err` statements in compile and run command files
2. Add context describing what operation failed
3. Use `fmt.Errorf("failed to X: %w", err)` pattern for error wrapping
4. Ensure error chains are traceable from CLI entry point to root cause

## Files to Fix

Run this command to identify affected locations:
```bash
grep -n 'return err$' pkg/cli/compile*.go pkg/cli/run*.go

Priority locations:

pkg/cli/compile_infrastructure.go:29 — Line 29: add context
pkg/cli/compile_infrastructure.go:59 — Line 59: add context
pkg/cli/compile_pipeline.go — Multiple locations (478, 489, 533, 542, 555, 560, 594)
pkg/cli/run.go — Lines 28, 37, 75, 84
pkg/cli/run_workflow_execution.go — Multiple locations

Guidelines

Error Wrapping Best Practice:

// ❌ WRONG - Loses context
if err != nil {
    return err
}

// ✅ CORRECT - Adds operation context
if err != nil {
    return fmt.Errorf("failed to validate workflow structure: %w", err)
}

Context Guidelines:

Describe the operation that failed ("failed to compile workflow", "failed to push changes")
Use %w to preserve error chain for errors.Is() and errors.As()
Be specific about what was being processed ("failed to parse frontmatter in %s", workflowPath)

Validation

After making changes:

Run make build && make fmt
Run make lint and verify zero errors
Run make test-unit to ensure tests pass
Manually trigger an error to verify full error chain displays context

Example Fix

Before (bare return):

// pkg/cli/compile_infrastructure.go:29
if err := setupWorkspace(cfg); err != nil {
    return err  // ❌ No context
}

After (with context):

// pkg/cli/compile_infrastructure.go:29  
if err := setupWorkspace(cfg); err != nil {
    return fmt.Errorf("failed to setup compilation workspace: %w", err)
}

Before (bare return in loop):

// pkg/cli/compile_pipeline.go:478
for _, file := range files {
    if err := compile(file); err != nil {
        return err  // ❌ Which file failed?
    }
}

After (with context):

// pkg/cli/compile_pipeline.go:478
for _, file := range files {
    if err := compile(file); err != nil {
        return fmt.Errorf("failed to compile %s: %w", file, err)
    }
}

Work systematically through the affected files and create a single PR with all fixes.


---

#### Task 5: Create Error Message Compliance Linter

**Priority**: Low
**Estimated Effort**: Medium  
**Focus Area**: Error Message Quality

**Description:** Create a custom Go linter (in `pkg/linters/`) that checks for common error message anti-patterns: bare `return err` in CLI files, `fmt.Fprintln(os.Stderr, err)` without console formatting, and `fmt.Println` diagnostic output in non-test CLI files.

**Acceptance Criteria:**
- [ ] New linter `pkg/linters/errormessage/analyzer.go` created
- [ ] Linter detects: bare `return err`, unformatted stderr errors, stdout diagnostics
- [ ] Linter integrated into `make lint` workflow
- [ ] Linter passes on codebase after Tasks 1-4 are complete  
- [ ] Linter tests in `pkg/linters/errormessage/analyzer_test.go` cover all patterns
- [ ] Documentation in `pkg/linters/README.md` updated

**Code Region:** `pkg/linters/errormessage/` (new directory), `pkg/linters/linters.go` (register analyzer), `.golangci.yml` (enable linter)

```markdown
---
workflow: create-error-message-linter
engine: copilot
---

You are a Go developer creating a custom linter for gh-aw error message quality.

## Task

Create a custom Go analysis linter that enforces error message best practices:

1. Create `pkg/linters/errormessage/analyzer.go` following existing linter patterns
2. Implement checks for common anti-patterns
3. Integrate linter into `pkg/linters/linters.go` and `make lint`
4. Write comprehensive tests in `analyzer_test.go`

## Anti-Patterns to Detect

### 1. Bare `return err` in CLI Commands
**Pattern:** `return err` without wrapping in `pkg/cli/*.go` files
**Message:** "add context to error return using fmt.Errorf(\"failed to X: %w\", err)"

### 2. Unformatted Error Output  
**Pattern:** `fmt.Fprintln(os.Stderr, err)` or `fmt.Fprintf(os.Stderr, ..., err)`
**Message:** "use console.FormatErrorMessage(err.Error()) for error output"

### 3. Diagnostic Output to Stdout
**Pattern:** `fmt.Println(...)` in `pkg/cli/*.go` (non-test) without JSON/hash context
**Message:** "diagnostic output should use fmt.Fprintln(os.Stderr, console.Format*Message(...))"

## Implementation Guide

Follow the pattern from existing linters like `pkg/linters/workflowcall/`:

1. **Create analyzer structure:**
```go
package errormessage

import "golang.org/x/tools/go/analysis"

var Analyzer = &analysis.Analyzer{
    Name: "errormessage",
    Doc:  "checks for error message anti-patterns in CLI code",
    Run:  run,
}

func run(pass *analysis.Pass) (any, error) {
    // Implementation
}

Inspect AST for patterns:
- Look for ast.ReturnStmt with bare err identifier in pkg/cli/
- Look for ast.CallExpr to fmt.Fprintln with os.Stderr and error args
- Look for ast.CallExpr to fmt.Println in CLI files (exclude test files)
Report diagnostics:

pass.Reportf(node.Pos(), "add context to error return using fmt.Errorf(\"failed to X: %%w\", err)")

Register analyzer:
Add to pkg/linters/linters.go:

import "github.com/github/gh-aw/pkg/linters/errormessage"

func Analyzers() []*analysis.Analyzer {
    return []*analysis.Analyzer{
        // ... existing analyzers
        errormessage.Analyzer,
    }
}

Testing

Create analyzer_test.go with test cases:

func TestBareReturnErr(t *testing.T) {
    testdata := analysistest.TestData()
    analysistest.Run(t, testdata, errormessage.Analyzer, "a")
}

Create testdata files:

testdata/src/a/bare_return.go — Test bare return err detection
testdata/src/a/unformatted_error.go — Test unformatted stderr errors
testdata/src/a/stdout_diagnostic.go — Test stdout diagnostic detection

Validation

After implementation:

Run go test ./pkg/linters/errormessage/ — verify all tests pass
Run make lint — linter should integrate cleanly
Fix any issues in codebase that linter detects
Verify linter documentation in pkg/linters/README.md

References

Existing linters: pkg/linters/workflowcall/, pkg/linters/testbuildtag/
Error message skill: .github/skills/error-messages/SKILL.md
Console formatting: pkg/console/console.go
AGENTS.md "Console Message Formatting" and "Logging Guidelines"

Create a single PR with the new linter, tests, and integration.


---

## 📊 Historical Context

<details>
<summary>Previous Focus Areas</summary>

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|  
| 2026-05-20 | Large File Refactoring & Maintainability | Custom | Y | 5 tasks generated targeting files >800 LOC, validation guideline violations |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. **Fix CLI error formatting** (Task 1) — Priority: High — Quick wins across 37 command files
2. **Fix output stream violations** (Task 2) — Priority: High — Restores Unix conventions, enables pipeable workflows

### Short-term Actions (This Month)  
1. **Improve validation error messages** (Task 3) — Priority: Medium — Focus on top 10 most frequent errors
2. **Add error context** (Task 4) — Priority: Medium — Prevents context loss in error chains

### Long-term Actions (This Quarter)
1. **Create error message linter** (Task 5) — Priority: Low — Prevents regression, enforces guidelines automatically

---

## 📈 Success Metrics

- **Console-formatted errors**: 70 → 1,800+ (match `fmt.Errorf` volume)
- **Stdout diagnostic violations**: 64 → 0 (all diagnostics to stderr)
- **Error wrapping rate**: 65.2% → 85%+ (add context to bare returns)
- **Validation errors with examples**: 0% baseline → 50%+ (top errors have YAML examples)
- **Linter coverage**: 0 checks → 3 automated checks (bare return, unformatted, stdout)

---

## Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items  
4. Re-evaluate this focus area in 30 days (after Tasks 1-4 complete)

---

*Generated by Repository Quality Improvement Agent*
*Next analysis: 2026-05-22 — Focus area selected by diversity algorithm*




> Generated by [⚡ Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/26230112734) · ● 1.1M · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Frepository-quality-improver%22&type=discussions)
> - [x] expires <!-- gh-aw-expires: 2026-05-22T13:58:43.446Z --> on May 22, 2026, 1:58 PM UTC

<!-- gh-aw-agentic-workflow: Repository Quality Improvement Agent, engine: copilot, version: 1.0.48, model: claude-sonnet-4.5, id: 26230112734, workflow_id: repository-quality-improver, run: https://github.com/github/gh-aw/actions/runs/26230112734 -->

<!-- gh-aw-workflow-id: repository-quality-improver -->
<!-- gh-aw-workflow-call-id: github/gh-aw/repository-quality-improver -->

2026-05-22T14:53:55Z

github-actions[bot]
Bot May 22, 2026
Author

This discussion was automatically closed because it expired on 2026-05-22T13:58:43.446Z.

Closed by Workflow

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[repository-quality] 🎯 Repository Quality Improvement Report - Error Message Quality & User Experience #33768

Uh oh!

{{title}}

Uh oh!

Focus Area: Error Message Quality & User Experience

Current State Assessment

Findings

Strengths

Areas for Improvement

Detailed Analysis

1. Console Formatting Adoption Gap

2. Output Stream Violations

3. Error Context Loss

4. Error Message Quality Examples

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

[repository-quality] 🎯 Repository Quality Improvement Report - Error Message Quality & User Experience #33768

Uh oh!

github-actions[bot] Bot May 21, 2026

Executive Summary

Focus Area: Error Message Quality & User Experience

Current State Assessment

Findings

Strengths

Areas for Improvement

Detailed Analysis

1. Console Formatting Adoption Gap

2. Output Stream Violations

3. Error Context Loss

4. Error Message Quality Examples

🤖 Tasks for Copilot Agent

Improvement Tasks

Task 1: Audit and Fix CLI Error Formatting

Guidelines

Validation

Example Fix

Guidelines

Validation

Example Fix

Validation

Notes

Guidelines

Validation

Example Fix

Testing

Validation

References

Replies: 1 comment

Uh oh!

github-actions[bot] Bot May 22, 2026 Author

github-actions[bot]
Bot May 21, 2026

github-actions[bot]
Bot May 22, 2026
Author