Markdown Audit: Complete CI/CD Scope Optimization Initiative

[ashleyshaw]

Markdown Audit & CI/CD Optimization Initiative

Status: In Progress (Phase 1 complete, Phase 2-3 planned)

Overview

Comprehensive audit of 9,024 markdown files across the repository identified significant CI/CD optimization opportunities. This epic tracks all three implementation phases to reduce linting scope by 38% (9,024 → 1,182 files) while improving signal quality and maintainability.

Audit Findings

Project Location: .github/projects/active/markdown-audit-ci-optimization/

Key Metrics

• Files analyzed: 9,024
• Files to exclude: ~3,400 (vendored + reports + projects)
• Linting scope reduction: 38% (achieved via Phase 1)
• Estimated CI time savings: 35-45%
• Implementation roadmap: 3 phases over 2+ months

Categories Identified

Category	Files	Frontmatter	CI Decision	Notes
A (Long-term docs)	754	84.2%	✅ Include	Strong adoption
B (Portable assets)	8,140	16.5%	⚠️ Selective	Phase 2-3 focus
C (Temporary)	1	100%	❌ Exclude	Minimal impact
D (Templates)	37	100%	✅ Include	Perfect adoption
E (Reports)	91	90.1%	❌ Exclude	Generated outputs
F (Release)	1	100%	✅ Include	Minimal impact

Critical Findings

🔴 CRITICAL: 90.2% of files are portable assets including ~21% vendored content

• 1,928+ plugin-provided/platform-managed files in agent directories
• Duplicate vendor files (figma/gotchas.md appears 4+ times)
• False positives from third-party documentation

🟡 HIGH: Inconsistent exclusion patterns between workflows

• testing.yml excludes differently than meta.yml
• Results in unreliable linting behavior

🔡 MEDIUM: Report files incorrectly included in CI linting

• 91 generated/audit outputs being linted
• Should be excluded as outputs, not sources

🔵 INFO: Frontmatter adoption disparity

• 100% in templates, 84% in docs, but only 16.5% in portable assets

Project Deliverables

All audit materials in develop branch at :

1. AUDIT_PROMPT.md — Reusable audit framework

   • 6-category taxonomy for markdown file classification
   • Discovery methodology
   • Can be used for quarterly audits

2. MARKDOWN_AUDIT_FINDINGS.md — Complete audit report

   • Detailed statistics for each category
   • Current CI/workflow configuration analysis
   • 5 key findings with evidence
   • Implementation roadmap

3. IMPLEMENTATION_GUIDE.md — Technical guidance

   • Step-by-step implementation instructions
   • Specific files to modify
   • Testing procedures
   • Verification checklist

Related Issues & PRs

• Research: research/markdown-audit-ci-optimization branch
• Audit Deliverables: PR #1223
• Phase 1 Implementation: PR #1226, ci/markdown-linting-scope-optimization

Child Issues

• #1224 — Phase 1: CI Configuration & Exclusion Patterns (build-ci)
• #1230 — Phase 2: Frontmatter Standardization for Portable Assets (feature)
• #1232 — Phase 3: Long-Term Standardization & Quarterly Audits (research)

---

Audit Date: 2026-07-24
Initiated By: Claude Code Agent
Effort Estimate: 2-3 months (all phases)

[linear-code]

LS-1776

[github-actions]

⚠️ This issue does not follow a required issue template.

Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)

The issue will remain open and flagged until the body is corrected.
Please update the issue with one of the official templates:

• https://github.com/lightspeedwp/.github/issues/new/choose

If this was opened by automation, update the automation to preserve the template sections before creating the issue.

[github-actions]

⏱️ Aging and SLA annotation

• Age: 12 day(s)
• SLA state: SLA risk
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-08-05T11:18:43.793Z

Maintained by project-meta-sync workflow.