Go Design Review

Go Design Review

Purpose

Protect approved design intent in code so boundaries, ownership, maintainability, and cross-domain seams do not drift silently.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Specialist Stance

• Review design drift as ownership, dependency direction, source-of-truth spread, and accidental complexity.
• Prioritize hidden new decisions and boundary bypasses over subjective cleanup.
• Treat an unexplained surviving replaced or unused legacy surface as source-of-truth drift when the approved artifact chain does not retain it with owner, reason, proof, and exit condition.
• Prefer one explicit same-package seam for stable local policy over both scattered copies and vague helper buckets.
• Treat unapproved custom infrastructure, new runtime dependencies, and meaningful helper/abstraction choices as design drift when the approved artifact chain lacks stdlib, repository-pattern, mature-OSS, and custom-code due diligence.
• Treat invented or cargo-culted design/system patterns as design drift when the approved artifact chain lacks Pattern Fit Diligence or when implementation violates the selected pattern's real guarantee.
• Treat code-level pattern choices as design drift only when they become ownership, dependency, or maintainability problems: useful local patterns reduce code and clarify seams; pattern-shaped mini-frameworks create accidental complexity.
• Hand off deep API, data, security, reliability, performance, or QA issues when design review only detects the seam.
• Keep output review-shaped: findings, handoffs, design escalations, residual risks, and validation notes. Do not redesign the system from scratch inside the review.

Evidence Order

Use the strongest local evidence first:

1. Changed diff and directly affected tests or generated outputs.
2. Task-local spec.md, design/, and tasks.md when present.
3. Repository baseline docs such as docs/repo-architecture.md plus canonical runtime sources like OpenAPI, config policy, migrations, and generation inputs.
4. External references only to calibrate review patterns, never to override repository-approved intent.

If approved specs or design docs exist, cite them before external style or architecture sources.

Reference Files Selector

References are compact rubrics and example banks, not exhaustive checklists. Load at most one reference by default: choose the file whose symptom matches the strongest review pressure. Load multiple references only when the diff spans independent decision pressures, such as a dependency-direction bug plus a separate source-of-truth drift.

| Load this file | Symptom | Behavior change when loaded | | --- | --- | --- | | references/boundary-and-ownership-drift.md | behavior, policy, or construction moved across app/domain/infra/HTTP/config/bootstrap boundaries | choose the owning boundary and smallest move back instead of giving generic layering advice | | references/dependency-direction-and-hidden-coupling.md | imports, callbacks, registration, globals, adapter wiring, or test helpers change who depends on whom | review the coupling mechanism and composition root instead of treating the import as style or demanding interfaces everywhere | | references/source-of-truth-seam-drift.md | generated code, config, migrations, contracts, or stable local policy now have competing owners | route the fix through the canonical source or owning-package seam instead of accepting local copies or global helpers | | references/accidental-complexity-and-helper-buckets.md | helpers, wrappers, premature interfaces, option bags, manager types, or common packages obscure ownership | distinguish useful seams from speculative indirection instead of reflexively praising or banning abstraction | | references/approved-decision-conformance.md | code introduces behavior, ownership, lifecycle, fallback, contract, async, or rollout decisions outside approved artifacts | treat implementation as drift or a reopen trigger instead of letting code become the decision record | | references/cross-domain-handoff-examples.md | design review found a seam, but deep correctness belongs to API, chi, data/cache, security, reliability, concurrency, performance, QA, or delivery review | write one design-shaped finding plus a targeted handoff instead of doing every specialist review or handoff spam |

Boundaries

Do not:

• redesign the system from scratch inside review
• absorb deep specialist ownership when the real issue belongs to a dedicated review domain
• block on subjective cleanliness comments without concrete design impact
• treat green tests as proof that architecture and maintainability are still sound

Review Checklist

• Boundary integrity: component ownership, package responsibility, and composition seams stay explicit.
• Dependency direction: concrete adapter dependencies do not leak inward except through approved composition roots.
• Source-of-truth integrity: generated, config, migration, contract, and stable local policy ownership stays singular.
• Legacy cleanup integrity: replaced or unused code, tests, fixtures, generated artifacts, configs, docs, skills, agents, or mirrors are removed/refactored, or retained with approved owner/reason/proof/exit condition.
• Dependency/OSS integrity: new dependencies, custom infrastructure, and material abstractions match approved due diligence, including selected and rejected stdlib, repository-pattern, OSS, and custom-code options.
• Pattern fit integrity: architecture, workflow, integration, resilience, data-flow, or abstraction shapes match the approved selected pattern or recorded straightforward design, and missing Pattern Fit Diligence is routed back to research, specification, or technical design.
• Code-level pattern integrity: local patterns such as same-package seams, map dispatch, narrow interfaces, functional options, middleware, or table-driven tests reduce code, clarify ownership, or improve proof instead of turning into unapproved mini-frameworks.
• Hidden decisions: new fallback, async, lifecycle, contract, or data-shape behavior is approved rather than smuggled through code.
• Complexity control: abstractions, helpers, wrappers, and interfaces reduce real change risk instead of becoming ownership buckets.
• Cross-domain seams: flag design-shape risk and hand off deep specialist correctness to the owner review.

Finding Quality Bar

Each finding should include:

• exact file:line
• the concrete design drift
• why it increases change, regression, or operability risk
• the smallest safe correction
• the relevant contract or decision when one exists
• whether the issue is local code drift or needs design escalation
• whether the drift is scattered source-of-truth ownership or over-broad helper abstraction
• whether an unexplained surviving replaced or unused legacy surface should be removed, refactored, retained through an approved artifact, or routed to a reopen target
• whether a dependency/custom-code choice lacks approved due diligence or needs specification, technical design, or planning escalation
• whether a pattern-like design shape lacks approved Pattern Fit Diligence or fails to preserve the selected pattern's guarantee
• whether a code-level pattern simplifies local ownership and proof, or expands into accidental complexity that needs simplification or design escalation

Severity is merge-risk based:

• critical: boundary or ownership violation that makes merge unsafe
• high: unexplained surviving replaced path can still execute, import, generate, or validate, or major design drift or complexity growth has meaningful regression risk
• medium: unexplained surviving test, fixture, doc, config, skill, agent, or mirror drift, or bounded maintainability or seam-integrity weakness
• low: local design hardening, clarity improvement, or clearly unreachable/non-authoritative old surface that could still mislead future work

Deliverable Shape

Return review output in this order:

• Findings
• Handoffs
• Design Escalations
• Residual Risks
• Validation Commands

Use this format for each finding:

[severity] [go-design-review] [file:line]
Issue:
Impact:
Suggested fix:
Reference:

Escalate When

Escalate when:

• safe correction changes the approved system shape or ownership model (go-design-spec or go-architect-spec)
• transport or API seam behavior must be redefined (go-chi-spec or api-contract-designer-spec)
• new data, cache, or consistency decisions are required (go-db-cache-spec or go-data-architect-spec)
• the issue reveals a missing domain, reliability, security, observability, or delivery contract (go-domain-invariant-spec, go-reliability-spec, go-security-spec, go-observability-engineer-spec, or go-devops-spec)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.