// Scout Rule — identify the top 3 highest-impact improvement opportunities in files you're already touching. Analyzes entire file content, not just changed lines. Focuses on pre-existing code quality, not PR bugs. Use when preparing a PR, during code review, or after completing a feature.
Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
Prepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.
Validate commit messages against the Conventional Commits specification. Auto-detects and installs commitlint CLI if missing. Checks project config or falls back to sensible defaults. Use when validating commit messages, preparing PRs, or enforcing commit conventions.
Audit Go nolint directives for staleness and lazy justifications. Mechanically verifies each suppression with golangci-lint, then runs adversarial Red/Blue/White debates on the top candidates for removal. Use when inheriting a Go codebase, during periodic cleanup, or when nolint count is growing unchecked.
Validate markdown files against formatting standards. Auto-detects and installs markdownlint-cli if missing. Checks project config or falls back to sensible defaults. Supports auto-fix mode. Use when creating or modifying markdown files, validating documentation, or enforcing markdown conventions.
Generate a PR_MESSAGE.md file from session context using GitHub CLI. Detects related issues via branch-keyword search, writes a structured PR description with commit subject, summary, test plan, and changelog. Validates with commitlint and markdownlint. Use when preparing a pull request on GitHub.
| name | scout |
| description | Scout Rule — identify the top 3 highest-impact improvement opportunities in files you're already touching. Analyzes entire file content, not just changed lines. Focuses on pre-existing code quality, not PR bugs. Use when preparing a PR, during code review, or after completing a feature. |
| compatibility | Requires git. Works with any project that has a diff to analyze. |
"Leave the code better than you found it."
Identify the top 3 highest-impact, lowest-risk improvement opportunities in files touched by a diff. Reads entire file content, not just changed lines. Focuses on pre-existing code quality — things the next developer will thank you for fixing.
git --version 2>/dev/null && git rev-parse --is-inside-work-tree 2>/dev/null
If git is not installed or the working directory is not a git
repository, stop and report the issue. Do not proceed.
Determine which files to analyze based on input.
# Detect base branch
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
| sed 's@^refs/remotes/origin/@@' || echo "main")
# Combine committed + uncommitted + staged changes vs base
{ git diff --name-only ${BASE_BRANCH}...HEAD 2>/dev/null; \
git diff --name-only; \
git diff --name-only --cached; } | sort -u
If all sources return empty, report that there are no changed files to analyze.
If the user specifies a target branch to analyze, detect the base branch the same way as the default mode, then diff:
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
| sed 's@^refs/remotes/origin/@@' || echo "main")
git diff --name-only ${BASE_BRANCH}...${BRANCH}
If given an explicit list of file paths rather than a branch name, use those directly without running git diff.
Read the full content of each changed file, not just diff hunks. Look for improvements in the entire file.
Do not:
dead-codeUnused functions, variables, imports, or types. Commented-out code blocks. Unreachable branches. Stale TODO/FIXME comments referencing completed work.
namingMisleading names that don't match current behavior (code evolved,
name didn't). Inconsistent patterns within the same file (e.g.,
getUserID vs fetchUserId). Single-letter variables in
non-trivial scope (beyond simple loop counters). Abbreviations
that hurt readability when the full word is short.
magic-valuesHardcoded numbers or strings that should be named constants. Repeated literal values that represent the same concept. Timeout/limit values embedded in logic without explanation.
deprecated-patternsOld APIs when newer alternatives exist in the same codebase. Patterns that the project has moved away from (check other recent files for the modern approach). Legacy error handling when the project now uses a different convention.
simplificationOverly complex logic that can be expressed more directly. Unnecessary indirection (wrapper functions that add no value). Redundant nil/error checks where the invariant is already guaranteed. Nested conditionals that can be flattened with early returns.
Score each opportunity on two dimensions (1-5 each):
Composite score = Impact × Low-Risk. Return only the top 3.
Present a summary table followed by per-suggestion details:
| # | File:Line | Category | Description | Effort | Score |
|---|---|---|---|---|---|
| 1 | location | category | description | effort | I×R=S |
| 2 | location | category | description | effort | I×R=S |
| 3 | location | category | description | effort | I×R=S |
For each suggestion, include:
If no improvement opportunities are found, report:
No significant improvement opportunities found. The touched files are in good shape.