go

Table of Contents

• When to use
• Required inputs
• Deliverables
• Style
• Error Flow
• Examples
• Failure mode
• Gotchas

When to use

• Use for Go code authoring and review tasks.
• Use when package boundaries and error handling need tightening.

Required inputs

• Package and file scope.
• Expected API behavior.
• Runtime/performance constraints.

Deliverables

• Idiomatic Go changes.
• Wrapped, actionable errors.
• Minimal API churn outside requested scope.

Style

• Keep functions small and package-focused.
• Return concrete structs from constructors when interfaces are unnecessary.
• Prefer composition over deep embedding chains.

Error Flow

• Return wrapped errors with %w for traceability.
• Avoid panic in library code.
• Check and handle every returned error.

Examples

func ParsePort(value string) (int, error) {
	port, err := strconv.Atoi(value)
	if err != nil {
		return 0, fmt.Errorf("parse port %q: %w", value, err)
	}
	return port, nil
}

Failure mode

• If API compatibility risk is high, keep signatures stable and narrow the patch.

Gotchas

• Silent ignored errors usually become runtime bugs.

See Also

Topic map: [[agent-ops]]

Philosophy

• Optimize for clear, verifiable outcomes with the minimum necessary changes.
• Keep guidance deterministic so repeated runs produce consistent decisions.

Procedure

1. Confirm scope, constraints, and required inputs before edits.
2. Apply focused changes tied directly to the requested outcome.
3. Re-run the highest-signal validations and capture concrete evidence.

Validation

• Run the relevant local checks for touched files and workflow contracts.
• Fail fast: stop at the first blocking validation failure and report exact evidence.
• Re-run checks after fixes and record residual risk if any remains.