| name | _ctx-qa |
| description | Run QA checks before committing. Use after writing code, before commits, or when CI might fail. |
Run the project's QA pipeline locally to catch issues before
they hit CI.
Before Running
- Check what changed: run
git diff --name-only to see
which files were modified; this determines which checks
to run (see "When to Run What" below)
- Build first:
CGO_ENABLED=0 go build -o /dev/null ./cmd/ctx
to catch compile errors before running the full pipeline
When to Use
- After writing or modifying Go code
- Before committing (catch issues locally, not in CI)
- When CI failed and you need to reproduce locally
- After dependency changes or refactors
When NOT to Use
- When only docs, markdown, or config files changed (no Go
code touched)
- When the user explicitly says "skip QA" or "commit without
checks"
- Mid-development when code is intentionally incomplete; wait
until a logical stopping point
Usage Examples
/_ctx-qa
/_ctx-qa (after refactoring the journal command)
What to Run
Run these checks in order; each depends on the previous
passing:
1. Format
gofmt -l .
If files are listed, they need formatting. Fix with
gofmt -w . and include the formatted files in the commit.
2. Vet
CGO_ENABLED=0 go vet ./...
3. Lint
golangci-lint run --timeout=5m
4. Test
CGO_ENABLED=0 CTX_SKIP_PATH_CHECK=1 go test ./...
5. Smoke (if CLI behavior changed)
make smoke
Builds the binary and exercises ctx init, ctx status,
ctx agent, ctx drift, ctx task add, and
ctx journal source in a temporary directory.
Shortcut
make audit runs steps 1-4 in sequence. Use it when you
want a single pass/fail answer.
When to Run What
| Changed | Minimum Check |
|---|
Any .go file | make audit |
| CLI command behavior | make audit + make smoke |
| Only docs/config | Nothing |
| Template files changed | go build (embed must work) |
On Failure
When a check fails, reason through the error before fixing:
read the output, trace the cause, then fix. Do not blindly
retry or apply the first fix that comes to mind.
Common Failures
| Failure | Fix |
|---|
gofmt -l lists files | gofmt -w . |
fmt.Printf in CLI code | Use cmd.Printf (enforced by AST test) |
| golangci-lint unused variable | Remove it; do not rename to _ |
Test needs CTX_SKIP_PATH_CHECK | Already set in make test and make audit |
Coverage below 70% on internal/context | Add tests; check with make test-coverage |
Output Format
After running checks, report:
- Result: pass or fail
- Failures: what failed and how to fix (if any)
- Files touched: list of files that were auto-formatted
Quality Checklist
Before reporting QA results, verify:
