What happened
On PR #748, a <!-- skillsaw-disable-next-line content-placeholder-text --> HTML comment was inserted between two Markdown list items at flush-left (zero) indentation to suppress a false-positive lint match. The review agent ran on the initial commit (run 31515289059) and did not flag any rendering issue.
Human reviewer waynesun09 verified via gh api markdown (GFM mode) that the unindented comment split the self-review checklist into two separate <ul> elements on GitHub, visually breaking the list. The fix was indenting the comment by 2 spaces so it becomes continuation content of the preceding list item (commit 3fd69a4, run 31803799453).
What could go better
The correctness sub-agent owns logic errors and unintended side effects. An HTML comment insertion that breaks Markdown list rendering is an unintended side effect — the author intended to suppress a lint match, not break the checklist. The sub-agent likely lacked specific knowledge of GFM list continuation rules: in GitHub-Flavored Markdown, content between list items must be indented to the list item's content level to remain continuation content; unindented content (including HTML comments) terminates the list.
This is a well-documented GFM behavior, not an obscure edge case. The human reviewer caught it by actually rendering the output — a verification step the sub-agent does not perform.
Confidence: medium. The root cause could be the sub-agent's prompt lacking Markdown rendering guidance, or the scope constraint preventing deep analysis of a seemingly trivial change.
Proposed change
In skills/pr-review/sub-agents/correctness.md, add a Markdown-specific guidance section:
Markdown rendering correctness: When a change inserts content between Markdown list items (including HTML comments, directive comments, or non-list-item text), verify that the insertion maintains list continuity per GFM rules. Specifically:
- HTML comments between list items must be indented to the list item's content level to remain continuation content.
- Unindented HTML comments, blank lines followed by unindented content, or block-level elements between list items break the list into separate elements.
- If uncertain, note the risk in findings rather than silently approving.
This adds a targeted heuristic for a common Markdown editing mistake without requiring the sub-agent to learn all GFM rendering rules.
Validation criteria
On the next 2 PRs that insert HTML comments or directive comments between Markdown list items, the correctness sub-agent should flag any unindented insertion that could break list rendering. If no such PRs occur within 60 days, validate by confirming the sub-agent definition includes the added guidance.
Generated by retro agent from #748
What happened
On PR #748, a
<!-- skillsaw-disable-next-line content-placeholder-text -->HTML comment was inserted between two Markdown list items at flush-left (zero) indentation to suppress a false-positive lint match. The review agent ran on the initial commit (run 31515289059) and did not flag any rendering issue.Human reviewer waynesun09 verified via
gh api markdown(GFM mode) that the unindented comment split the self-review checklist into two separate<ul>elements on GitHub, visually breaking the list. The fix was indenting the comment by 2 spaces so it becomes continuation content of the preceding list item (commit3fd69a4, run 31803799453).What could go better
The correctness sub-agent owns logic errors and unintended side effects. An HTML comment insertion that breaks Markdown list rendering is an unintended side effect — the author intended to suppress a lint match, not break the checklist. The sub-agent likely lacked specific knowledge of GFM list continuation rules: in GitHub-Flavored Markdown, content between list items must be indented to the list item's content level to remain continuation content; unindented content (including HTML comments) terminates the list.
This is a well-documented GFM behavior, not an obscure edge case. The human reviewer caught it by actually rendering the output — a verification step the sub-agent does not perform.
Confidence: medium. The root cause could be the sub-agent's prompt lacking Markdown rendering guidance, or the scope constraint preventing deep analysis of a seemingly trivial change.
Proposed change
In
skills/pr-review/sub-agents/correctness.md, add a Markdown-specific guidance section:This adds a targeted heuristic for a common Markdown editing mistake without requiring the sub-agent to learn all GFM rendering rules.
Validation criteria
On the next 2 PRs that insert HTML comments or directive comments between Markdown list items, the correctness sub-agent should flag any unindented insertion that could break list rendering. If no such PRs occur within 60 days, validate by confirming the sub-agent definition includes the added guidance.
Generated by retro agent from #748