review_architecture_skill

Overview

This skill provides a systematic architecture review checklist and automated pattern compliance guidance for Go projects. It codifies layer boundaries, interface and dependency rules, package layout expectations, and observability and error-handling standards. Use it to produce a clear compliance matrix and prioritized remediation guidance.

How this skill works

The skill inspects code and design against a defined layered architecture and a set of Go-specific principles: ISP, DIP, SRP, package layout, configuration, error handling, and observability. It flags upward or circular dependencies, large or misnamed interfaces, concrete dependencies where interfaces are expected, missing package artifacts, and absent metrics/tracing. The output is a structured review document with a compliance matrix, categorized issues, recommendations, and positive highlights.

When to use it

• During PR review for new packages, providers, or major features
• When refactoring to ensure preservation of architectural boundaries
• Before merging changes touching core layers (agents, llms, retrievers, memory, infra)
• Onboarding new contributors to validate idiomatic package structure
• Periodic architecture health checks across the codebase

Best practices

• Enforce strict layer dependencies: higher layers depend only on lower layers, never upward imports
• Keep interfaces small (≤5 methods) and name single-method interfaces with -er suffix
• Prefer constructor injection with interfaces; avoid package-level mutable state and init side-effects
• Give each package a single responsibility and avoid 'utils' god-packages
• Include config.go, metrics.go, errors.go, iface/, and tests for each package and provider
• Instrument public methods with tracing and expose standard Prometheus metrics and error counters

Example use cases

• Review a pull request that adds a new provider implementation under providers/ to ensure registry and config patterns
• Audit a package that recently grew large to detect god objects and split responsibilities
• Validate that a new LLM adapter depends only on the LLM layer and uses interfaces for downstream clients
• Assess observability coverage when adding a public API so metrics and spans are present
• Scan for global state or init() side effects before a release to prevent runtime coupling