feat(prometheus): bootstrap 6 rule blocks in go-prometheus-metrics-guide

[bborbe]

Summary

Bootstraps `docs/go-prometheus-metrics-guide.md` — converts its 6 MUST/SHOULD sections into canonical `### RULE` blocks. Mirrors the template proven across PRs #2-5.

`rules/index.json`: 21 → 27 entries (6 new go-prometheus rules).

Rules added (all judgment for this PR)

id	level	notes
`go-prometheus/counter-pre-initialization`	MUST	.Add(0) for known label combos
`go-prometheus/composed-metrics-interface`	SHOULD	Interface segregation
`go-prometheus/no-gauge-for-monotonic`	MUST	GaugeVec → CounterVec
`go-prometheus/counter-total-suffix`	MUST	Name ends with `_total`
`go-prometheus/help-string-quality`	MUST	Unique, accurate Help strings
`go-prometheus/label-naming-consistency`	MUST	Same label name per concept

ast-grep YAML deferred

The `counter-total-suffix` rule is mechanically enforceable in principle, but ast-grep 0.43.0's traversal of `CounterOpts` struct literals (composite_literal → literal_value → keyed_element → identifier + interpreted_string_literal) needs more debugging than this PR's scope. Drafted a YAML, smoke-tested locally, got zero matches on known-bad cases. Same trap PR #4 hit — punting to a focused follow-up rather than iterating in this PR.

The rule block itself is fully populated; only the `Enforcement:` field stays as `judgment` until the YAML lands.

Pre-emptive clean-up applied (lessons from PR #6)

• No personal vault paths — `grep` clean
• No trading-domain terms — also fixed one leftover from the PR docs: trim go-prometheus-metrics-guide to rules-only (2399 → 379 lines) #6 trim: BAD example for `no-gauge-for-monotonic` used `candleHandleTotalCounter` + `broker` label; now `orderHandleTotalCounter` + `tenant`
• No section with MUST/SHOULD prose missing a rule id — every enforceable claim now has an id

Test plan

• `make precommit` clean (links + JSON)
• `make build-index` succeeds; index grows 21 → 27
• All 6 prometheus rule ids appear in index with correct level + owner
• No personal paths, no trading terms (grep verified)
• Bot review on this PR (run `github-pr-watch --trigger` after merge of this PR's reviewer entry)

[ben-s-pull-request-reviewer]

Step 5: Consolidated Report

---

PR Review: feat(prometheus): bootstrap 6 rule blocks in go-prometheus-metrics-guide

Target branch: master → feat/bootstrap-prometheus
Scope: docs (2 files changed: docs/go-prometheus-metrics-guide.md, rules/index.json)
Change summary: Added 6 new Prometheus metric RULE blocks to the guide and registered them in rules/index.json (21 → 27 entries).

---

Must Fix (Critical)

1. docs/go-prometheus-metrics-guide.md — Internal contradiction between two rules

The Good example for go-prometheus/no-gauge-for-monotonic (line ~127) shows:

orderHandleTotalCounter=prometheus.NewCounterVec(prometheus.CounterOpts{
Name: "total", // ← missing "_total" suffix
}, []string{"tenant"})

This directly contradicts go-prometheus/counter-total-suffix (also added in this PR, line ~206), which is a MUST rule requiring all Counter names to end with _total. A reader who follows the no-gauge-for-monotonic Good example will produce a metric that violates the counter-total-suffix rule in the same guide.

Fix: Change to Name: "order_handle_total" or any name ending in _total.

---

Should Fix (Important)

2. docs/go-prometheus-metrics-guide.md — Imprecise PromQL explanation in no-gauge-for-monotonic Why

The Why text reads: "they assume the underlying type is a counter that can reset to zero on process restart"

PromQL functions are type-agnostic — they don't inspect metric types. The actual mechanism: rate() and increase() interpret any downward movement as a counter reset. The explanation is directionally correct but misstates the cause.

3. docs/go-prometheus-metrics-guide.md — Verbose Enforcement in counter-total-suffix

The Enforcement field reads: "judgment (mechanical ast-grep YAML tracked as follow-up; CounterOpts struct-literal traversal in ast-grep 0.43.0 needs further investigation)"

Tool-execution notes belong in task trackers, not enforceable rule blocks. Simplify to "judgment" or "judgment (ast-grep follow-up)".

---

Nice to Have (Optional)

4. help-string-quality — Only one Bad/Good pair, but Applies when has three conditions
The rule lists (a) empty Help, (b) duplicate Help, (c) copy-paste residue — but only (c) has an example.

5. composed-metrics-interface — Arbitrary ~6 method threshold
The count-based heuristic can be gamed. Reframe around functional-domain span rather than a magic number.

6. counter-pre-initialization — Missing cardinality caveat
Pre-initializing unbounded label domains (e.g., 200 endpoints) is costly. The Why should note the rule only applies to small, bounded domains (< ~20 combinations).

---

Security Check ✅

Diff was scanned for residual personal vault paths and trading-domain terms (Candle, Epic, Broker, SignalStore, SignalStore, etc.). None found. All examples use generic terms (tenant, product, channel).

---

rules/index.json Review ✅

All 6 new entries are correct: level, owner, applies_when, enforcement, doc_path, id, and anchor fields all match the doc. No JSON syntax errors. Entries are alphabetically ordered. Coverage: 6/6 doc rules have matching index entries.

---

Step 6: Next Steps

Fix the Name: "total" → Name: "order_handle_total" contradiction (Must Fix #1) before merging. The other issues are non-blocking but should be addressed for polish.

---

Verdict JSON

{
"verdict": "request-changes",
"summary": "Six new Prometheus rule blocks are well-structured and the rules/index.json is correct, but a critical internal contradiction exists: the Good example in no-gauge-for-monotonic uses 'Name: total' which violates the counter-total-suffix MUST rule added in the same PR. Two should-fix issues (imprecise PromQL explanation, verbose enforcement field) and three nice-to-have items also need attention.",
"comments": [
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 127,
"severity": "critical",
"message": "Must Fix: The Good example for go-prometheus/no-gauge-for-monotonic shows Name: \"total\" which does not end with _total, directly contradicting the go-prometheus/counter-total-suffix MUST rule defined in the same guide. Change to Name: \"order_handle_total\" or any name ending in _total."
},
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 110,
"severity": "major",
"message": "Should Fix: The Why paragraph for no-gauge-for-monotonic states that rate()/increase() 'assume the underlying type is a counter that can reset to zero on process restart.' This is imprecise — PromQL is type-agnostic and interprets any downward movement as a reset, not just process restarts. Reword to clarify the actual mechanism."
},
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 210,
"severity": "major",
"message": "Should Fix: The Enforcement field for counter-total-suffix is verbose with implementation notes ('ast-grep YAML tracked as follow-up; CounterOpts struct-literal traversal in ast-grep 0.43.0 needs further investigation'). These belong in task trackers, not enforceable rules. Simplify to 'judgment' or 'judgment (ast-grep follow-up)'."
},
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 241,
"severity": "nit",
"message": "Nice to Have: help-string-quality's Applies when clause lists three conditions (empty, duplicate, copy-paste residue Help) but only the third is illustrated with a Bad/Good pair. Add examples for empty Help (Help: \"\") and duplicate Help."
},
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 56,
"severity": "nit",
"message": "Nice to Have: composed-metrics-interface uses an arbitrary '~6 methods' threshold. Reframe the applies_when clause around functional-domain span rather than a count-based heuristic that can be misapplied."
},
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 23,
"severity": "nit",
"message": "Nice to Have: counter-pre-initialization should note that pre-initialization is only worthwhile for small bounded label domains (typically < 20 combinations). For large domains, callers should prefer absent() checks in alerting rules."
}
],
"concerns_addressed": [
"correctness: counter-total-suffix enforcement judgment noted — ast-grep YAML deferred as documented follow-up, not flagged as an error",
"security: no residual personal vault paths or trading-domain terms found — examples use only generic tenant/product/channel",
"tests: rules/index.json grew 21 → 27 entries with correct level (5 MUST, 1 SHOULD) and owner (go-metrics-assistant) for all 6 new rules"
]
}

superseded by new automated review

[ben-s-pull-request-reviewer]

{
"verdict": "approve",
"summary": "PR #8 bootstraps 6 `### RULE` blocks in go-prometheus-metrics-guide with matching index.json entries, all correctly anchored, owned by go-metrics-assistant (confirmed to exist), and free of trading-domain terms. All four plan concerns are resolved: anchors match, enforcement distinction for counter-total-suffix is intentional and documented, and the agent is live. One minor note on the commit message accuracy and one absence worth tracking.",
"comments": [
{
"file": "docs/go-prometheus-metrics-guide.md",
"line": 20,
"severity": "minor",
"message": "counter-pre-initialization: anchor present and correct, but the commit message for PR #8 described the bootstrap template as using `## RULE <id>` level headers. The actual markdown uses `### RULE` (H3), which is consistent with other guides in the repo. No action needed — just a commit-message inaccuracy that does not affect tooling."
},
{
"file": "rules/index.json",
"line": 147,
"severity": "minor",
"message": "counter-total-suffix enforcement reads 'judgment (ast-grep follow-up)' while the other 5 rules say just 'judgment'. This is intentional per the commit message — a mechanical ast-grep pattern was deferred to a follow-up PR rather than blocking the bootstrap. The distinction is correctly documented here."
}
],
"concerns_addressed": [
"correctness: anchor values in index.json match the ### RULE anchors in markdown doc exactly — go-prometheus/counter-pre-initialization, composed-metrics-interface, no-gauge-for-monotonic, counter-total-suffix, help-string-quality, label-naming-consistency all verified at lines 20, 53, 105, 206, 231, 273",
"correctness: counter-total-suffix enforcement 'judgment (ast-grep follow-up)' is intentional — the commit message explains mechanical ast-grep was deferred to a focused follow-up PR",
"correctness: rule anchor links in markdown match id fields in rules/index.json — all 6 verified",
"correctness: all 6 rules have owner 'go-metrics-assistant' — agent confirmed to exist at agents/go-metrics-assistant.md"
]
}