What happened
On PR #246, the review agent flagged multiple AsciiDoc convention violations that required fix-push-review cycles: (1) placeholder formatting — bare <placeholder> instead of the repo's established [,yaml,subs="+quotes"] with __<placeholder>__ pattern (medium severity, review run 33374015666), (2) title casing — page title used title case while nav entry used sentence case (low severity, same run), (3) step heading style not matching existing guides (low severity, run 33075552379). The author addressed each finding in separate commits, triggering 3 additional full reviews ($12.28) on Aug 31 alone. The CLAUDE.md documents repo structure and build commands but contains no AsciiDoc content conventions.
What could go better
The review agent had to discover AsciiDoc conventions by cross-referencing existing files each run, and the author was unaware of some conventions (like the placeholder formatting pattern used in only 2 other files). If CLAUDE.md documented the established patterns, authors would apply them from the first commit, and the review agent would have an authoritative reference rather than inferring conventions from sparse examples. Confidence: moderate — this addresses convention-awareness but would not have prevented the cross-document API version finding (the most valuable catch), which was a content accuracy issue rather than a formatting convention.
Proposed change
Add an "AsciiDoc Content Conventions" section to CLAUDE.md documenting the patterns already established in the repo:
- Placeholder formatting: Use
[,yaml,subs="+quotes"] (or [,shell,subs="+quotes"]) with __<placeholder>__ for user-replaceable values in code blocks. This renders placeholders in italics.
- Page titles: Use sentence case (e.g., "Catching policy violations early"), not title case.
- Navigation entries: Must match page title casing (sentence case).
- Admonitions: Use
NOTE:, TIP:, WARNING: (the three types used in this repo). No IMPORTANT: or CAUTION:.
- Cross-references: Use Antora
xref:page.adoc[label] for local links, xref:component:module:page.adoc[label] for cross-component links.
- Code block language: Use Antora shorthand
[,language] (e.g., [,yaml], [,shell]).
This is complementary to issue #240 (AsciiDoc validation tooling), which catches structural errors. Convention documentation prevents style issues that automated validation cannot detect.
Validation criteria
On the next 3 documentation PRs to conforma/user-guide: (1) placeholder formatting findings should not appear in agent reviews — authors should use the documented pattern from the first commit, and (2) title casing findings should decrease or disappear. Measurable by comparing review finding categories on future PRs against the PR #246 baseline.
Generated by retro agent from #246
What happened
On PR #246, the review agent flagged multiple AsciiDoc convention violations that required fix-push-review cycles: (1) placeholder formatting — bare
<placeholder>instead of the repo's established[,yaml,subs="+quotes"]with__<placeholder>__pattern (medium severity, review run 33374015666), (2) title casing — page title used title case while nav entry used sentence case (low severity, same run), (3) step heading style not matching existing guides (low severity, run 33075552379). The author addressed each finding in separate commits, triggering 3 additional full reviews ($12.28) on Aug 31 alone. The CLAUDE.md documents repo structure and build commands but contains no AsciiDoc content conventions.What could go better
The review agent had to discover AsciiDoc conventions by cross-referencing existing files each run, and the author was unaware of some conventions (like the placeholder formatting pattern used in only 2 other files). If CLAUDE.md documented the established patterns, authors would apply them from the first commit, and the review agent would have an authoritative reference rather than inferring conventions from sparse examples. Confidence: moderate — this addresses convention-awareness but would not have prevented the cross-document API version finding (the most valuable catch), which was a content accuracy issue rather than a formatting convention.
Proposed change
Add an "AsciiDoc Content Conventions" section to
CLAUDE.mddocumenting the patterns already established in the repo:[,yaml,subs="+quotes"](or[,shell,subs="+quotes"]) with__<placeholder>__for user-replaceable values in code blocks. This renders placeholders in italics.NOTE:,TIP:,WARNING:(the three types used in this repo). NoIMPORTANT:orCAUTION:.xref:page.adoc[label]for local links,xref:component:module:page.adoc[label]for cross-component links.[,language](e.g.,[,yaml],[,shell]).This is complementary to issue #240 (AsciiDoc validation tooling), which catches structural errors. Convention documentation prevents style issues that automated validation cannot detect.
Validation criteria
On the next 3 documentation PRs to conforma/user-guide: (1) placeholder formatting findings should not appear in agent reviews — authors should use the documented pattern from the first commit, and (2) title casing findings should decrease or disappear. Measurable by comparing review finding categories on future PRs against the PR #246 baseline.
Generated by retro agent from #246