[repository-quality] Repository Quality: Error-Handling Contract Consistency

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Error Handling Contract Consistency

Analysis Date: 2026-10-05
Focus Area: Error-handling contract consistency (wrapping, sentinels, string matching, actionable messages)
Strategy Type: Custom
Custom Area: Yes — the repo has many custom error linters (errorfwrapv, errstringmatch, errormessage, fmterrorfnoverbs), so the question is where the conventions still leak.

Executive Summary

Error handling is largely disciplined: about 1,900 of roughly 3,180 fmt.Errorf calls in non-test code wrap with %w. No production %v-with-error formatting was found. No trailing punctuation was found either. Only 29 messages start with a capital letter, and the ones sampled were mostly acronyms such as GitHub, URL and API.

The gaps are structural. There are zero exported sentinel errors (Err... = errors.New) across about 750 errors.New calls, even though errors.Is/As is used 172 times. Callers therefore have no stable values to match on. pkg/cli/update_extension_check.go:439 still matches on err.Error() text. Some static messages (mcp_add.go:253,261, secrets.go:40) state a failure without saying what to do.

Full Analysis Report

Focus Area: Error-handling contract consistency

Current State Assessment

Metric	Value	Status
fmt.Errorf (non-test)	3177	i️
%w wrapping	1901 (~60%)	✅
errors.New (non-test)	747	i️
Exported sentinel errors	0	❌
errors.Is/As uses	172	✅
strings.Contains(err.Error(), ...) in production	1 (update_extension_check.go:439)	⚠️
Capitalized messages	29 (mostly acronyms)	✅
Production %v with err	0	✅

Findings

Strengths

• Linters for wrapping, string matching, and message quality already exist.
• No production code formats an error with %v.

Areas for Improvement

• ❌ No sentinel errors. Callers of the 747 errors.New sites cannot match on stable values.
• ⚠️ String matching on error text in update_extension_check.go.
• ⚠️ Terse messages without remediation in pkg/cli/mcp_add.go:253,261 and pkg/cli/secrets.go:40.
• ⚠️ A few capitalized, non-acronym messages (frontmatter_content.go:231, which starts with a function name; model_aliases.go:57).
• i️ ~40% of fmt.Errorf calls don't wrap. Many are legitimate leaf errors, but they were not audited.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Replace error-text matching with typed/sentinel checks

Priority: High
Estimated Effort: Small
Focus Area: Error handling

Description: update_extension_check.go uses strings.Contains(err.Error(), msg). Replace it with errors.Is/errors.As, or with a sentinel error.

Acceptance Criteria:

• No strings.Contains(err.Error() remains in the production code of pkg/cli
• Existing tests pass; a test covers the new check

Code Region: pkg/cli/update_extension_check.go

Refactor the err.Error() substring check near line 439 of pkg/cli/update_extension_check.go to use errors.Is/As with a sentinel or typed error returned by the producer. Add or update tests. Run make fmt and the unit tests.

---

Task 2: Introduce sentinel errors for common failure classes

Priority: Medium
Estimated Effort: Medium
Focus Area: Error handling

Description: Find repeated errors.New messages (not-found, unsupported, auth, rate limit) and promote them to exported sentinels. Wrap them with %w so callers can use errors.Is.

Acceptance Criteria:

• At least 5 sentinels are introduced in the packages with the most duplicated messages
• Callers are updated to use errors.Is where they previously compared strings
• Tests are added

Code Region: pkg/cli, pkg/workflow, pkg/parser

Run a duplicate-message analysis of errors.New and fmt.Errorf literals in pkg/. Introduce Err* sentinels for the top repeated failure classes. Wrap them with %w, and update the callers and tests.

---

Task 3: Make terse errors actionable

Priority: Medium
Estimated Effort: Small
Focus Area: Usability

Description: Add expected/required/example details to the terse messages in pkg/cli/mcp_add.go (lines 253 and 261) and pkg/cli/secrets.go:40. Fix the capitalization of frontmatter_content.go:231 and model_aliases.go:57.

Acceptance Criteria:

• Each message says what to do next
• Message-asserting tests are updated

Code Region: pkg/cli/mcp_add.go, pkg/cli/secrets.go, pkg/parser/frontmatter_content.go, pkg/workflow/model_aliases.go

Rewrite the listed error messages to follow the repo's error-messages skill: state the problem, the expected value, and an example. Update tests.

---

Task 4: Audit unwrapped fmt.Errorf calls that take an error argument

Priority: Low
Estimated Effort: Medium
Focus Area: Code quality

Description: About 40% of fmt.Errorf calls don't use %w. Identify those that pass an error through another verb or drop it. A prior grep found none using %v, so check %s and .Error() concatenation. Then wrap them.

Acceptance Criteria:

• A report of the findings is produced
• The cases that drop an error are fixed
• The existing errorfwrapv linter is extended if needed to catch %s/.Error() usage

Code Region: pkg/, pkg/linters/errorfwrapv

Search for fmt.Errorf calls that format an error with %s or err.Error(). Convert them to %w. If the errorfwrapv linter does not cover these forms, extend it with testdata.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-10-05	Error-handling contract consistency	Custom	Y	No sentinel errors; 1 string match

---

🎯 Recommendations

Immediate Actions (This Week)

1. Remove error-text matching — Priority: High

Short-term Actions (This Month)

1. Introduce sentinels and make terse messages actionable — Priority: Medium

Long-term Actions (This Quarter)

1. Audit unwrapped errors — Priority: Low

---

📈 Success Metrics

• Sentinel errors: 0 → 5+
• Error-text 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 on improvement items
4. Re-evaluate this focus area in 1 month

---

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

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 19.5 AIC · ⌖ 6.15 AIC · ⊞ 9.7K · ◷

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

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #66149.