docs: add repository-level gauge-repo engineering best-practices audit - #127
Conversation
Adds the complete Markdown report from the gauge-repo skill run at repository scope under docs/. Adjusted compliance 35.9%; critical gates RED (items 2, 16, 40). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![argus-pattern[bot]](https://avatars.githubusercontent.com/in/4870434?s=60&v=4){kind=small}
|
|
||
| ## Repo profile | ||
|
|
||
| `caterpillar` is a Go 1.25 data-ingestion and pipeline-processing engine owned by Pattern (`patterninc/caterpillar`, verified via `gh repo view`). It ships as a distributable CLI binary and a multi-arch Docker image published to Docker Hub (`patternoss/caterpillar`) by `.github/workflows/release.yaml`; the repo itself deploys no hosted service — no Terraform, no ECS/Lambda/Kubernetes configs, no owned database. Package layout follows the Go idiom (`cmd/caterpillar`, `internal/pkg/pipeline/task/...`), with a per-task `README.md` under each of the 21 `task/*` directories. GitHub reports ~15 human contributors, and `.github/CODEOWNERS` assigns everything to `@patterninc/data-acquisition`, so this is a team-scale repo. AWS SDK integrations (SQS, SNS, S3, Parameter Store, Translate) exist as pipeline tasks the *user's* pipelines run against; the repo has no owned AWS footprint, so item 49's `aws[]` sub-check does not apply. There is no browser UI, no visual surface, and no persistence layer. Because ownership is `patterninc` (API-verified), Pattern inherited controls apply to items 19, 20, 39, and 47. |
There was a problem hiding this comment.
The task-directory count is off: internal/pkg/pipeline/task/ has 20 directories, not 21, and one of them (aws/) has no README.md — so there are 19 per-task READMEs, not one under each. This makes both this line's "21 task/* directories" and the "under all 21 … directories" claim in the "Beyond the checklist" section inaccurate.
Fix: correct the count to 20 directories / 19 READMEs and drop the "all"/"each" wording, or note aws/ as the exception.
There was a problem hiding this comment.
Good catch — corrected in 54b5bba. The profile now reads "19 of the 20 task/* directories (the aws/ wrapper directory has none; its integration lives in aws/parameter_store/)" and the Beyond-the-checklist line drops the "all"/"each" wording with the same aws/ exception noted.
There was a problem hiding this comment.
Good catch — corrected in 54b5bba. The profile now reads "19 of the 20 task/* directories (the aws/ wrapper directory has none; its integration lives in aws/parameter_store/)" and the Beyond-the-checklist line drops the all/each wording with the same aws/ exception noted.
The task directory has 20 subdirectories with 19 per-task READMEs; the aws/ wrapper has none (its integration lives in aws/parameter_store/). Corrects the profile and Beyond-the-checklist sections that claimed 21 directories with a README under each. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Argus reviewed this head (54b5bba). This is a docs-only change adding docs/engineering-best-practices-audit.md, the repository-scoped gauge-repo report. Spec-wise it satisfies the requested outcome: the full report (per-item verdict tables, prioritized recommendations, declined practices, and strengths) is captured in a single, descriptively named Markdown file under docs/.
For accuracy I spot-checked the concrete claims against the tree — Go 1.25 module, CI running only go build, the empty directories= in makefile, absent AGENTS.md, the unit/integration test files, the 18 *_test.yaml scenarios, and the Dockerfile/release version pins — all consistent. The earlier task-directory/README count discrepancy has been corrected (20 task/* directories, 19 with READMEs, aws/ being the wrapper whose integration lives in aws/parameter_store/), and that now matches the tree.
No inline comments this cycle.
1 participant
Summary
Runs the
gauge-reposkill at repository scope againstpatterninc/caterpillarand commits the complete Markdown report atdocs/engineering-best-practices-audit.md.AGENTS.md), item 16 (required CI runs onlygo build, no tests/lint, no required status checks in the ruleset), item 40 (no documented dev/stage/prod secret-scoping convention)AGENTS.md, extend CI withgo test ./...+golangci-lintand mark them required, document the SSM prefix layout for scoped secrets.The report includes the full per-item verdict tables (all 49 checklist items with evidence), 27 ticket-ready prioritized recommendations, the 10 declined practices with profile-backed rationales, and a "Beyond the checklist" strengths section. A previous audit (PR #119) was reverted in PR #122; this re-audit found no item changed status since, and notes that under "Changes since last audit".
Validation: docs-only change (single new Markdown file); the repo's CI check (
go build) is unaffected and the Go toolchain is not available in this worker, so no local build was run.Oly run: https://oly.pattern.com/runs/01a0c805-c459-76f5-9566-ae4143e1916e
Requested by: shashank.mittal@pattern.com
🤖 Generated with Claude Code