notque/vexjoy-agent / skills/programming/programming
programming
FlaggedLanguage rules, workflows, and tooling: Go, Python, Rust, Kotlin, Swift, PHP, TypeScript type checks and debugging, OpenStack Python, MCP local-docs servers, Node.js backend APIs.
references/go/quality-gate.md
View on GitHub
# Go PR Quality Gate Skill
Run `make check` as the single source of truth for Go code quality, parse the output into categorized errors, and suggest actionable fixes. The skill identifies issues and suggests make targets -- it does not fix code automatically, run custom linters, modify Makefiles, run checks incrementally on single files, or interpret business logic errors.
## Instructions
### Step 1: Read Repository CLAUDE.md
Read and follow the repository's CLAUDE.md before doing anything else. It may contain project-specific quality requirements or overrides.
### Step 2: Validate Repository Context
Never skip validation, even if you think you know what the error is -- assumptions miss prerequisites and waste time debugging the environment instead of code quality.
Run the validation script to check prerequisites:
```bash
python3 ~/.claude/skills/programming/scripts/quality_checker.py --validate-only
```
The repository needs:
- `go.mod` at root (Go module)
- `Makefile` with a `check` target
- A git repository
Expected success output:
```json
{
"status": "valid",
"repository": "/path/to/repo",
"has_gomod": true,
"has_makefile": true,
"is_gomakefilemaker": true
}
```
If validation fails:
- **"Not a Go repository"**: Navigate to a directory with `go.mod`
- **"Makefile not found"**: Repository may need a Makefile-based build workflow setup
- **"Not in git repository"**: Initialize git or navigate to repo root
**Gate**: Validation returns `"status": "valid"`. Proceed only when gate passes.
### Step 3: Run Quality Checks
Always use `make check` through the script -- never bypass it by running golangci-lint, go test, or go vet individually. Different projects configure their quality gates differently, and running tools directly skips whatever the Makefile includes.
Execute the quality gate:
```bash
python3 ~/.claude/skills/programming/scripts/quality_checker.py
```
The script will:
1. Run `make check` (static analysis + tests)
2. Parse output for errors and coverage
3. Categorize any failures
4. Generate an actionable report with fix suggestions
For verbose progress output:
```bash
python3 ~/.claude/skills/programming/scripts/quality_checker.py --verbose
```
### Step 4: Interpret Results
Report facts: exact error messages, file locations, exit codes, and coverage percentages. Do not editorialize or self-congratulate on passing checks.
#### Success Scenario
```json
{
"status": "success",
"coverage": "87.3%",
"checks_passed": ["static-check", "test", "coverage"],
"summary": "All quality checks passed"
}
```
When successful:
1. Acknowledge passing checks
2. Report coverage percentage -- always include it, because silently dropping coverage hides regressions
3. Suggest next steps: view detailed coverage (`open build/cover.html`), create commit, or run specific checks
#### Failure Scenario
```json
{
"status": "failed",
"exit_code": 2,
"errors": {
"linting": [{"linter": "errcheck", "file": "pkg/api/handler.go", "line": 45, "message": "Error return value not checked", "severity": "high"}],
"tests": [{"package": "github.com/example/pkg/service", "test": "TestProcessRequest", "error": "expected 200, got 500"}]
},
"fix_commands": ["make goimports", "make tidy-deps"]
}
```
When failures occur:
1. **Categorize errors** by type (linting, tests, build, license)
2. **Group linting errors** by linter name (errcheck, gosec, govet, etc.)
3. **Show actionable fixes** using the structured output:
- Import issues: `make goimports`
- Dependency issues: `make tidy-deps`
- License headers: `make license-headers`
- Specific linter guidance: check `${CLAUDE_SKILL_DIR}/references/go/quality-gate/common-lint-errors.json`
4. **Provide context**: file paths, line numbers, error descriptions
5. **Report exact exit codes** from make -- never mask or modify them
Keep explanations brief. Report the specific error with its location and the fix suggestion from script output. Only explain further if the user asks -- a quality check is not a tutorial.
### Step 5: Apply Fixes Incrementally
Fix one category at a time. Applying 15 fixes across multiple files simultaneously makes it impossible to verify which fix resolved which error, and if one fix is wrong, everything needs rollback.
For common error patterns, run suggested make targets one at a time:
```bash
# Fix import formatting
make goimports
# Fix dependency issues
make tidy-deps
# Add/update license headers
make license-headers
```
After each fix, re-run quality checks (Step 3) to verify resolution before moving to the next category.
**Gate**: All checks pass (exit code 0). Coverage meets baseline. No linting errors. All tests pass.
### Step 6: Detailed Investigation (Optional)
For complex failures, use specific make targets to isolate the problem:
```bash
# Run only static analysis
make static-check
# Run only tests
make test
# Run specific test with verbose output
go test -v -run TestSpecificTest ./pkg/service
# View HTML coverage report
open build/cover.html
```
Only use individual make targets for focused investigation after `make check` has failed -- not as a substitute for it.
### Advanced Options
Custom coverage threshold enforcement:
```bash
python3 ~/.claude/skills/programming/scripts/quality_checker.py --min-coverage 80.0
```
JSON output for automation pipelines:
```bash
python3 ~/.claude/skills/programming/scripts/quality_checker.py --format json
```
Combined options for thorough debugging:
```bash
python3 ~/.claude/skills/programming/scripts/quality_checker.py --min-coverage 80.0 --verbose
```
### Cleanup
Remove temporary analysis files and debug logs at completion. Keep only files needed for user review.
---
## Error Handling
### Error: "make: *** [check] Error 2"
Cause: One or more quality checks failed (linting, tests, or build)
Solution:
1. Review error categorization in JSON output
2. Apply suggested fixes from `fix_commands` array
3. Check `${CLAUDE_SKILL_DIR}/references/go/quality-gate/common-lint-errors.json` for specific linter guidance
4. Re-run checks after each fix
### Error: "golangci-lint: command not found"
Cause: Static analysis tools not installed on the system
Solution:
1. Install via package manager: `brew install golangci-lint`
2. Or use project's install script if available
3. Verify with: `golangci-lint --version`
### Error: "coverage: 0.0% of statements"
Cause: No test files exist, or test packages have no executable tests
Solution:
1. Verify test files exist: look for `*_test.go` files
2. Verify tests run independently: `make test`
3. Check that test functions follow `Test` naming convention
### Error: Script Times Out
Cause: Tests hang, infinite loops, or blocking external dependencies
Solution:
1. Run individual targets to isolate: `make static-check`, `make test`
2. Check for hanging tests or external service dependencies
3. Run specific test in isolation: `go test -v -run TestName ./pkg/...`
---
## References
- `${CLAUDE_SKILL_DIR}/references/go/quality-gate/common-lint-errors.json`: Linter descriptions, severities, and fix suggestions
- `${CLAUDE_SKILL_DIR}/references/go/quality-gate/makefile-targets.json`: Available make targets and when to use them
- `${CLAUDE_SKILL_DIR}/references/go/quality-gate/expert-review-patterns.md`: Manual review patterns beyond automated linting
- `${CLAUDE_SKILL_DIR}/references/go/quality-gate/examples.md`: Detailed usage examples with expected output
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |