feat(godoc): bootstrap 4 rule blocks in go-doc-best-practices

[bborbe]

Summary

Bootstraps `docs/go-doc-best-practices.md` — 4 rule blocks added to the godoc style guide. Mirrors PRs #2-5, #8, #10, #14.

`rules/index.json`: 46 → 50 entries.

Rules added

id	level	enforcement
`go-doc/exported-item-must-have-comment`	MUST	judgment (mechanical follow-up: revive `exported` rule)
`go-doc/comment-starts-with-name`	MUST	judgment (mechanical follow-up: revive / ast-grep via PR #11 recipe)
`go-doc/package-comment-in-doc-go`	SHOULD	judgment (filename + first-comment-block)
`go-doc/third-person-no-signature-repeat`	SHOULD	judgment (semantic)

Notes

• All MUST rules are mechanically enforceable via `revive`'s `exported` lint rule (already covers item-must-have-comment + comment-starts-with-name). The mechanical layer is a focused follow-up; this PR establishes the rule blocks first.
• Generic examples throughout (Order, Customer, Discount, Add). No trading-domain terms.
• `godoc-assistant` agent exists at `agents/godoc-assistant.md` — owner field resolves.

Pre-emptive checks

• `grep -nEi "personal/|/users/bborbe|~/documents/obsidian"` → clean
• Trading-term grep → clean
• All 4 rule IDs unique
• `make build-index` regenerated; `check-index` passes (PR feat(precommit): add check-index target to catch walker-output drift #13 drift guard happy)

Test plan

• `make precommit` clean
• 4 `go-doc/*` entries in index with correct level + owner
• Bot review

[ben-s-pull-request-reviewer]

{
"verdict": "request-changes",
"summary": "The 4 new godoc RULE blocks are structurally sound and well-aligned with the guide's purpose, but the enforcement claim for `go-doc/comment-starts-with-name` contains a factual error that could mislead developers wiring up linters. One SHOULD-level rule also omits exported struct fields from its applies_when scope.",
"comments": [
{
"file": "rules/index.json",
"line": 78,
"severity": "critical",
"message": "Must Fix — `go-doc/comment-starts-with-name` enforcement notes \"`revive`'s `exported` rule enforces this\" — this is factually incorrect. `revive`'s `exported` rule only checks that exported identifiers have a doc comment; it does NOT verify that the comment's first word matches the identifier name. No standard linter enforces the \"starts with name\" requirement. Remove the `revive` claim and keep only the ast-grep / judgment path."
},
{
"file": "docs/go-doc-best-practices.md",
"line": 19,
"severity": "major",
"message": "Should Fix — `go-doc/exported-item-must-have-comment` applies_when lists \"function, method, type, interface, struct, constant, or variable\" but omits exported struct fields, which `revive`'s `exported` rule does flag. Add \"exported struct field\" to the enumeration."
},
{
"file": "rules/index.json",
"line": 87,
"severity": "major",
"message": "Should Fix — same issue as above propagates to `rules/index.json` applies_when field for `go-doc/exported-item-must-have-comment`."
}
],
"concerns_addressed": [
"correctness: rules/index.json has 4 new JSON entries with all required fields (id, anchor, applies_when, enforcement, level, owner, doc_path) — verified present and well-formed",
"correctness: 4 new RULE blocks in docs/go-doc-best-practices.md follow consistent formatting (MUST/SHOULD level, owner, applies_when/enforcement/Why, Bad/Good examples) — verified",
"correctness: `go-doc/third-person-no-signature-repeat` enforcement honestly notes \"prose linters can flag first-person; signature-repeat is semantic and needs review\" — this is accurate and not conflating separate checks",
"tests: `make build-index` regenerated `rules/index.json` — entries are sorted correctly (go-doc/* rules appear in alphabetical order before go-errors/*)"
]
}

superseded by new automated review

[ben-s-pull-request-reviewer]

PR Review: feat(godoc): bootstrap 4 rule blocks in go-doc-best-practices

Automated Checks

Check	Status
rules/index.json JSON syntax	✅ Valid
LICENSE file present	✅ Found
Makefile precommit	⚠️ Could not run (sandbox blocked make)

Anchor Link Verification

All 4 anchors match exactly between docs/go-doc-best-practices.md and rules/index.json:

Rule ID	Markdown header	rules/index.json anchor	Match
go-doc/exported-item-must-have-comment	line 16	line 84	✅
go-doc/comment-starts-with-name	line 51	line 75	✅
go-doc/package-comment-in-doc-go	line 73	line 93	✅
go-doc/third-person-no-signature-repeat	line 106	line 102	✅

Level Classification Review

Rule	Level in diff	Assessment
exported-item-must-have-comment	MUST	✅ Correct — undocumented exported identifiers are a critical gap
comment-starts-with-name	MUST	✅ Correct — wrong first word breaks godoc/pkg.go.dev rendering
package-comment-in-doc-go	SHOULD	✅ Correct — doc.go convention, not a correctness issue
third-person-no-signature-repeat	SHOULD	✅ Correct — style/register issue, not a correctness issue

Markdown Code Block Review

• All #### Bad / #### Good code blocks contain syntactically valid Go code
• Order / Discount / Price / Customer types used consistently across Bad/Good examples
• No orphaned code fragments or inconsistent type references

Findings

Must Fix (Critical): None.

Should Fix (Important): None.

Nice to Have (Optional): None.

Verdict

approve — The diff correctly bootstraps 4 rule blocks with matching anchors in both the markdown guide and rules/index.json, appropriate MUST/SHOULD classification, and syntactically valid Go examples throughout.

---

{
"verdict": "approve",
"summary": "PR #15 bootstraps 4 godoc rule blocks in go-doc-best-practices.md with matching entries in rules/index.json. All 4 anchors match exactly, MUST/SHOULD levels are appropriately assigned, and Go code examples are syntactically valid and internally consistent. No issues found.",
"comments": [],
"concerns_addressed": [
"correctness: anchor links match exactly between markdown headers and rules/index.json entries — verified",
"correctness: 2 MUST rules (exported-item-must-have-comment, comment-starts-with-name) and 2 SHOULD rules (package-comment-in-doc-go, third-person-no-signature-repeat) are appropriately classified — verified",
"docs: markdown Go code blocks under each rule are syntactically valid Go and Bad/Good sections are internally consistent — verified"
]
}