Skip to content

docs: fix typos and inaccuracies in README, guides, and designreview prompts - #587

Open
Emillock wants to merge 4 commits into
awslabs:mainfrom
Emillock:fix/doc-typos
Open

docs: fix typos and inaccuracies in README, guides, and designreview prompts#587
Emillock wants to merge 4 commits into
awslabs:mainfrom
Emillock:fix/doc-typos

Conversation

@Emillock

@Emillock Emillock commented Jul 15, 2026

Copy link
Copy Markdown

Summary

Documentation-only fixes, per maintainer feedback: this PR now touches nothing under aidlc-rules/. It fixes typos and grammar in the README and contributor docs, corrects an outdated workflow count in the administrative guide, and repairs invalid markdown fences in the designreview prompt files. The rules-related findings from the original version of this PR are logged separately as #588, #589, #590, and #591.

Changes

  • README: rewrote the garbled OpenAI Codex verification step; fixed "as a directional best practices", "referred in it", and "Claude code" capitalization
  • CONTRIBUTING: "Powershell" changed to "PowerShell"
  • docs/DEVELOPERS_GUIDE: reworded the garbled GH_TOKEN setup line
  • docs/ADMINISTRATIVE_GUIDE: said six workflows exist; now documents all eight (ci.yml and codeql.yml added to the repo tree and permissions tables)
  • scripts/aidlc-designreview prompts: JSON output examples were closed with ```text, which is not a valid closing fence, so the Rules sections rendered inside the code block on GitHub

User experience

Before: several docs contained garbled sentences, the administrative guide undercounted the CI workflows, and the designreview prompt files rendered their Rules sections inside a code block.

After: docs read and render correctly. No files under aidlc-rules/ are touched.

Checklist

  • I have reviewed the contributing guidelines
  • I have performed a self-review of this change
  • Changes have been tested
  • Changes are documented

Test Plan

  • npx markdownlint-cli2 "**/*.md": 133 files, 0 errors
  • git diff main --stat: only README.md, CONTRIBUTING.md, docs/, and scripts/aidlc-designreview/config/prompts/ change; nothing under aidlc-rules/
  • View the three designreview prompt files on the branch: the Rules sections now render outside the JSON code blocks

Acknowledgment

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

@Emillock
Emillock requested review from a team as code owners July 15, 2026 20:16
@github-actions github-actions Bot added documentation Improvements or additions to documentation rules labels Jul 15, 2026
@scottschreckengaust scottschreckengaust added the do-not-merge Halts a pull request from merging label Jul 15, 2026
@Emillock Emillock changed the title Fix/doc typos docs: fix typos, stale stage names, and rendering issues across rules and docs Jul 15, 2026
@scottschreckengaust

Copy link
Copy Markdown
Member

Hi @Emillock thank you for your contribution! We triage based on GitHub issues and like to keep changes to rules even grammar managed closely. Would you consider sending a "documentation only" version separately outside of the rules and log others as bugs or suggestions? Thanks!

Emillock and others added 4 commits July 16, 2026 00:29
…ections

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…t files

The JSON output examples were closed with ```text, which is not a valid
closing fence (info strings are only allowed on opening fences), so the
Rules sections rendered inside the code block on GitHub.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The guide said six workflows, but eight exist. Add ci.yml (markdown lint)
and codeql.yml (CodeQL analysis) to the repo tree, CI/CD architecture
intro, and both permissions tables.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions github-actions Bot removed the rules label Jul 15, 2026
@Emillock Emillock changed the title docs: fix typos, stale stage names, and rendering issues across rules and docs docs: fix typos and inaccuracies in README, guides, and designreview prompts Jul 15, 2026
@Emillock

Copy link
Copy Markdown
Author

Hello @scottschreckengaust. Thanks for the guidance! I have reworked this PR in place to be the documentation-only version: it now touches only README.md, CONTRIBUTING.md, docs/, and the designreview prompt files, with nothing under aidlc-rules/. The title and description are updated to match.

The rules-related findings are logged as issues instead:

Each issue links to a reference branch on my fork in case that is useful during triage.

One scoping question: I kept the scripts/aidlc-designreview prompt-fence fix here since it is outside aidlc-rules/, but it is tool configuration rather than pure documentation. Happy to drop it from this PR and file it as an issue too if you would prefer.

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

Labels

do-not-merge Halts a pull request from merging documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants