Skip to content

fix(rules): blank-line separate multiple-choice options (#246)#278

Open
gluefactory wants to merge 1 commit into
awslabs:mainfrom
gluefactory:issue-246-question-format-blank-lines
Open

fix(rules): blank-line separate multiple-choice options (#246)#278
gluefactory wants to merge 1 commit into
awslabs:mainfrom
gluefactory:issue-246-question-format-blank-lines

Conversation

@gluefactory
Copy link
Copy Markdown

@gluefactory gluefactory commented May 18, 2026

Summary

Closes #246.

Per the CommonMark spec, a soft line break renders as a single space. So
the multiple-choice template used in question-format-guide.md

A) Option A
B) Option B
C) Option C

— collapses into one paragraph (A) Option A B) Option B C) Option C) in
strict renderers (IntelliJ, PyCharm preview, VS Code without the GFM
setting). Most AI-DLC users are in those exact IDE-driven workflows, so
this hits in the common case.

Changes

  • Insert blank lines between options across the template and every file
    that follows it:
    • aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md
      (template + all in-page examples)
    • aidlc-rules/aws-aidlc-rule-details/common/session-continuity.md
    • aidlc-rules/aws-aidlc-rule-details/extensions/security/baseline/security-baseline.opt-in.md
    • aidlc-rules/aws-aidlc-rule-details/extensions/testing/property-based/property-based-testing.opt-in.md
    • docs/WORKING-WITH-AIDLC.md
  • Add a guard rail: a new CI step (alongside markdownlint) fails when
    any two consecutive lines both match ^[A-Z]\) without a blank-line
    separator. Scope mirrors .markdownlint-cli2.yaml ignores so behavior
    is consistent with existing markdown CI.

Out of scope (intentional)

Two evaluator golden files under scripts/aidlc-evaluator/test_cases/
still use the old format. They are excluded from the CI scope (same as
markdownlint's ignore list) and left untouched to keep this PR focused.

Test plan

  • Manual test on Claude Code (Linux): installed the rules from
    this branch into a fresh project per the README's "Claude Code —
    Option 1" instructions, then drove the workflow far enough to
    generate a clarifying-questions file. Opened it in PyCharm's
    Markdown preview
    (strict CommonMark) and confirmed each option
    renders on its own line. Before this fix, the same flow produces
    the collapsed-paragraph behaviour described in [Bug]: Question-format template renders as a single paragraph in strict CommonMark renderers (IntelliJ/PyCharm preview, etc.) #246.
  • Regression guard: the new CI step failed on main's content
    (38 offending option-line pairs across 5 files) and passes after
    the fixes in this PR.
  • No new lint regressions: markdownlint-cli2 continues to pass
    cleanly across 43 in-scope files locally.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

Consecutive `A) ... B) ...` option lines without a blank-line separator
collapse into a single paragraph in strict CommonMark renderers
(IntelliJ / PyCharm preview), because soft line breaks render as spaces.

- Add blank lines between options in the question-format template, its
  examples, and the four files that follow the template
  (session-continuity, security-baseline.opt-in,
  property-based-testing.opt-in, WORKING-WITH-AIDLC).
- Add CI step that fails when consecutive option lines lack a blank-line
  separator. Scope mirrors .markdownlint-cli2.yaml ignores.

Closes awslabs#246

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@gluefactory gluefactory requested review from a team as code owners May 18, 2026 08:29
@github-actions github-actions Bot added documentation Improvements or additions to documentation github rules labels May 18, 2026
Copy link
Copy Markdown
Contributor

@harmjeff harmjeff left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Clean fix for a real usability issue that hits users in the common case (IDE-driven workflows with strict CommonMark rendering).

Highlights:

  • Correct approach per CommonMark spec — blank lines between options is the proper way to ensure they render as separate lines
  • CI guard (awk regex check) is smart and scoped consistently with existing markdownlint ignores
  • Good decision to leave evaluator golden files out of scope to keep the PR focused
  • Thorough test plan (manual PyCharm verification + regression guard catching 38 existing offenders)

No concerns — approve.

Copy link
Copy Markdown

@mayakost mayakost left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation github rules

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Question-format template renders as a single paragraph in strict CommonMark renderers (IntelliJ/PyCharm preview, etc.)

3 participants