docs: comprehensive documentation review and remediation#113
Open
scottschreckengaust wants to merge 4 commits intomainfrom
Open
docs: comprehensive documentation review and remediation#113scottschreckengaust wants to merge 4 commits intomainfrom
scottschreckengaust wants to merge 4 commits intomainfrom
Conversation
Addresses ~33 issues identified across the repository documentation, organized into 7 work streams covering correctness, consistency, completeness, and style. - Fix duplicate Step 1 heading in reverse-engineering.md; renumber Steps 1-13 sequentially - Fix incorrect loop-back reference in user-stories.md Step 18: "return to Step 14" -> "return to Step 15" (Load Story Generation Plan) - Fix broken cross-reference in process-overview.md: core-workflow.md (does not exist in rule-details/) -> welcome-message.md - Add .env to .gitignore to prevent accidental secret commit - Replace deprecated stage names across 6 files: "Context Assessment" -> "Workspace Detection", "Requirements Assessment" -> "Requirements Analysis", "Story Development" -> "User Stories", "Requirements Elaboration" -> "Requirements Analysis" - Fix systematic "phase" vs "stage" confusion in error-handling.md, workflow-changes.md, terminology.md, and units-generation.md (phase = INCEPTION/CONSTRUCTION/OPERATIONS; stage = individual workflow activities within a phase) - Resolve "Code Planning" ambiguity in terminology.md and workflow-planning.md: clarify Code Planning is Part 1 of the Code Generation stage, not a separate stage - Remove stale "Skip entire categories if not applicable" directives from application-design.md, infrastructure-design.md, nfr-design.md, and units-generation.md - Replace with proactive evaluation pattern modeled after requirements-analysis.md Step 5: evaluate ALL categories, determine applicability based on evidence, default to asking when in doubt - Add missing Windows PowerShell setup instructions for Kiro and Amazon Q sections (macOS/Linux and Windows CMD already existed) - Fix spelling: "Applicabality" -> "Applicability" - Remove trailing space from "Verify in Kiro IDE" heading - Add missing ToC entries: Version Control Recommendations, Security, License, Other Agents - Add extensions/ subdirectory to all 4 platform directory structure diagrams (Cursor, Cline, Claude Code, GitHub Copilot) - Fix Extension Directory Structure tree connector (└── -> ├── for baseline/ which has siblings) - Add .kiro/ and .amazonq/ rule-details paths to Version Control Recommendations - Separate Kiro and Amazon Q troubleshooting into distinct sections (/context show is Kiro-only) - Add ?raw=true to kiro-sdd-nudge.png image tag for consistency - Add TODO comments for Amplify URL replacement with stable URL - Add LICENSE hyperlink for consistency with CONTRIBUTING.md links - Replace Unicode box-drawing characters in welcome-message.md diagram with ASCII equivalents per ascii-diagram-standards.md - Standardize build-and-test.md completion message to use the REVIEW REQUIRED / WHAT'S NEXT template matching all other stages; also fixes extra double-quote on completion line - Fix incomplete sentence fragment in core-workflow.md line 475: rewrite as complete prohibition statement - Fix typos in codebuild.yml and buildspec.yml: "Kisk" -> "Disk", "Hardward" -> "Hardware" - Add buildspec.yml (CodeBuild build specification) - Add TODO near OWASP Top 10 (2025) mapping table in security-baseline.md to verify year against latest edition - Add TODO HTML comments near Amplify URLs in README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixes 5 issues identified during code review of the docs commit:
1. terminology.md: Update stale "Code Planning stage" references
- Line 13: "Code Planning stage" -> "Code Generation stage" in examples
- Line 18: "7 stages" -> "6 stages" (after merging Code Planning
into Code Generation)
- Line 19: "Code Planning stage" -> "Code Generation stage" in
usage example
2. README.md: Move TODO HTML comment above the markdown table to
prevent breaking GitHub-Flavored Markdown table rendering (comment
between header separator and first data row terminates the table)
3. core-workflow.md: Fix canonical stage name "NFR Requirements
Analysis" -> "NFR Requirements" to match usage elsewhere in the
same file (line 349: "NFR Requirements was executed")
4. Align dash style in overconfidence directives: change "--" to "-"
in application-design.md, units-generation.md, infrastructure-
design.md, nfr-design.md to match the canonical style in
overconfidence-prevention.md and 3 other files
5. Align contraction in overconfidence directives: change "It is
better" to "It's better" in the same 4 files to match the
canonical wording in overconfidence-prevention.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixes 7 issues identified during the pr-review-toolkit comprehensive review of the documentation remediation branch. 1. workflow-changes.md:88 - Remove stale "Code Planning" from the user warning message template. The restart impact warning now lists "Code Generation" as a single stage instead of the previous "Code Planning, Code Generation" pair. 2. error-handling.md:133,145 - Consolidate "Code Planning Errors" and "Code Generation Errors" section headings into "Code Generation Errors (Part 1: Code Planning)" and "Code Generation Errors (Part 2: Code Generation)" to align with the Code Planning/Code Generation stage merger applied everywhere else. 3. error-handling.md:48 - Fix "Cannot determine required phases" to "required stages". This appears in the Workspace Detection Errors section and refers to individual workflow stages, not the three lifecycle phases (INCEPTION/CONSTRUCTION/OPERATIONS). 4. build-and-test.md:345 - Fix "Log the phase completion" to "Log the stage completion". Build and Test is a stage within the CONSTRUCTION phase. This was newly added text in the previous commit. 5. build-and-test.md:326 - Add trailing two-space markdown line break to the REVIEW REQUIRED blockquote line, matching the pattern used in all other stage completion message templates (functional-design.md, nfr-design.md, infrastructure-design.md, code-generation.md, etc.). 6. security-baseline.md:312 - Strengthen the OWASP TODO comment from a simple "verify the year" note to a CRITICAL flag that the entire mapping table (category IDs, numbering, and names) needs verification against the actual published OWASP Top 10 standard (currently 2021 edition). The "2025" edition referenced in the table may not exist. 7. .gitignore - Add trailing newline for POSIX compliance. The file previously lacked a final newline, which can cause issues with some tools that expect POSIX text files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Revert CI/CD file changes that are out of scope for this documentation remediation PR: - Remove buildspec.yml (new file — should be tracked separately) - Revert codebuild.yml spelling fixes and sts identity command (infrastructure changes, not documentation) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
scottschreckengaust
force-pushed
the
docs/comprehensive-documentation-review-remediation
branch
from
d5af3ec to
fea6037
Compare
scottschreckengaust
requested review from
a team,
harmjeff,
raj-jain-aws and
spraja08
harmjeff
reviewed
Mar 25, 2026
harmjeff
approved these changes
Mar 25, 2026
Contributor
harmjeff
left a comment
harmjeff
left a comment
There was a problem hiding this comment.
Completed review and agree this is good
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation review and remediation addressing ~33 issues identified across the entire AI-DLC repository. Changes span 19 files covering rule detail files, core workflow, README, CI/CD configs, and extensions.
Reviewer Focus Areas
1. Overconfidence Directive Replacement (WS3) — behavioral change, needs careful review
The "Skip entire categories if not applicable" directive (identified as root cause of overconfidence in
overconfidence-prevention.md) was replaced with a proactive evaluation pattern: MANDATORY evaluation of ALL categories with evidence-based applicability determination. This is an intentional behavioral change to how the AI agent operates — shifting from selective questioning to comprehensive evaluation. Please verify:requirements-analysis.mdStep 5overconfidence-prevention.md2. Code Planning/Code Generation Consolidation (WS2.3) — structural terminology change
"Code Planning" and "Code Generation" are merged into a single "Code Generation" stage (Part 1: Planning, Part 2: Generation). This affects:
workflow-planning.mdterminology.md(7 → 6 CONSTRUCTION stages)error-handling.mdworkflow-changes.mdPlease verify this aligns with the implementation in
code-generation.md(the source of truth).3. "Phase" vs "Stage" Terminology Sweep (WS2.2) — high volume, judgment calls
Systematic replacement of "phase" with "stage" where individual workflow activities are meant. Phase is preserved where it correctly refers to INCEPTION/CONSTRUCTION/OPERATIONS. A few judgment calls were made:
error-handling.md:160— "Operations phase" kept as-is (correctly refers to lifecycle phase)error-handling.md:255— "across phases" kept as-is (refers to lifecycle phases)4. build-and-test.md Completion Message Reformat (WS5.2) — template change
The informal checkmark-style completion message was replaced with the standard
REVIEW REQUIRED/WHAT'S NEXTtemplate used by all other stages. Please verify:functional-design.md,nfr-design.md)5. OWASP Mapping Table Concern (WS7.1) — needs domain expertise
A strengthened TODO flags that the OWASP Top 10 "2025" mapping table may reference a non-existent edition (latest published is 2021). The category IDs and names need verification by someone with OWASP expertise.
6. README PowerShell Instructions (WS4.1) — platform-specific, needs Windows validation
New Windows PowerShell setup blocks were added between the existing macOS/Linux and Windows CMD blocks. These use
New-Item,Copy-Item, and$env:USERPROFILEsyntax. Would benefit from validation on an actual Windows machine.Lower-Risk Changes (spot-check sufficient)
reverse-engineering.mduser-stories.mdcore-workflow.md→welcome-message.mdprocess-overview.mdwelcome-message.mdascii-diagram-standards.mdcore-workflow.mdREADME.md,codebuild.yml,buildspec.yml.envto.gitignore.gitignoreextensions/to directory diagramsREADME.md(4 diagrams)README.mdREADME.md,security-baseline.mdREADME.mdREADME.md?raw=trueto image tagREADME.md.kiro/and.amazonq/to version control listREADME.mdTest Plan
grep -r "Context Assessment" aidlc-rules/returns 0 resultsgrep -r "Requirements Assessment" aidlc-rules/returns 0 resultsgrep -r "Story Development" aidlc-rules/returns 0 resultsgrep -r "Skip entire categories" aidlc-rules/returns onlyoverconfidence-prevention.mdreverse-engineering.mdare sequential 1-13.envappears in.gitignorewelcome-message.mdextensions/appears in all 4 README directory diagramserror-handling.mdandworkflow-changes.mdrequirements-analysis.mdpatternRelated Issues
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.
🤖 Generated with Claude Code