What happened
In PR #58, the code agent added code fence tracking to parse_update_instructions() in src/comments.py to fix issue #57. The fix correctly handles backtick fences (```) including language specifiers, multiple fences, and unclosed fences. However, it only checks stripped.startswith("```") and does not recognize tilde fences (~~~), which are equally valid code fence delimiters per the CommonMark spec. The review agent identified this gap during review but classified it as info severity (below the reporting threshold) and approved the PR. The PR was merged at 2026-08-16 10:33 UTC.
A user writing [update-docs] instructions containing a tilde-fenced code block with a filename.ext: text line inside it will still have that line incorrectly extracted as a per-file instruction — the same bug class that issue #57 described for backtick fences.
What could go better
The code agent implemented the fix using only backtick detection (stripped.startswith("```")). The triage agent's analysis on issue #57 also specified only triple backticks in its proposed fix, so the code agent followed its guidance faithfully. The gap originated upstream: neither the issue author (retro agent on PR #56) nor the triage agent mentioned tilde fences as an alternative delimiter.
The review agent's correctness sub-agent did independently discover the tilde fence gap during review, which demonstrates good analytical capability. However, it classified the finding as info/negligible with actionable: false because tilde fences are "rare in GitHub comments." This severity assessment is reasonable for a general-purpose change but arguably too lenient for a PR whose sole purpose is adding code fence support — missing an entire fence syntax means the feature is incomplete. Confidence: high that this is a real bug; medium-low on practical impact since tilde fences in [update-docs] comments are uncommon but plausible, especially in documentation-focused projects (which is this tool's target audience).
A secondary edge case exists with nested backtick fences (e.g., a ```````` fence containing inner ``` ), where the simple boolean toggle would break. This is lower impact but worth noting.
Proposed change
In src/comments.py, in the parse_update_instructions() function, extend the code fence detection to also recognize tilde fences. The minimal fix is changing:
if stripped.startswith("```"):to:
if stripped.startswith("```") or stripped.startswith("~~~"):Add a test case in tests/test_comment_parsing.py that verifies a filename.ext: instruction-shaped line inside a ~~~ tilde fence is preserved in global instructions and not extracted as a per-file instruction. Example:
def test_tilde_code_fence_preserves_file_pattern(self):
comment = (
"[update-docs] here is an example:\n"
"~~~\n"
"pools.rst: example usage\n"
"~~~\n"
"health-checks.rst: update the CLI section"
)
global_inst, file_inst = parse_update_instructions(comment)
assert "pools.rst: example usage" in global_inst
assert "pools.rst" not in file_inst
assert "health-checks.rst" in file_instValidation criteria
The new test case passes. Existing tests (415+) continue to pass. Running uv run ruff check src/ tests/ produces no new warnings. A manual test with a ~~~-fenced code block containing a filename.ext: text line confirms the line is preserved in global instructions.
Generated by retro agent from #58
What happened
In PR #58, the code agent added code fence tracking to
parse_update_instructions()insrc/comments.pyto fix issue #57. The fix correctly handles backtick fences (```) including language specifiers, multiple fences, and unclosed fences. However, it only checksstripped.startswith("```")and does not recognize tilde fences (~~~), which are equally valid code fence delimiters per the CommonMark spec. The review agent identified this gap during review but classified it asinfoseverity (below the reporting threshold) and approved the PR. The PR was merged at 2026-08-16 10:33 UTC.A user writing
[update-docs]instructions containing a tilde-fenced code block with afilename.ext: textline inside it will still have that line incorrectly extracted as a per-file instruction — the same bug class that issue #57 described for backtick fences.What could go better
The code agent implemented the fix using only backtick detection (
stripped.startswith("```")). The triage agent's analysis on issue #57 also specified only triple backticks in its proposed fix, so the code agent followed its guidance faithfully. The gap originated upstream: neither the issue author (retro agent on PR #56) nor the triage agent mentioned tilde fences as an alternative delimiter.The review agent's correctness sub-agent did independently discover the tilde fence gap during review, which demonstrates good analytical capability. However, it classified the finding as
info/negligiblewithactionable: falsebecause tilde fences are "rare in GitHub comments." This severity assessment is reasonable for a general-purpose change but arguably too lenient for a PR whose sole purpose is adding code fence support — missing an entire fence syntax means the feature is incomplete. Confidence: high that this is a real bug; medium-low on practical impact since tilde fences in[update-docs]comments are uncommon but plausible, especially in documentation-focused projects (which is this tool's target audience).A secondary edge case exists with nested backtick fences (e.g., a ```````` fence containing inner ``` ), where the simple boolean toggle would break. This is lower impact but worth noting.
Proposed change
In
src/comments.py, in theparse_update_instructions()function, extend the code fence detection to also recognize tilde fences. The minimal fix is changing:to:
Add a test case in
tests/test_comment_parsing.pythat verifies afilename.ext: instruction-shaped line inside a~~~tilde fence is preserved in global instructions and not extracted as a per-file instruction. Example:Validation criteria
The new test case passes. Existing tests (415+) continue to pass. Running
uv run ruff check src/ tests/produces no new warnings. A manual test with a~~~-fenced code block containing afilename.ext: textline confirms the line is preserved in global instructions.Generated by retro agent from #58