[repository-quality] Repository Quality Improvement Report - Error Message Quality and Context

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Error Message Quality and Context

Analysis Date: 2026-10-15
Focus Area: Error Message Quality and Context
Strategy Type: Custom
Custom Area: Yes - 4,400+ error constructions and custom linters (errorfwrapv, errstringmatch) make error consistency a repo-specific concern.

Executive Summary

Error handling is generally healthy: 2,036 of 3,477 fmt.Errorf calls wrap with %w, %v-with-error misuse exists only in linter testdata, and errors.Is/As is used (206 sites). User-facing validation errors usually include hints and examples (e.g. pkg/cli/spec.go).

Main gaps: ~1,461 bare return err in pkg/cli and pkg/workflow lose context (hot spots: workflow/safe_outputs_max_validation.go 60, cli/work_command.go 43, workflow/compiler_orchestrator_workflow.go 29, cli/mcp_schema.go 29); 34 capitalized Errorf messages; 69 short bare errors.New strings; no package-level sentinel errors; one remaining strings.Contains(err.Error()).

Full Analysis Report

Current State Assessment

Metrics Collected:

Metric	Value	Status
fmt.Errorf (non-test)	3,477	i️
Wrapped with %w	2,036	✅
errors.New (non-test)	963	i️
%v with err (non-testdata)	0	✅
Bare return err (cli+workflow)	1,461	⚠️
Capitalized Errorf messages	34	⚠️
Short bare errors.New	69	⚠️
Package-level Err* sentinels	0	⚠️
err.Error() string matches	1 (cli/update_extension_check.go:439)	⚠️
Unknown engine without options	workflow/agentic_engine.go:674	⚠️

Findings

Strengths

• Linters enforce %w and discourage string matching.
• Most validation errors include expected values and examples.

Areas for Improvement

• Medium: bare returns in high-volume files lose call-site context.
• Low: capitalized messages (some are proper nouns, so audit rather than blanket change).
• Medium: unknown engine: %s does not list valid engines.
• Low: one remaining err-string match.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Add context to bare error returns in hot-spot files

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

Description: Wrap bare return err in the four highest-count files where the callee does not already add context.

Acceptance Criteria:

• Bare returns in the 4 files reviewed and wrapped where context is missing
• No double-prefixing; existing tests pass

Code Region: pkg/workflow/safe_outputs_max_validation.go, pkg/cli/work_command.go, pkg/workflow/compiler_orchestrator_workflow.go, pkg/cli/mcp_schema.go

Review each bare return err in the listed files. Where the callee gives no hint of the operation, wrap with fmt.Errorf with a verb-object prefix and %w. Skip cases where context already exists. Run make fmt and make test-unit.

---

Task 2: Improve unknown-engine error with valid options

Priority: Medium
Estimated Effort: Small
Focus Area: Usability

Description: unknown engine: %s should list supported engines.

Acceptance Criteria:

• Error lists valid engine IDs
• Unit test asserts the message

Code Region: pkg/workflow/agentic_engine.go:674

Update the unknown-engine error to include sorted valid engine IDs (follow the error-messages skill). Add a unit test.

---

Task 3: Audit capitalized error messages

Priority: Low
Estimated Effort: Small
Focus Area: Code Quality

Description: 34 fmt.Errorf messages start with a capital letter; lowercase those that are not proper nouns or acronyms.

Acceptance Criteria:

• Non-proper-noun messages lowercased; tests updated

Code Region: pkg/**/*.go (grep for Errorf with a leading capital)

List capitalized Errorf messages, lowercase where appropriate, update tests asserting the strings, run make fmt.

---

Task 4: Introduce sentinel errors for branching on errors

Priority: Medium
Estimated Effort: Medium
Focus Area: Code Organization

Description: Replace the string match in update_extension_check.go:439 with sentinels and errors.Is; define sentinels for repeated bare errors callers branch on (e.g. no releases found).

Acceptance Criteria:

• Sentinels defined where callers branch
• No strings.Contains(err.Error(), ...) in update_extension_check.go

Code Region: pkg/cli/update_extension_check.go, pkg/cli/update_workflows.go, pkg/cli/run_push.go

Identify errors checked by message text and replace them with package sentinels and errors.Is. Keep messages unchanged.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-10-13	Large Source File Decomposition	Custom	Y	Split 800+ LOC files
2026-10-14	Library Robustness	Custom	Y	Panics/context.Background audit
2026-10-15	Error Message Quality and Context	Custom	Y	Bare returns, hints, sentinels

---

🎯 Recommendations

Immediate Actions (This Week)

1. Wrap bare returns in hot-spot files — Priority: High

Short-term Actions (This Month)

1. Improve unknown-engine error; introduce sentinels — Priority: Medium

Long-term Actions (This Quarter)

1. Consider a linter for bare returns in user-facing paths — Priority: Low

---

📈 Success Metrics

• Bare returns in hot spots: 161 → <60
• Err-string matches: 1 → 0

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress
4. Re-evaluate in 1 month

---

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

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 24.4 AIC · ⌖ 0.666 AIC · ⊞ 9.9K · ◷

• expires on Oct 16, 2026, 5:04 AM UTC-08:00