godoctor

name	godoctor
description	Developer tooling and architectural safety rules for Go. Automatically validates AST integrity, guards against regressions with compiler rollback gates, eliminates blind spots via Selene mutation testing, and enables fast test and coverage analytics with TestQuery SQLite queries. Activate when writing or refactoring Go code, fixing compilation or test failures, auditing test thoroughness with mutation testing, or enforcing idiomatic Go standards.
license	Apache-2.0
metadata	{"category":"coding","tags":"go, golang, testing, refactoring, quality, mutation-testing","author":"Daniela Petruzalek ([e-mail])","version":"0.2.0","catalog":"https://skills.danicat.dev"}

Go Quality & Tooling Guide (GoDoctor)

GoDoctor provides AST-aware Go developer tooling, code quality enforcement, and testing analytics available both as a command-line interface (CLI) and as a Model Context Protocol (MCP) server.

---

1. Go Coding & Architectural Standards

Google Go Style & Idiomatic Practices

• Standard Toolchain Enforcement: All code must be strictly formatted with gofmt, organized with goimports, checked with go vet, and linted with golangci-lint.
• Naming Conventions:
  • Avoid repeating package names in exported types or functions (no stuttering). Use user.Service instead of user.UserService, http.Server instead of http.HttpServer, and config.Load instead of config.LoadConfig.
  • Use camelCase for unexported identifiers and PascalCase for exported identifiers. Acronyms must remain uniform in case (e.g., JSONURL, dbID, xmlHTTP).
• Error Handling:
  • Return errors as the last return value.
  • Wrap errors with contextual information using fmt.Errorf("action description: %w", err).
  • Do not panic in libraries or standard business logic; return explicit errors.

Package Architecture & Layout

• Flat Package Structure: Prefer flat package layouts over deep enterprise layered modeling (such as adapters/, ports/, entities/, controllers/, repositories/, services/, usecases/). Keep code flat in the root or logically grouped by feature/domain.
• Private vs. Public API: Use internal/ for private packages that should not be imported by external modules. Do not create a pkg/ directory unless developing a cloud-native project in the Kubernetes ecosystem.
• Test Fixtures & Golden Files: Store test fixtures, golden files, mock datasets, and external test inputs in testdata/ directories. The Go toolchain ignores testdata/ folders during normal package compilation.
• Avoid Monolithic Files: Split package logic into clear, focused files named after their primary responsibility (e.g., server.go, handler.go, config.go, types.go).
• Prohibition of Generic Catch-All Packages: NEVER create generic util, shared, common, or helpers packages. These act as catch-all dumping grounds that destroy dependency boundaries. Place functionality in specific, domain-named packages or close to its site of use.

API Design & HTTP Architecture

• Interface Segregation: Keep interfaces small and consumer-defined (accept interfaces, return structs). Do not create premature interfaces with single implementations. Expose concrete types from producer packages.
• HTTP Service Design: Follow modern Go HTTP service design patterns:
  • Constructor-based dependency injection (e.g., NewServer(cfg, logger)).
  • Group HTTP routes and handlers on a single server struct.
  • Write explicit HTTP middleware for cross-cutting concerns (logging, authentication, tracing).

---

2. Tool Selection Matrix

Task / Goal	CLI Command (godoctor call)	MCP Tool Name	Behavior / Safeguards
AST-Aware Code Edits	godoctor call edit	smart_edit	Coordinate matching + AST formatting + atomic write + compiler rollback gate (go vet).
Build & Quality Pipeline	godoctor call build	smart_build	Builds Go binaries and packages with integrated compilation, testing, coverage analysis, linting, and quality verification.
Test & Benchmark Runner	godoctor call test	smart_test	Multi-tier runner (fast, basic/standard, benchmark, complete) + auto-indexes into testquery.db.
AST Documentation	godoctor call docs	read_docs	Fetches package docs, exported symbols, types, and function signatures with 3-tier fallback caching.
Mutation Testing	godoctor call selene	selene	Evaluates test suite quality by mutating AST operators and checking for test assertion kills. See references/selene.md.
SQL Test Analytics	godoctor call tq	test_query	Executes SQLite queries against test history and statement coverage in testquery.db. See references/testquery.md.

Test Runner Tiers (smart_test / godoctor call test)

• level: "fast": Sub-second inner loop test execution. Runs package unit tests directly; skips coverage profiling, benchmarks, and mutation analysis. Ideal for rapid iterative development.
• level: "basic" / "standard": Standard testing tier. Runs unit tests with statement coverage profiling and auto-indexes execution metrics into .godoctor/testquery.db.
• level: "benchmark": Runs unit tests, coverage profiling, and Go benchmark suites (go test -bench=.).
• level: "complete": Comprehensive quality gate. Runs unit tests, coverage profiling, benchmarks, and full multi-worker Selene AST mutation testing across all packages. Ideal for pre-commit, CI verification, and release audits.

---

3. Core Principles & Safeguards

• Zero-Fallback Policy: External binaries (golangci-lint, modernize, deadcode, selene, testquery) must be pre-installed in $PATH or defined in .godoctor.yaml. Dynamic go run compilation fallbacks are banned to eliminate 1.5s–4.5s latency delays and ensure reproducible execution.
• Tool Version Tracking: GoDoctor actively verifies installed tool versions against recommended baselines, reporting non-blocking upgrade recommendations and providing godoctor check.
• Absolute Paths Required: All directory (dir) and file (filename) parameters must be absolute paths (e.g. /path/to/project).
• Atomic Edit Transactions & Compiler Gate: edit / smart_edit writes changes to temporary files before atomic replacement, preserving file permissions. Edits are verified via go vet ./... and automatically rolled back if errors are introduced.
• Concurrency & Resource Management: Heavy operations like level: "complete" (Selene AST mutation testing) utilize all CPU cores; avoid spawning concurrent test/build tasks while complete runs are in flight to prevent CPU exhaustion and SQLite WAL contention.
• Configuration-Driven: Subsystems read settings from .godoctor.yaml following a strict 3-tier precedence hierarchy: $$\text{Per-Call Payload (JSON)} \succ \text{Config File } (\texttt{.godoctor.yaml}) \succ \text{Built-in Defaults}$$

---

4. Environment Diagnostics (godoctor check)

Inspect installed external tools, versions, and health status:

# Formatted ASCII diagnostic table
godoctor check

# Machine-readable JSON output
godoctor check --json

---

5. Centralized Configuration (.godoctor.yaml)

Initialize a configuration file in your repository:

godoctor init

Key configuration sections in .godoctor.yaml:

version: "1"

# CLI & Runtime Settings
cli:
  default_output: "text"
  color: true

# Server Execution Settings
server:
  write_timeout: "5m"
  allowed_origins:
    - "http://localhost"
    - "http://localhost:*"
    - "http://127.0.0.1"
    - "http://127.0.0.1:*"

# External Tools & Version Management
tools:
  golangci_lint:
    recommended_version: "v2.12.2"
    pkg: "github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2"
  modernize:
    recommended_version: "latest"
    pkg: "golang.org/x/tools/go/analysis/passes/modernize/cmd/modernize@latest"
  deadcode:
    recommended_version: "latest"
    pkg: "golang.org/x/tools/cmd/deadcode@latest"
  selene:
    recommended_version: "latest"
    pkg: "github.com/danicat/selene/cmd/selene@latest"
    workers: 0 # 0 defaults to runtime.GOMAXPROCS
    testquery_compat: true
  testquery:
    recommended_version: 
     
     



   
   
   
   
   

---

6. Installation & Surface Management

Installing GoDoctor CLI

go install github.com/danicat/godoctor/cmd/godoctor@latest

Managing Surfaces (godoctor install & uninstall)

Configure MCP server registration in mcp_config.json and unpack agent skills:

# Configure MCP and skills globally (default: ~/.gemini/config)
godoctor install

# Configure in workspace scope (.agents/)
godoctor install -w

# Modular configuration
godoctor install --mcp        # MCP server registration only
godoctor install --skills     # Skills unpacking only

# Clean removal
godoctor uninstall
godoctor uninstall -w

---

7. Direct CLI Invocation Examples (godoctor call)

1. edit (AST-Verified Coordinate Edits with Atomic Rollback)

godoctor call edit '{"filename": "/absolute/path/to/main.go", "old_content": "fmt.Println(\"old\")", "new_content": "fmt.Println(\"new\")"}'

2. build (Build, Test, and Lint Pipeline)

# Standard workspace build and test
godoctor call build '{"dir": "/absolute/path/to/project"}'

# Build with specific output binary target
godoctor call build '{"dir": "/absolute/path/to/project", "packages": "./cmd/godoctor", "output": "bin/godoctor"}'

3. test (Multi-Tier Test Runner)

# Available levels: fast, basic, benchmark, complete
godoctor call test '{"dir": "/absolute/path/to/project", "level": "basic"}'

4. docs (AST Symbol & Type Documentation)

godoctor call docs '{"import_path": "net/http", "symbol_name": "Client"}'

5. selene (Mutation Testing)

godoctor call selene '{"dir": "/absolute/path/to/project"}'

6. tq (SQL Test & Coverage Analytics)

godoctor call tq '{"dir": "/absolute/path/to/project", "query": "SELECT package, test, elapsed FROM all_tests WHERE action = '\''fail'\''"}'

---

8. Detailed References

For specialized workflows, refer to the companion references:

• TestQuery SQL Analytics & Schema: references/testquery.md — Comprehensive database schema (all_tests, all_coverage, test_coverage, all_code), SQLite query recipes, and statement coverage metrics.
• Selene Mutation Testing Guide: references/selene.md — AST mutation operators, mutant statuses (KILLED, SURVIVED, UNCOVERED), targeted mode execution, and surviving mutant remediation strategies.