[repository-quality] 🎯 Repository Quality Improvement Report - CLI Output Consistency (2026-05-08)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - CLI Output Consistency

Analysis Date: 2026-05-08
Focus Area: CLI Output Consistency
Strategy Type: Custom
Custom Area: Yes — The repo has a well-defined console formatting system (pkg/console) with explicit guidelines (AGENTS.md) for routing output. This area measures how well the codebase adheres to those standards.

Executive Summary

The pkg/cli package has 1,502 correct uses of console.Format* helpers, which is encouraging. However, analysis reveals 685 instances of bare fmt.Fprintln(os.Stderr, ...) / fmt.Fprintf(os.Stderr, ...) calls that bypass the console formatting layer — resulting in visually inconsistent output (missing emoji prefixes, colour, and style) for a significant fraction of user-facing messages.

The most notable clusters are: compile_file_operations.go (error printed without FormatErrorMessage), add_interactive_engine.go and add_interactive_workflow.go (debug/status lines without FormatInfoMessage/FormatProgressMessage), and audit_cross_run_render.go (report-body lines mixed with stdout markdown output in the first output render function). Additionally, 20+ high-traffic code paths return bare err without wrapping context, making error chains harder to diagnose.

Closing these gaps will improve UX consistency for all CLI users and make error trails significantly easier to follow during debugging.

Full Analysis Report

Focus Area: CLI Output Consistency

Current State Assessment

Metrics Collected:

Metric	Value	Status
console.Format* calls in pkg/cli	1,502	✅ Strong adoption
Bare stderr writes without console formatting	685	⚠️ Significant gap
fmt.Println/Printf to stdout (non-structured)	14 files	⚠️ Mixed routing
return err without wrapping context	20+ in pkg/cli	⚠️ Needs improvement
TODO/FIXME count	14	✅ Low

Findings

Strengths

• 1,502 console.Format* usages show strong adoption of the formatting system
• add_interactive_engine.go, add_interactive_workflow.go, and compile_file_operations.go all have the console import and correctly apply formatting in many places
• audit_cross_run_render.go has a well-structured dual-output design (markdown tables to stdout, summary stats to stderr)
• Error wrapping with %w is used in the majority of fmt.Errorf calls

Areas for Improvement

1. [High] compile_file_operations.go:74 — fmt.Fprintln(os.Stderr, err.Error()) bypasses FormatErrorMessage; users see a plain string instead of the styled error prefix
2. [High] compile_file_operations.go:174 — "Watching for file changes" uses bare Fprintln instead of FormatProgressMessage
3. [Medium] add_interactive_engine.go:77 — fmt.Fprintf(os.Stderr, "Using coding agent: %s\n", ...) should be FormatInfoMessage
4. [Medium] add_interactive_engine.go:162 / add_interactive_workflow.go:50,56,65 — multiple bare status lines without any console formatting in interactive flows
5. [Medium] add_interactive_workflow.go:135,140,143 — "Updating local branch..." and associated messages are bare, breaking the visual cadence of a formatted success sequence
6. [Low] 20+ return err in pkg/cli (e.g. mcp_secrets.go:55, logs_orchestrator.go:44,203, validate_command.go:42) add no context, making stack traces harder to interpret

Detailed Analysis

compile_file_operations.go is invoked on every compile run and is one of the most user-visible code paths. Line 74 is in the per-file compile loop:

fmt.Fprintln(os.Stderr, err.Error())  // should be FormatErrorMessage

Line 174 starts the watch mode:

fmt.Fprintln(os.Stderr, "Watching for file changes")  // should be FormatProgressMessage or FormatInfoMessage

add_interactive_workflow.go has a noticeable drop in formatting quality in the progress-polling section (lines 50–65) where it uses raw fmt.Fprintf(os.Stderr, ...) for status check messages while surrounding lines use FormatSuccessMessage / FormatWarningMessage.

add_interactive_engine.go:77 is printed directly before a formatted FormatInfoMessage at line 83, producing inconsistent style in the same function.

For error wrapping, logs_orchestrator.go:44 sits at the entry to log downloading and discards the call context entirely with return err.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Apply console formatting to compile_file_operations.go bare output calls

Priority: High
Estimated Effort: Small
Focus Area: CLI Output Consistency

Description: Two bare output calls in pkg/cli/compile_file_operations.go bypass the console formatting system. Fix them to use the appropriate console.Format* helpers so compile-loop errors and watch-mode start messages are visually consistent with the rest of the CLI.

Acceptance Criteria:

• Line 74: fmt.Fprintln(os.Stderr, err.Error()) → fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))
• Line 174: fmt.Fprintln(os.Stderr, "Watching for file changes") → fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Watching for file changes"))
• make build && make fmt passes without errors
• No other bare stderr calls introduced in this file

Code Region: pkg/cli/compile_file_operations.go

In `pkg/cli/compile_file_operations.go`, two output lines bypass the console formatting system:

- Line 74: `fmt.Fprintln(os.Stderr, err.Error())` — should use `console.FormatErrorMessage(err.Error())`
- Line 174: `fmt.Fprintln(os.Stderr, "Watching for file changes")` — should use `console.FormatProgressMessage("Watching for file changes")` or `console.FormatInfoMessage`

Apply the correct `console.Format*` helper to each line. Run `make build && make fmt` and verify the build passes. Do not change any other lines in the file. Create a pull request with these two targeted changes.

---

Task 2: Apply console formatting to bare messages in add_interactive_engine.go

Priority: Medium
Estimated Effort: Small
Focus Area: CLI Output Consistency

Description: pkg/cli/add_interactive_engine.go has several bare fmt.Fprintf/Fprintln(os.Stderr, ...) calls interleaved with properly formatted ones, breaking the visual cadence of the interactive engine-selection flow.

Acceptance Criteria:

• Line 77: fmt.Fprintf(os.Stderr, "Using coding agent: %s\n", c.EngineOverride) → fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Using coding agent: "+c.EngineOverride))
• Line 162: bare string message about secrets → wrapped in FormatInfoMessage
• All bare fmt.Fprintln(os.Stderr, "") blank-line separators can remain as-is (they are intentional spacing, not messages)
• make build && make fmt passes

Code Region: pkg/cli/add_interactive_engine.go

In `pkg/cli/add_interactive_engine.go`, the following lines use bare output instead of console formatting helpers:

- Line 77: `fmt.Fprintf(os.Stderr, "Using coding agent: %s\n", c.EngineOverride)` — convert to `fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Using coding agent: "+c.EngineOverride))`
- Line 162: `fmt.Fprintln(os.Stderr, "Once you have write access or an admin configures the repository, set the secret with:")` — convert to `fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Once you have write access or an admin configures the repository, set the secret with:"))`

Blank-line separator calls like `fmt.Fprintln(os.Stderr, "")` are intentional spacing and should be left unchanged.

Apply the fixes, run `make build && make fmt`, verify the build passes, and open a pull request with the targeted changes.

---

Task 3: Apply console formatting to bare messages in add_interactive_workflow.go

Priority: Medium
Estimated Effort: Small
Focus Area: CLI Output Consistency

Description: The polling and branch-update sections of pkg/cli/add_interactive_workflow.go use bare fmt.Fprintf(os.Stderr, ...) calls while adjacent lines use console.Format*, creating an inconsistent UX during the gh aw add interactive flow.

Acceptance Criteria:

• Line 50: fmt.Fprintf(os.Stderr, "Checking workflow status (attempt %d/5) for: %s\n", ...) → FormatProgressMessage
• Line 56: fmt.Fprintf(os.Stderr, "Status check error: %v\n", err) → FormatWarningMessage
• Line 60: fmt.Fprintf(os.Stderr, "Found %d workflow(s) matching pattern\n", ...) → FormatInfoMessage
• Line 65: fmt.Fprintln(os.Stderr, "No workflows found matching pattern yet") → FormatInfoMessage
• Lines 135, 143: branch-update messages → FormatProgressMessage or FormatInfoMessage
• make build && make fmt passes

Code Region: pkg/cli/add_interactive_workflow.go

In `pkg/cli/add_interactive_workflow.go`, multiple bare `fmt.Fprintf/Fprintln(os.Stderr, ...)` calls in the polling loop and branch-update section bypass the console formatting system. Adjacent code correctly uses `console.FormatSuccessMessage`, `console.FormatWarningMessage`, and `console.FormatErrorMessage`.

Apply `console.Format*` helpers to:
- Line 50 (`"Checking workflow status..."`) → `FormatProgressMessage`
- Line 56 (`"Status check error: %v"`) → `FormatWarningMessage`
- Line 60 (`"Found %d workflow(s)..."`) → `FormatInfoMessage`
- Line 65 (`"No workflows found matching pattern yet"`) → `FormatInfoMessage`
- Line 135 (`"Updating local branch..."`) → `FormatProgressMessage`
- Line 143 (`"Finished updating local branch."`) → `FormatInfoMessage`

Leave blank-line separators (`fmt.Fprintln(os.Stderr, "")`) unchanged. Run `make build && make fmt`, confirm the build passes, and open a pull request.

---

Task 4: Add error context to bare return err calls in pkg/cli high-traffic paths

Priority: Medium
Estimated Effort: Medium
Focus Area: CLI Output Consistency

Description: Over 20 locations in pkg/cli return err directly without wrapping it in a contextual message. The highest-impact locations are in logs_orchestrator.go, validate_command.go, compile_validation.go, and mcp_secrets.go. Wrapping errors with fmt.Errorf("... context ...: %w", err) dramatically improves debugging and error chains.

Acceptance Criteria:

• logs_orchestrator.go:44 — wrap with fmt.Errorf("failed to initialize logs orchestrator: %w", err) (or appropriate message)
• logs_orchestrator.go:203 — wrap with contextual message indicating which operation failed
• validate_command.go:42,72 — wrap with fmt.Errorf("validation failed: %w", err)
• compile_validation.go:42 — wrap with fmt.Errorf("compile validation failed: %w", err)
• mcp_secrets.go:55 — wrap with contextual message
• No pre-existing tests are broken (make test-unit passes)

Code Region: pkg/cli/logs_orchestrator.go, pkg/cli/validate_command.go, pkg/cli/compile_validation.go, pkg/cli/mcp_secrets.go

In `pkg/cli`, the following locations return `err` without adding context, making error chains opaque:

- `logs_orchestrator.go` lines 44, 203, 639
- `validate_command.go` lines 46, 72
- `compile_validation.go` line 42
- `mcp_secrets.go` line 55

For each location, replace `return err` with `return fmt.Errorf("<short description of what was being attempted>: %w", err)`. Use the immediate function name or calling context as the description (e.g. `"failed to download logs"`, `"validation step failed"`, `"failed to configure MCP secret"`).

After making changes, run `make build && make fmt && make test-unit` and confirm all tests pass. Open a pull request with the targeted changes.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
(no prior runs)	—	—	—	—

---

🎯 Recommendations

Immediate Actions (This Week)

1. Fix compile_file_operations.go bare output calls — Priority: High (every compile run is affected)

Short-term Actions (This Month)

1. Fix add_interactive_engine.go and add_interactive_workflow.go bare messages — Priority: Medium
2. Add error context to bare return err in high-traffic paths — Priority: Medium

Long-term Actions (This Quarter)

1. Run a repo-wide audit of all 685 bare stderr calls and batch-fix remaining ones — Priority: Low
2. Add a lint rule (e.g. a custom staticcheck or golangci-lint check) that flags fmt.Fprintln(os.Stderr, ...) without console.Format* — Priority: Low

---

📈 Success Metrics

• Bare stderr calls without console formatting: 685 → < 100
• return err without context in pkg/cli: 20+ → < 5

---

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 1 month

---

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

References: §25557600244

Generated by Repository Quality Improvement Agent · ● 8.1M · ◷

• expires on May 9, 2026, 1:21 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-09T13:21:10.261Z.

Closed by Workflow