Skip to content

Audit "Good" examples in remaining instruction modules #19

Description

@tablackburn

Context

PR #17 audited every "Good" code example in powershell.instructions.md against the file's own rules and found multiple internal-rule violations: non-descriptive variable names, unquoted string literal parameters, an unapproved verb, missing parameter validation, etc. Each Good example in an instruction module is itself authoritative — agents pattern-match on examples, so a violation in one teaches the wrong thing.

The same audit hasn't been done for the other instruction modules in this repo.

Request

Audit each remaining *.instructions.md file under instructions/ and instruction-templates/ for "Good" examples that violate the file's own rules (or the rules of any other applicable instruction module — e.g., shorthand, markdown):

  • markdown.instructions.md — check fenced-block examples for compliance with their own listed rules
  • github-cli.instructions.md — check shell snippets for parameter quoting, full flag names, etc.
  • testing.instructions.md — check any code examples
  • git-workflow.instructions.md — check command examples
  • shorthand.instructions.md — check that examples don't themselves use shorthand
  • agent-workflow.instructions.md, readme.instructions.md, releases.instructions.md, repository-specific.instructions.md, update.instructions.md, contributing.instructions.md — check for any code examples and validate

Why a separate issue

The PR #17 audit was already substantial; expanding to other modules would have ballooned the scope. Separate PR keeps blame and review tractable.

Acceptance criteria

  • Each Good example in each instruction module passes every applicable rule (the file's own + cross-cutting modules like shorthand)
  • Both instruction-templates/ and instructions/ mirror copies updated together (no sync drift introduced)
  • CHANGELOG entry under [Unreleased] describing the audit and listing changes per module
  • Follow PR docs: Add line continuation guidance to PowerShell instructions (v0.8.13) #17's commit pattern: one commit per module if the changes are substantial, otherwise grouped logically

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions