[sergo] Sergo Report: Symbol-Navigation + Pattern-Grep — 2026-04-29

[github-actions[bot]]

Date: 2026-04-29
Strategy: symbol-navigation-plus-grep
Success Score: 8/10

Executive Summary

This is the inaugural Sergo run on github/gh-aw. Analysis combined Serena's LSP-powered symbol navigation tools with ripgrep pattern searches to perform a broad scan of the utility and workflow packages. The codebase is a large, well-structured Go monorepo (~400+ files in pkg/workflow/ alone) with strong test coverage.

Three actionable findings were identified spanning idiom consistency, error chain integrity, and logging architecture. None are correctness bugs, but two of them (error wrapping and logger bypass) directly affect production debuggability. Three GitHub issues were filed.

---

Serena Tools Snapshot

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

Tool Capabilities Used Today

Tool	Purpose
activate_project	Initialize LSP analysis on the Go workspace
check_onboarding_performed	Verify project state
list_dir	Explore package structure
find_file	Discover .go files by package
get_symbols_overview	Get exported/unexported symbols per file
find_symbol	Read full function bodies
find_referencing_symbols	Trace callers of key functions
search_for_pattern	Regex search for idiom patterns
write_memory	Persist project knowledge for future runs

---

Strategy Selection

New Exploration Component (100% — first run, no cache to draw from)

Since this is the inaugural run, there is no prior strategy history. Both components of the 50/50 split were treated as new exploration. For future runs, today's strategy will serve as the cached baseline.

Strategy Name: symbol-navigation-plus-grep

Approach:

1. Symbol-level survey — Used get_symbols_overview and find_symbol to read bodies of utility functions across pkg/sliceutil, pkg/stringutil, pkg/envutil, pkg/typeutil, pkg/fileutil, and pkg/gitutil. These small packages are high-leverage: they define idioms inherited by the larger packages.
2. Pattern-grep for idiomatic anti-patterns — Used search_for_pattern and Grep to quantify the spread of map[T]bool (set idiom), fmt.Errorf without %w (error wrapping), and fmt.Fprintln(os.Stderr) (logger bypass) across all non-test production code.
3. Reference tracing — Used find_referencing_symbols to understand the blast radius of issues (e.g., confirming Deduplicate is called from 14 production sites across pkg/cli, pkg/parser, pkg/workflow).

Hypothesis: Small utility packages with weak idiomatic choices propagate bad patterns into larger packages that call them.

---

Codebase Context

• Total Go Files in pkg/: Hundreds (pkg/workflow alone has 400+ files)
• Packages Analyzed: sliceutil, stringutil, envutil, typeutil, fileutil, gitutil, parser, workflow (selectively)
• Focus: Utility packages as pattern-setters; validation helpers as impact multipliers

---

Findings Summary

#	Issue	Severity	Files Affected	Count
1	map[T]bool for set semantics instead of map[T]struct{}	Medium	153+	Pattern-wide
2	fmt.Errorf without %w breaks errors.Is/As chains	High	173	580 sites
3	GetIntFromEnv bypasses logger for warning messages	Medium	1	2 sites

---

Detailed Findings

Finding 1 — map[T]bool Used for Set Semantics (Medium)

Location: pkg/sliceutil/sliceutil.go:64, pkg/workflow/validation_helpers.go:212, pkg/stringutil/sanitize.go:22

Pattern: Using map[T]bool to track "seen" items (set membership) is valid but not idiomatic Go. The idiomatic approach is map[T]struct{} because struct{} is a zero-size type — the value slot in the map requires no memory storage. Additionally, the intent ("this is a set") is clearer with struct{}{} as the sentinel value.

Quantified spread:

• make(map[...bool): 153+ non-test files
• map[T]struct{}: 14 non-test files

The ratio (153:14) shows the bool pattern dominates, largely because the utility functions Deduplicate and validateNoDuplicateIDs use it, and callers copy the idiom.

// Current (pkg/sliceutil/sliceutil.go:64)
seen := make(map[T]bool, len(slice))
if !seen[item] { seen[item] = true }

// Idiomatic
seen := make(map[T]struct{}, len(slice))
if _, ok := seen[item]; !ok { seen[item] = struct{}{} }

Finding 2 — fmt.Errorf Missing %w (High)

Location: 173 non-test files, 580 occurrences

High-concentration files:

• pkg/parser/schedule_fuzzy_scatter.go — 31 instances
• pkg/workflow/engine_validation.go — 17 instances
• pkg/workflow/stop_after.go — 16 instances
• pkg/workflow/compiler_pre_activation_job.go — 10 instances
• pkg/workflow/call_workflow_validation.go — 9 instances

When %s (or no verb) is used for an error, the error chain is severed. errors.Is(err, target) and errors.As(err, &target) cannot traverse the chain. This limits sentinel-error-based control flow upstream and makes production debugging harder.

// Breaks chain (580 occurrences)
return fmt.Errorf("call workflow: unsupported trigger %q", trigger)

// Preserves chain (1004 occurrences)
return fmt.Errorf("call workflow: unsupported trigger %q: %w", trigger, err)

Note: errors with no underlying err to wrap are intentionally plain — only cases where an err variable is included as %s (not %w) need migration.

Finding 3 — GetIntFromEnv Bypasses Logger (Medium)

Location: pkg/envutil/envutil.go:38,48

The function signature is:

func GetIntFromEnv(envVar string, defaultValue, minValue, maxValue int, log *logger.Logger) int

The log parameter is used only for the success path. Both warning paths (invalid format, out-of-bounds) use fmt.Fprintln(os.Stderr, ...), bypassing the caller-provided logger. This means callers cannot control the warning output channel, cannot suppress them in tests, and cannot redirect them to structured logging infrastructure.

---

Improvement Tasks Generated

Task 1: Migrate set-semantics maps to map[T]struct{}

Impact: Medium | Effort: Medium
Start with: pkg/sliceutil/sliceutil.go (Deduplicate), pkg/workflow/validation_helpers.go (validateNoDuplicateIDs), pkg/stringutil/sanitize.go (commonWorkflowKeywords)
Then: Sweep remaining make(map[...bool) set usages in production code

Task 2: Add %w to fmt.Errorf calls that include an error

Impact: High | Effort: Medium
Start with: High-count files: schedule_fuzzy_scatter.go, engine_validation.go, stop_after.go
Tool: go vet + golangci-lint errorlint to find and prevent regression
Caveat: Only wrap where an err variable is embedded — don't blindly add %w to format-only errors

Task 3: Route GetIntFromEnv warnings through the logger parameter

Impact: Medium | Effort: Small
File: pkg/envutil/envutil.go (2 warning sites)
Pattern: Use the logger when non-nil, fall back to stderr when nil

---

Success Metrics

This Run

• Findings Generated: 3
• Tasks Created: 3
• Files Analyzed: ~20 directly; pattern data from 173+ files
• Success Score: 8/10

Score Reasoning

• Findings Quality (3.5/4): All 3 findings are real, actionable, and supported by quantified evidence
• Coverage (2.5/3): Good coverage of utility packages; pkg/cli left mostly unexplored
• Task Generation (2/3): 3 clear tasks with scoped starting points

---

Historical Context

This is the first Sergo run. No historical comparison available. Baseline established for future runs.

Cumulative Statistics:

• Total Runs: 1
• Total Findings: 3
• Total Tasks Generated: 3
• Average Success Score: 8.0/10
• Strategy in Use: symbol-navigation-plus-grep

---

Recommendations

Immediate Actions

1. [High] Sweep fmt.Errorf without %w — start with schedule_fuzzy_scatter.go (31 sites), engine_validation.go (17 sites), stop_after.go (16 sites). Consider enabling errorlint in .golangci.yml.
2. [Medium] Fix GetIntFromEnv logger bypass — single-function change, low risk, high observability gain.
3. [Medium] Migrate Deduplicate and validateNoDuplicateIDs to map[T]struct{} — sets a better pattern for the rest of the codebase to follow.

Long-term Improvements

• Add errorlint or wrapcheck to the golangci-lint config to prevent future error-wrapping gaps.
• Consider a linter rule (e.g., custom go vet check) for map[T]bool set usage.
• Future Sergo run focus: pkg/cli/ package — large surface area not yet analyzed for similar patterns.

---

Next Run Preview

Suggested Focus Areas: pkg/cli/ commands (unexplored), pkg/parser/ import cycle detection logic, error aggregation patterns in pkg/workflow/compiler_orchestrator.go

Strategy Evolution: Next run should use symbol-navigation-plus-grep as the 50% cached component, with a new 50% component targeting interface satisfaction and type assertion patterns in pkg/types/ and pkg/workflow/engine_definition.go.

---

References:

• §25132435628

Generated by Sergo — The Serena Go Expert
Run ID: 25132435628 | Strategy: symbol-navigation-plus-grep

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

• expires on Apr 30, 2026, 8:44 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-30T20:44:51.408Z.

Closed by Workflow