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.

Constraints

• Redact secrets, tokens, credentials, and sensitive data by default.
• Do not expand scope beyond the request unless explicitly asked.
• Prefer safe, reversible edits over broad refactors.

Anti-patterns

• Skipping validation after making changes.
• Applying broad refactors to solve narrow issues.
• Assuming behavior without evidence from current checks.

References and assets

• Open deep guidance: Infrastructure/references/deep-guidance.md
• Read when: the task needs advanced edge cases, migration-safe patterns, or runtime-specific nuance beyond the core checklist.