Summary

Writing-style convention violations from writing-style.instructions.md exist across documentation and README files. These predate the writing-style instructions and represent accumulated convention debt.

This issue is scoped to documentation files only: docs/, scripts/ READMEs, root markdown files, and extension/ markdown. Instruction files (.github/instructions/), prompt files (.github/prompts/), agent files (.github/agents/), and skill files (.github/skills/) are excluded from this issue.

Violation Categories

In-Scope Files

Highest-Debt Files

Excluded from Scope

The following file categories are intentionally excluded and may be addressed in separate issues:

• .github/instructions/*.instructions.md
• .github/agents/*.agent.md
• .github/prompts/*.prompt.md
• .github/skills/**/SKILL.md

Implementation Notes

• docs/getting-started/methods/ has the highest concentration of pseudo-heading violations because each method page uses **Bold:** lines instead of ### or #### headings.
• Em dash violations cluster in narrative documentation (docs/rpi/, docs/getting-started/).
• writing-style.instructions.md (L81-82) and prompt-builder.instructions.md (L385) contain intentional bad-pattern examples within rule definitions; these are not violations.

Recommended Approach

Batch remediation by file category in priority order:

1. docs/ files first (~16 files) — user-facing, highest visibility
2. Root files, extension/, and scripts/ READMEs (~8 files)

Consider adding automated validation to the linting pipeline to prevent regression.

Acceptance Criteria

• All bolded-prefix list items in docs/READMEs replaced with plain text, headings, or description lists
• All em dashes in docs/READMEs replaced with commas, colons, periods, or parentheses per writing-style.instructions.md
• All emphasis-only pseudo-headings in docs/READMEs replaced with proper ATX headings
• Automated linting rule added to prevent regression