[sergo] Sergo Report: Error Handling & Context Propagation - 2026-05-04

[github-actions[bot]]

🔬 Sergo Report: Error Handling & Context Propagation

Date: 2026-05-04
Strategy: error-handling-and-context-propagation
Success Score: 7/10
Run ID: §25301644786

---

Executive Summary

This is the inaugural Sergo run on the gh-aw Go codebase (766 non-test Go files, ~180K LOC). With no prior strategy cache to draw from, the analysis focused on two foundational code quality dimensions: error handling patterns and code structure.

The codebase is overall well-structured with clear interface segregation (pkg/workflow/agentic_engine.go), good error wrapping hygiene in most code paths, and intentional crash-fast strategies for embedded data initialization. The three most actionable findings are: (1) missing context.Context propagation through GitHub API call chains, (2) an explicitly developer-flagged architectural TODO for safe outputs decoupling, and (3) growing per-engine domain function sprawl.

---

🛠️ Serena Tools Update

Tools Snapshot

• Total Tools Available: 23
• New Tools Since Last Run: N/A (first run)
• Removed Tools: N/A
• Modified Tools: N/A

Tool Capabilities Used Today

Tool	Purpose
activate_project	Initialize Serena LSP for the workspace
get_symbols_overview	Understand structure of largest files
search_for_pattern	Find error handling anti-patterns across pkg/
find_symbol	Locate specific function definitions

---

📊 Strategy Selection

Cached Reuse Component (50%)

No prior cache — this is the first run. For the "cached" slot, the most universally high-value Go analysis pattern was selected: error handling and context propagation. This is the #1 category of code quality issues in mature Go codebases.

• Why chosen: Error handling and context propagation are foundational to production reliability in Go. Both are systematic (easy to scan programmatically) and impactful (silently discarded errors or missing timeouts can cause real production issues).
• Target areas: All pkg/ production Go files (excluding _test.go)

New Exploration Component (50%)

Novel Approach: Large-file structural complexity analysis using get_symbols_overview

• Hypothesis: Files >900 LOC are likely to contain complex orchestration logic that benefits from better documentation or decomposition
• Tools Employed: get_symbols_overview on the 5 largest files
• Target Areas: pkg/workflow/ — the core compilation package

Combined Strategy Rationale

The error-handling scan (breadth-first, all files) + large-file structural analysis (depth-first, top 5 files) provides complementary coverage: systematic pattern detection paired with deep architectural understanding of the most complex code.

---

🔍 Analysis Execution

Codebase Context

• Total Go Files (non-test): 766
• Total LOC: ~180,380
• Key Packages: pkg/workflow/ (compiler), pkg/cli/ (CLI), pkg/parser/ (YAML parsing), pkg/actionpins/
• Notable Dependencies: rhysd/actionlint, securego/gosec/v2, modelcontextprotocol/go-sdk, anthropics/anthropic-sdk-go

Findings Summary

• Total Issues Found: 6
• Critical: 0
• High: 0
• Medium: 2
• Low: 4

---

📋 Detailed Findings

Medium Priority

Finding M1: context.Background() used directly in GitHub API call chains

Production code in pkg/workflow/ and pkg/cli/ passes context.Background() directly to functions that make GitHub API network calls, bypassing any parent context timeout or cancellation:

• pkg/workflow/action_reference.go:78,116 — resolver.ResolveSHA(context.Background(), ...)
• pkg/workflow/action_sha_checker.go:122 — same pattern
• pkg/workflow/maintenance_workflow.go:68 — same pattern
• pkg/workflow/github_cli.go:131,153 — RunGHContext(context.Background(), ...)
• pkg/cli/add_command.go:366 — fetchAllRemoteDependencies(context.Background(), ...)

Total production instances: 24 across pkg/. These network calls can hang indefinitely if GitHub's API is unresponsive, and cannot be cancelled by parent CLI signal handlers.

Finding M2: Safe outputs event trigger coupling — developer-flagged TODO

At pkg/workflow/compiler_safe_outputs_steps.go:67-73, a developer explicitly marked an architectural concern:

// TODO: `@dsyme` says: We must remove this. The important longer term thing is
// that safe outputs need to be independent of event trigger context...

The safe outputs application step reconstructs target branch information from GitHub Actions event expressions (github.base_ref || github.event.pull_request.base.ref || ...). This causes a known bug: issue_comment events on PRs targeting non-default branches checkout the wrong base branch.

Low Priority

View Low Priority Findings

Finding L1: Per-engine domain function sprawl in domains.go
pkg/workflow/domains.go (1113 lines) exports 16+ per-engine domain functions, many of which are one-line wrappers around GetAllowedDomainsForEngineWithModel. Adding a new AI engine requires adding 2+ mechanical boilerplate functions. The generic API already exists; the wrappers add surface area without value.

Finding L2: Silent error discards in compile_pipeline.go
pkg/cli/compile_pipeline.go:402-403 discards filepath.Glob() errors. Since the patterns are compile-time constants (*.lock.yml, *.invalid.yml), these errors are practically impossible but worth a brief comment.

Finding L3: Error chain breaking is a design choice (documented)
The codebase uses errors.New() (370+ instances) rather than fmt.Errorf("%w") in many places. Based on comments in pkg/workflow/error_wrapping_test.go, this appears intentional — preventing internal error types from leaking to users. No action required.

Finding L4: Panic usage is intentional
All panic() calls in production code are in init() functions loading embedded JSON or binary data. This is a correct crash-fast strategy for detecting compile/packaging errors. No action required.

---

✅ Improvement Tasks Generated

Task 1: Propagate context.Context in action SHA resolution (Medium, Priority: 1)

Issue Type: Context Propagation Anti-Pattern

Problem: resolver.ResolveSHA() and related network operations are called with context.Background() throughout the action resolution code paths. These GitHub API calls have no timeout or cancellation support.

Locations:

• pkg/workflow/action_reference.go:78,116
• pkg/workflow/action_sha_checker.go:122
• pkg/workflow/maintenance_workflow.go:68
• pkg/workflow/github_cli.go:131,153
• pkg/cli/add_command.go:366

Recommendation: Thread ctx context.Context through the call chains leading to these network operations. Verify existing context.WithTimeout(context.Background(), ...) patterns are also updated to use the parent context instead.

Estimated Effort: Medium

---

Task 2: Decouple safe outputs from event trigger context (Medium, Priority: 2)

Issue Type: Architectural Debt (Developer-Flagged TODO)

Problem: pkg/workflow/compiler_safe_outputs_steps.go:67-73 reconstructs target branch from event context rather than having it encoded in the safe output payload, causing a known bug for issue_comment events on non-default-branch PRs.

Recommendation: Enrich the safe output metadata at generation time with target_branch and target_repo, eliminating the event-context fallback expression chain at application time.

Estimated Effort: Large

---

Task 3: Reduce per-engine boilerplate in domains.go (Low, Priority: 3)

Issue Type: Code Duplication / API Sprawl

Problem: pkg/workflow/domains.go has 16+ thin per-engine wrapper functions. Each new engine addition requires mechanical boilerplate; the underlying generic API already handles all cases.

Recommendation: Remove per-engine GetXxxAllowedDomainsWithToolsAndRuntimes wrappers and have callers use GetAllowedDomainsForEngineWithModel directly. Consolidate GetXxxDefaultDomains into a single GetDefaultDomainsForEngine(engine, model) function.

Estimated Effort: Small

---

📈 Success Metrics

This Run

• Findings Generated: 6
• Tasks Created: 3
• Files Analyzed: ~50 (overview on 5 largest + pattern search across all 766)
• Issues Created: 3
• Success Score: 7/10

Score Reasoning

• Findings Quality (3/4): Two medium findings are concrete and actionable; M2 is developer-validated. Deducted 1 for no critical/high severity findings.
• Coverage (2/3): Broad pattern search across all files + deep structural analysis of 5 largest. Deducted 1 as first-run baseline limits cross-run comparison.
• Task Generation (2/3): Generated 3 well-specified tasks but L1-L4 findings are relatively minor. Deducted 1 as none are critical.

Cumulative Statistics (First Run)

• Total Runs: 1
• Total Findings: 6
• Total Tasks Generated: 3
• Average Success Score: 7.0/10
• Most Successful Strategy: error-handling-and-context-propagation

---

🎯 Recommendations

Immediate Actions

1. Context propagation (Medium) — Thread context.Context through action SHA resolution call chains. Improves production reliability for GitHub API calls with no functional behavior change.
2. Safe outputs decoupling (Medium, Large effort) — Implement @dsyme's TODO. Fixes a known edge-case bug and improves testability of safe output application.
3. domains.go cleanup (Low, Small effort) — Remove per-engine wrapper functions. Quick win that reduces future engine addition boilerplate by ~2 functions each.

Long-term Improvements

• Consider adding a context.Context parameter audit to CI to prevent new context.Background() from being introduced in production network call paths.
• The agentic_engine.go interface segregation pattern is excellent and should be used as a model for other packages needing capability detection.

---

🔄 Next Run Preview

Suggested Focus Areas

• Type assertion safety: Search for unguarded type assertions x.(Type) (without the comma-ok pattern) that could panic at runtime
• Interface implementation completeness: Verify that BaseEngine properly implements all methods required by CodingAgentEngine and check for any engines that override methods incorrectly
• Concurrency patterns: The codebase uses sourcegraph/conc — analyze goroutine patterns for potential data races

Strategy Evolution

• Next run should use 50% today's strategy (context propagation — drill deeper, count remaining instances after fix) + 50% new: type assertion safety analysis

---

References:

• §25301644786

Generated by Sergo - Serena Go Expert · ● 394.3K · ◷

• expires on May 5, 2026, 5:02 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Sergo - Serena Go Expert.

A newer discussion is available at Discussion #30276.