[AI Ops] Canonical Markdown Instructions Audit & Upgrade

[ashleyshaw]

🧠 AI Ops: Canonical Markdown Instructions Audit & Upgrade

Overview

Propose a comprehensive audit and refactor of markdown.instructions.md in the LightSpeedWP .github repository to meet highest standards for instruction files, following the 23-ai-ops.md template for clarity, maintainability, and Copilot/agent compatibility.

Problem Statement

The current markdown.instructions.md lacks:

• Clear canonical scope and precedence statement
• Explicit cross-references to related markdown instruction files and standards
• Summary table of markdown-related instruction files and their scope
• Direct references to accessibility requirements (WCAG, a11y)
• Expanded examples and validation criteria
• Contribution and review guidelines
• Consistent, branded footer with references, contact, and license

Proposed Solution

1. Add Canonical Scope & Precedence
   • State this file is the canonical markdown standard for LightSpeedWP.
   • Document how it interacts with other markdown instruction files (style guide, inline markdown, etc.)
2. Cross-Reference Related Instructions
   • Add links and context for markdown-style-guide.instructions.md, inline-markdown.instructions.md, docs.instructions.md, etc.
3. Add a Summary Table
   • Table listing related markdown instructions, their scope, and intended use.
4. Accessibility Requirements
   • Reference a11y.instructions.md and WCAG standards.
   • Specify required accessibility checks for markdown content.
5. Expand Examples & Validation Steps
   • Provide clear, expanded examples for headings, lists, tables, images, code blocks, and frontmatter.
   • List required validation steps for contributors and automation.
6. Contribution/Review Process
   • Document how to propose changes, review process, and escalation for conflicts.
7. Consistent Branded Footer
   • Add a footer per branding agent standards, with references, support, and license info.

Success Criteria

• markdown.instructions.md is the unambiguous canonical source for markdown standards in the repo
• Contributors and agents can easily find and apply related markdown rules
• Accessibility and validation requirements are explicit and actionable
• Issue management and review process are documented
• Footer is consistent, branded, and informative

References

• coding-standards.instructions.md
• markdown-style-guide.instructions.md
• inline-markdown.instructions.md
• a11y.instructions.md
• README.md
• custom-instructions.md

Metadata

• Type: Documentation
• Labels: documentation, standards, area:content, ai-ops, priority:important, status:triage
• Template: 23-ai-ops.md
• Tag: patch-markdown-instructions

---

For agent and Copilot compatibility:

• Use clear headings and short paragraphs
• Cross-link instructions for context
• List validation criteria and accessibility checks
• Add summary tables for related files
• Provide a markdown footer consistent with repo branding

Acceptance Criteria

• AI workflow/agent described
• Problem/opportunity scoped
• Success metric defined
• Documentation updated
• PR uses correct branch prefix (ai/)
• Approved by at least one maintainer

Additional Context

References

• Contribution Guidelines
• Branching Strategy
• Automation Governance
• PR Labels
• Saved Replies
• Project Meta
• Labeler Config
• Labels
• Issue Types

---

Definition of Ready (DoR)

• AI ops goal described
• Area/action mapped
• Acceptance criteria listed
• Estimate added

Definition of Done (DoD)

• All acceptance criteria met
• Solution/automation verified
• Documentation updated
• PR uses correct branch prefix (ai/)

---

Maintained by the 🧠 AI Ops and Automation team for LightSpeedWP. For questions, open a discussion or contact support@lightspeedwp.agency.

---

[ashleyshaw]

Closed by PR #523 (merged 2026-05-28).

.github/instructions/markdown.instructions.md upgraded to v1.1: added canonical scope and precedence statement with conflict-resolution rule; related-files summary table (6 files); expanded accessibility section to WCAG 2.2 AA with explicit required checks; added frontmatter standards section; expanded examples (tables, images with alt text, good/bad links, relative links, frontmatter); contribution/review process with escalation path; branded footer with GPL-3.0 licence and support contact.

---

Generated by Claude Code