diff --git a/.github/projects/active/AUDIT_PROMPT_README.md b/.github/projects/active/AUDIT_PROMPT_README.md new file mode 100644 index 000000000..d65c3a71d --- /dev/null +++ b/.github/projects/active/AUDIT_PROMPT_README.md @@ -0,0 +1,143 @@ +--- +title: "Documentation Audit Prompt - Quick Start" +description: "How to use the Comprehensive Documentation Audit Prompt to create GitHub issues" +version: "1.0.0" +created_date: "2026-05-31" +--- + +# 📋 Documentation Audit Prompt — Quick Start + +## What This Is + +A detailed, structured prompt document designed to help you create GitHub issues for systematically auditing and fixing the `.github` repository's documentation, templates, and automation systems. + +## Problem It Solves + +- **Issue labeling system isn't working** (but PR labeling is) +- **Documentation is scattered** across 40+ files with duplication +- **AI agents don't have clear instructions** on how to create well-formed issues +- **File organization doesn't match** the planned structure in CLAUDE.md +- **44 README files need updating** with accessible Mermaid diagrams + +## The Prompt Document + +**Location:** `.github/projects/active/DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md` + +**Contains:** +- Problem statement and root causes +- 5 parent issues (full descriptions ready to copy) +- ~25 child issues (templates for customization) +- Instructions for creating issues via GitHub UI or CLI +- Success criteria and next steps + +## How to Use It + +### Option 1: Create Issues via GitHub UI (Easiest) + +1. Open `.github/projects/active/DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md` +2. Go to each "Parent Issue" section +3. Copy the description and metadata +4. Create new GitHub issue in the repository +5. Paste description into issue body +6. Repeat for all child issues +7. Link parent ↔ child issues using GitHub's linking feature + +### Option 2: Create Issues via GitHub CLI + +```bash +# Example: create parent issue 1 +gh issue create \ + --title "[Audit] Issue Templates, Automation, & AI Agent Integration" \ + --body-file parent-1.md \ + --label "type:audit,area:automation,priority:important" \ + --assignee @ashley + +# Repeat for each issue +``` + +### Option 3: Use a Script + +If creating 30+ issues manually is tedious, create a simple script to parse the prompt document and batch-create issues via the GitHub API. + +## Issue Structure + +``` +Parent Issue #NNN +├── Child Issue #NNN.1 — specific component audit +├── Child Issue #NNN.2 — related audit +├── Child Issue #NNN.3 — findings consolidation +└── Child Issue #NNN.4 — implementation plan +``` + +Each child issue references its parent. Parent issue tracks all children. + +## What Each Issue Does + +### Parent Issues (Strategic Audits) + +1. **Issue Templates & Automation** — Why don't issue templates trigger labeling like PR templates do? +2. **Canonical Configs** — Are labels.yml, issue-types.yml, issue-fields.yml complete and consistent? +3. **Documentation Consolidation** — Where is duplication and what can be merged? +4. **README & Mermaid Diagrams** — Are 44 READMEs accessible and up-to-date? +5. **File Organization** — Does current structure match CLAUDE.md boundaries? + +### Child Issues (Detailed Investigations) + +Each parent has 4-5 child issues that: +- Focus on a specific component or area +- Provide detailed audit checklists +- Specify deliverables (reports, recommendations) +- Point to relevant files +- Enable parallel investigation + +## Expected Outcomes + +Once all audits are complete, you'll have: + +✅ Clear understanding of why issue automation doesn't work +✅ Mapping of templates → automation triggers → labeling rules +✅ Consolidated documentation plan (reduce 40+ files to core essentials) +✅ Audit of 44 README files with accessibility fixes +✅ File organization plan aligned with CLAUDE.md + +This clarity will guide the next implementation wave to fix the system. + +## Timeline + +- **Week 1:** Create all 30 issues +- **Week 2-3:** Execute audits (gather findings, document issues) +- **Week 4:** Review findings, consolidate recommendations +- **Week 5+:** Execute implementations based on audit outcomes + +## Next Steps + +1. ✅ **You're here** — Read this README +2. **Create issues** — Use the prompt document to create GitHub issues +3. **Execute audits** — Team investigates and documents findings +4. **Consolidate** — Review audit outputs and create implementation plan +5. **Implement** — Fix templates, configs, documentation based on findings +6. **Validate** — Verify issue automation works correctly + +## Key Files to Reference + +While creating and executing audits, reference these source documents: + +- `CLAUDE.md` — Repository structure and boundaries (source of truth) +- `docs/LABEL_STRATEGY.md` — Label philosophy and color strategy +- `docs/AUTOMATION_GOVERNANCE.md` — Automation standards +- `.github/labels.yml` — All canonical labels +- `.github/issue-types.yml` — All canonical issue types +- `.github/labeler.yml` — Automation rules (shows PR rules, helps identify gaps for issues) + +## Questions or Issues? + +If while creating issues you realize something needs adjustment: +- Add notes to the issue being created +- Update this README with clarifications +- Check `next-issues-execution-plan.md` for related context + +--- + +**Status:** ✅ Ready to use +**Last Updated:** 2026-05-31 +**Maintained by:** LightSpeed Team diff --git a/.github/projects/active/DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md b/.github/projects/active/DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md new file mode 100644 index 000000000..11f47d077 --- /dev/null +++ b/.github/projects/active/DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md @@ -0,0 +1,757 @@ +--- +file_type: "planning-document" +title: "Comprehensive Documentation & Automation Audit Prompt" +description: "Detailed step-by-step prompt for creating GitHub issues to audit and fix documentation, templates, labeling, and automation systems" +version: "1.0.0" +created_date: "2026-05-31" +last_updated: "2026-05-31" +status: "ready-for-execution" +owner: "LightSpeed Team" +--- + +# Comprehensive Documentation & Automation Audit Prompt + +**Purpose:** This document provides a detailed, step-by-step prompt for creating GitHub issues that will audit, fix, and consolidate all documentation, templates, canonical configurations, and automation systems in the LightSpeed `.github` repository. + +**Goal:** Clear, correct, and complete documentation will guide the next steps for fixing the automated labeling system and ensuring AI agents can properly create issues that trigger correct automation. + +**Status:** Ready for execution. Use this to create parent issues and child issues in GitHub. + +--- + +## Part 1: Overview & Problem Statement + +### Current State +- **Issue labeling system:** Broken or inconsistent (PR labeling works fine) +- **Documentation:** Scattered across 40+ files with duplication and overlap +- **Templates:** Issue, PR, and Discussion templates exist but AI agents don't consistently use them +- **File organization:** Misalignment between planned structure and current state +- **README files:** 44 files across the repo with outdated or missing Mermaid diagrams +- **Canonical configs:** `labels.yml`, `labeler.yml`, `issue-types.yml`, `issue-fields.yml` exist but may be incomplete/inconsistent + +### Root Causes +1. Templates are not well-documented in relation to how they trigger automation +2. Labeling rules in `labeler.yml` don't cover issue scenarios (only PR/branch scenarios) +3. Documentation doesn't clearly explain HOW an AI agent should structure an issue to trigger proper automation +4. File organization doesn't follow the planned structure outlined in CLAUDE.md +5. README files are outdated and lack Mermaid diagrams for accessibility + +### Expected Outcome +Once these audits are complete: +- Documentation will clearly explain the entire issue/PR/automation flow +- Templates will be consolidated and deduplicated +- Canonical configs will be verified and updated for consistency +- File organization will match CLAUDE.md boundaries +- README files will have accessible Mermaid diagrams +- AI agents will have clear instructions for creating properly-formatted issues + +--- + +## Part 2: Parent Issues Structure + +Create the following **parent issues** in GitHub. Each parent issue will have multiple child issues attached. + +### Parent Issue 1: Issue Templates & Automation Integration Audit +**Title:** `[Audit] Issue Templates, Automation, & AI Agent Integration` +**Type:** `type:audit` +**Area:** `area:automation`, `area:labels` +**Priority:** `priority:important` +**Status:** `status:needs-triage` +**Effort:** `M` (Medium) + +**Description:** +```markdown +## Overview + +Comprehensive audit of issue templates, their relationship to the automated labeling system, +and how AI agents should create issues to trigger proper automation. + +## Current Problems + +1. Issue templates exist (.github/ISSUE_TEMPLATE/*.md) but don't consistently trigger automation +2. PR templates work well, but issue templates don't map clearly to labeling rules +3. `labeler.yml` has rules for PRs and branches, but minimal rules for issues +4. AI agents don't have clear instructions on how to structure issues for automation + +## Areas to Audit + +See child issues for detailed audits of: +- Issue template inventory and standardization +- Mapping between templates and automation triggers +- Missing automation rules in labeler.yml for issue types +- AI agent instructions for issue creation + +## Acceptance Criteria + +- [ ] All issue templates audited and categorized +- [ ] Clear mapping between template usage and automation triggers +- [ ] Labeler.yml rules for issues identified and documented +- [ ] AI agent instructions for issue creation updated + +## Related Files + +- `.github/ISSUE_TEMPLATE/` (all files) +- `.github/ISSUE_TEMPLATE/config.yml` +- `.github/ISSUE_TEMPLATE/README.md` +- `.github/labeler.yml` (issue rules section) +- `.github/issue-types.yml` +- `docs/ISSUE_CREATION_GUIDE.md` +- `.github/custom-instructions.md` +``` + +--- + +### Parent Issue 2: Canonical Configuration Files Audit & Standardization +**Title:** `[Audit] Canonical Config Files (labels, issue-types, issue-fields)` +**Type:** `type:audit` +**Area:** `area:labels`, `area:automation` +**Priority:** `priority:important` +**Status:** `status:needs-triage` +**Effort:** `L` (Large) + +**Description:** +```markdown +## Overview + +Comprehensive audit of canonical configuration files that define labels, issue types, +issue fields, and how they relate to each other. + +## Current Problems + +1. `labels.yml` has 200+ labels but many are grey and don't follow the color strategy +2. `issue-types.yml` defines 26 issue types but mapping to templates is unclear +3. `issue-fields.yml` defines custom fields but their usage in templates is unclear +4. No clear documentation on how these files work together or how to extend them +5. Inconsistencies between canonical files and documentation + +## Areas to Audit + +See child issues for detailed audits of: +- Label color consistency and family grouping +- Issue type mapping and template correlation +- Issue fields configuration and GitHub API alignment +- Relationship and interdependencies between config files +- Missing or unused labels/types + +## Acceptance Criteria + +- [ ] All labels verified against color strategy +- [ ] Issue type definitions aligned with templates +- [ ] Issue fields configuration validated +- [ ] All interdependencies documented +- [ ] Deprecations and removals identified + +## Related Files + +- `.github/labels.yml` +- `.github/labeler.yml` +- `.github/issue-types.yml` +- `.github/issue-fields.yml` +- `docs/LABEL_STRATEGY.md` +- `docs/ISSUE_LABELS.md` +- `docs/ISSUE_TYPES.md` +- `docs/ISSUE-FIELDS.md` +``` + +--- + +### Parent Issue 3: Documentation Consolidation & Deduplication +**Title:** `[Audit] Documentation Consolidation - Reduce Duplication Across Docs` +**Type:** `type:audit` +**Area:** `area:documentation` +**Priority:** `priority:important` +**Status:** `status:needs-triage` +**Effort:** `XL` (Extra Large) + +**Description:** +```markdown +## Overview + +Audit of 40+ documentation files across `docs/` to identify duplication, +overlap, and opportunities for consolidation. + +## Current Problems + +1. Multiple files document similar topics (e.g., 3-4 files on PR creation) +2. Files reference each other with inconsistent linking patterns +3. Some documentation is in `docs/`, some in `.github/`, some in `instructions/` +4. Duplication makes updates difficult and creates sync/consistency issues +5. Documentation index (`docs/index.md`) is incomplete or outdated + +## Areas to Audit + +See child issues for detailed audits of: +- Issue creation documentation (4+ files involved) +- PR creation documentation (3+ files involved) +- Labeling documentation (3+ files involved) +- Automation governance documentation (2+ files involved) +- File organization and folder structure alignment +- Documentation index and cross-referencing + +## Acceptance Criteria + +- [ ] All docs audited and duplication mapped +- [ ] Consolidation strategy created +- [ ] Obsolete files identified for archival +- [ ] Updated cross-reference links documented + +## Related Files + +- `docs/` (all .md files) +- `docs/index.md` +- `.github/README.md` +- README.md (root) +- Various .instructions.md files in instructions/ +``` + +--- + +### Parent Issue 4: README & Mermaid Diagram Audit (Accessibility & Freshness) +**Title:** `[Audit] 44 README Files - Mermaid Diagrams & Accessibility Review` +**Type:** `type:audit` +**Area:** `area:documentation`, `area:a11y` +**Priority:** `priority:normal` +**Status:** `status:needs-triage` +**Effort:** `XL` (Extra Large) + +**Description:** +```markdown +## Overview + +Comprehensive audit of 44 README.md files across the repository to verify +Mermaid diagram syntax, accessibility compliance, and content freshness. + +## Current Problems + +1. Mermaid diagrams may have syntax errors or be outdated +2. Diagrams may lack accessibility attributes (accTitle, accDescr) +3. Diagrams may not work in light/dark mode +4. README content may be outdated or incomplete +5. No systematic way to verify diagram accessibility compliance + +## Areas to Audit + +See child issues for detailed audits of: +- Root & core README files (6 files) +- Feature folder README files (12 files) +- Sub-folder README files (20 files) +- Test/config README files (6 files) +- Mermaid diagram syntax validation +- Accessibility compliance (WCAG AA) +- Light/dark mode rendering + +## Acceptance Criteria + +- [ ] All 44 README files inventoried +- [ ] Mermaid diagram syntax validated +- [ ] Accessibility attributes added where needed +- [ ] Content freshness verified and updated +- [ ] Audit report generated + +## Related Files + +All README.md files across the repository (see audit report for inventory) + +## Related Issues + +- #512 (Wave 3A: README & Mermaid Diagram Discovery & Audit) +- #513 (Wave 3B: README & Mermaid Diagram Repair & Update) +``` + +--- + +### Parent Issue 5: File Organization & Structure Alignment with CLAUDE.md +**Title:** `[Audit] File Organization - Align with CLAUDE.md Repository Boundaries` +**Type:** `type:audit` +**Area:** `area:core` +**Priority:** `priority:normal` +**Status:** `status:needs-triage` +**Effort:** `L` (Large) + +**Description:** +```markdown +## Overview + +Audit current file organization against the planned structure defined in CLAUDE.md +and identify misalignments requiring refactoring. + +## Current Problems + +1. `.github/agents/` still exists but agents moved to `/agents` in root +2. `.github/scripts/` exists but scripts moved to `/scripts` in root +3. `.github/schemas/` exists but should be `/schema` or `/schemas` in root +4. Documentation in both `docs/` and `.github/docs/` +5. Uncertainty about which folders are reusable vs. GitHub-native + +## Areas to Audit + +See child issues for detailed audits of: +- `.github/` contents vs. root-level portable assets +- Agent file locations and migration status +- Script file locations and migration status +- Schema/config file locations +- Documentation folder organization +- Workflows folder structure +- Instructions folder organization + +## Acceptance Criteria + +- [ ] Current state mapped against CLAUDE.md +- [ ] All misalignments documented +- [ ] Migration plan for files created +- [ ] Impact assessment completed + +## Related Files + +- `CLAUDE.md` (source of truth) +- `.github/` (all folders) +- `agents/` +- `scripts/` +- `schema/` or `schemas/` +- `workflows/` +- `instructions/` +``` + +--- + +## Part 3: Child Issues Template + +For each parent issue above, create the following child issues using this template. Replace `[PARENT]` with the parent issue number and customize titles/descriptions. + +### Child Issue Template: Specific Component Audit + +**Title:** `[Child of #PARENT] Audit: [Specific Component/Area]` +**Type:** `type:audit` +**Area:** `area:automation` or `area:documentation` (as appropriate) +**Priority:** `priority:normal` or `priority:important` +**Status:** `status:needs-triage` +**Effort:** `S` to `M` (Small to Medium, adjust per scope) +**Parent Issue:** `#PARENT` + +**Description:** +```markdown +## Overview + +[Brief description of what this child issue audits] + +## Scope + +- [Specific file/folder/component] +- [Related configuration or documentation] +- [Expected outcome] + +## Audit Checklist + +- [ ] [Specific check 1] +- [ ] [Specific check 2] +- [ ] [Specific check 3] + +## Deliverables + +- Audit report (as issue comment with findings) +- List of identified issues +- Recommendations for fixes +- (Optional) Create follow-up issues for fixes + +## Related Files + +- [Link to relevant files] + +## References + +- [Links to related documentation] +``` + +--- + +## Part 4: Specific Child Issues to Create + +### Under Parent Issue 1: Issue Templates & Automation + +#### Child 1.1: Audit Issue Template Inventory +**Title:** `[Child of #] Audit: Issue Template Inventory & Standardization` + +- Inventory all `.md` files in `.github/ISSUE_TEMPLATE/` +- Check if each template has required frontmatter +- Verify each template's relationship to an issue type in `issue-types.yml` +- Document which templates are actively used vs. deprecated +- Check config.yml for completeness + +**Deliverable:** Spreadsheet showing: Template Name | Issue Type | Status | Last Updated | Used? | Notes + +--- + +#### Child 1.2: Audit Issue Template to Automation Trigger Mapping +**Title:** `[Child of #] Audit: Issue Template → Automation Trigger Mapping` + +- For each issue template, document what automation should trigger +- Check if issue templates set up frontmatter that triggers labeling +- Compare with PR templates to understand the gap +- Identify missing automation rules in `labeler.yml` for issue scenarios +- Document how AI agents should structure issues for proper automation + +**Deliverable:** Mapping document showing Template → Expected Automation → Current Status → Missing Pieces + +--- + +#### Child 1.3: Audit Issue Labeling Rules in labeler.yml +**Title:** `[Child of #] Audit: Issue Labeling Rules in labeler.yml` + +- Review `.github/labeler.yml` for issue-specific rules +- Compare coverage between PR rules and issue rules +- Identify gaps (e.g., file path-based rules for issues) +- Document current issue detection heuristics +- Check if content/title-based rules exist for issues + +**Deliverable:** Report of current issue rules, gaps, and recommendations + +--- + +#### Child 1.4: Create AI Agent Instructions for Issue Creation +**Title:** `[Child of #] Implement: Clear AI Agent Instructions for Issue Creation` + +- Write clear, step-by-step instructions for how AI agents should create issues +- Include template selection guidelines +- Include frontmatter structure for issue automation +- Include label assignment strategy +- Include examples of well-formed issues + +**Deliverable:** New or updated `.github/custom-instructions.md` section for AI agents on issue creation + +--- + +### Under Parent Issue 2: Canonical Configuration Files + +#### Child 2.1: Audit labels.yml Color Consistency +**Title:** `[Child of #] Audit: labels.yml Color Consistency & Strategy Alignment` + +- Review all 200+ labels in `labels.yml` +- Check if each label's color matches the documented strategy +- Identify grey labels that should have family colors +- Verify color hex codes are valid +- Document color family assignments (status, priority, type, area, etc.) + +**Deliverable:** Report showing: Label Name | Current Color | Expected Color | Family | Status + +--- + +#### Child 2.2: Audit Issue Types Mapping +**Title:** `[Child of #] Audit: Issue Types Alignment with Templates & Labels` + +- Review all issue types in `issue-types.yml` +- Verify each type has a matching issue template +- Verify each type has a matching label in `labels.yml` +- Check if type colors match label colors +- Identify unused types or orphaned templates + +**Deliverable:** Mapping table: Issue Type | Template | Label | Color Match | Status + +--- + +#### Child 2.3: Audit Issue Fields Configuration +**Title:** `[Child of #] Audit: Issue Fields Configuration vs. GitHub API` + +- Review `issue-fields.yml` configuration +- Verify custom fields are properly defined +- Check field mappings to GitHub API +- Verify field values match what GitHub supports +- Test field creation/update via automation + +**Deliverable:** Validation report with test results and recommended fixes + +--- + +#### Child 2.4: Document Config File Relationships +**Title:** `[Child of #] Document: Canonical Config File Interdependencies` + +- Create comprehensive diagram showing how labels.yml, issue-types.yml, labeler.yml, and issue-fields.yml relate +- Document the flow from issue creation → template selection → type assignment → label application → field population +- Identify all dependencies and relationships +- Document which tools/agents use which configs + +**Deliverable:** Relationship diagram (Mermaid) + documentation in new file `docs/CANONICAL_CONFIGS_GUIDE.md` + +--- + +### Under Parent Issue 3: Documentation Consolidation + +#### Child 3.1: Audit Issue Creation Documentation +**Title:** `[Child of #] Audit: Issue Creation Docs - Consolidate Overlapping Files` + +- Review all files related to issue creation: + - `docs/ISSUE_CREATION_GUIDE.md` + - `docs/ISSUE_LABELS.md` + - `docs/ISSUE_TYPES.md` + - `.github/ISSUE_TEMPLATE/README.md` + - `docs/index.md` (if references issues) + - `instructions/issues.instructions.md` +- Identify duplication and overlap +- Propose consolidation strategy +- Document which information should live where + +**Deliverable:** Consolidation matrix showing current location, content, and proposed new location + +--- + +#### Child 3.2: Audit PR Creation Documentation +**Title:** `[Child of #] Audit: PR Creation Docs - Consolidate Overlapping Files` + +- Review all files related to PR creation: + - `docs/PR_CREATION_PROCESS.md` + - `docs/PR_LABELS.md` + - `.github/PULL_REQUEST_TEMPLATE/README.md` + - `instructions/pull-requests.instructions.md` + - `docs/BRANCHING_STRATEGY.md` +- Identify duplication and overlap +- Propose consolidation strategy + +**Deliverable:** Consolidation matrix + +--- + +#### Child 3.3: Audit Labeling Documentation +**Title:** `[Child of #] Audit: Labeling Docs - Consolidate Overlapping Files` + +- Review all files related to labeling: + - `docs/LABEL_STRATEGY.md` + - `docs/LABELING.md` + - `docs/ISSUE_LABELS.md` + - `docs/PR_LABELS.md` + - `docs/AUTOMATION_GOVERNANCE.md` (label section) + - Agent specs for labeling +- Identify duplication and overlap +- Propose single source of truth for labeling + +**Deliverable:** Consolidation matrix + proposed new structure + +--- + +#### Child 3.4: Audit File Organization Alignment +**Title:** `[Child of #] Audit: Documentation Folder Structure vs. CLAUDE.md Boundaries` + +- Review `.github/`, `docs/`, `instructions/` folder structure +- Compare against CLAUDE.md guidance for where documentation should live +- Identify misplaced files +- Propose reorganization plan + +**Deliverable:** Reorganization plan with source → destination mapping + +--- + +#### Child 3.5: Update Documentation Index +**Title:** `[Child of #] Update: Documentation Index (docs/index.md) - Complete & Current` + +- Review current `docs/index.md` +- Add/update all documentation files +- Organize by topic (issue creation, PR creation, labeling, automation, etc.) +- Add brief description for each file +- Add link to related template/config files + +**Deliverable:** Updated `docs/index.md` with complete inventory and organization + +--- + +### Under Parent Issue 4: README & Mermaid Diagrams + +#### Child 4.1: Discover & Audit All README Files +**Title:** `[Child of #] Audit: Discover All 44 README.md Files - Inventory` + +- Use script or manual inspection to find all README.md files +- Create inventory spreadsheet with location, size, last updated, mermaid diagrams present +- Categorize by: Root/Core, Feature folders, Sub-folders, Test/Config +- Check each README for broken links, outdated content +- Identify which ones have Mermaid diagrams + +**Deliverable:** Spreadsheet/CSV showing all 44 READMEs with metadata and issues found + +--- + +#### Child 4.2: Validate Mermaid Diagram Syntax +**Title:** `[Child of #] Audit: Validate Mermaid Syntax in All Diagrams` + +- For each README with Mermaid diagrams, validate syntax +- Check for parse errors +- Verify diagram type support +- Test rendering in Mermaid Live +- Document errors and required fixes + +**Deliverable:** Report showing which diagrams have syntax errors and specific fixes needed + +--- + +#### Child 4.3: Audit Mermaid Accessibility Compliance +**Title:** `[Child of #] Audit: Mermaid Diagram Accessibility (WCAG AA, Light/Dark Mode)` + +- For each Mermaid diagram, check for accessibility attributes: + - `accTitle` (accessible title) + - `accDescr` (accessible description) +- Test diagrams in light and dark mode +- Verify color contrast (WCAG AA standards) +- Document which diagrams need accessibility improvements + +**Deliverable:** Accessibility audit report with fixes for each diagram + +--- + +#### Child 4.4: Update README Content & Diagrams +**Title:** `[Child of #] Update: Fix & Refresh 44 README Files with Current Information` + +This is the implementation phase following audits: +- Update outdated content +- Fix broken links +- Add/update Mermaid diagrams with proper accessibility +- Ensure consistent formatting across all READMEs +- Add brief descriptions of folder/file purpose + +**Deliverable:** All 44 READMEs updated with current information and accessible diagrams + +--- + +### Under Parent Issue 5: File Organization Alignment + +#### Child 5.1: Audit Current vs. Planned File Organization +**Title:** `[Child of #] Audit: Current File Organization vs. CLAUDE.md Boundaries` + +- Map current structure of `.github/`, root folders, etc. +- Compare against CLAUDE.md definitions for reusable vs. GitHub-native assets +- Identify misplacements +- Document what's in the wrong place + +**Deliverable:** Mapping document showing Current Location | Expected Location (per CLAUDE.md) | Status + +--- + +#### Child 5.2: Audit Agent & Script File Locations +**Title:** `[Child of #] Audit: Agent & Script Files - Migration Status` + +- Check if `.github/agents/` still exists (should have moved to `/agents`) +- Check if `.github/scripts/` exists (should have moved to `/scripts`) +- Verify what remains in `.github/` vs. what's in root folders +- Document migration status for each file + +**Deliverable:** Migration status report + +--- + +#### Child 5.3: Create File Organization & Migration Plan +**Title:** `[Child of #] Plan: File Organization Refactoring - Migration & Validation` + +- Create detailed plan for reorganizing files to match CLAUDE.md +- Include impact assessment (what breaks if we move X?) +- Include validation checklist (how to verify moves worked?) +- Include rollback plan (how to recover if something goes wrong?) +- Create implementation timeline + +**Deliverable:** Detailed migration plan with checklists and timeline + +--- + +## Part 5: Issue Creation Instructions + +### How to Use This Prompt + +1. **Create Parent Issues First:** + - Copy each "Parent Issue" section above + - Use the template provided (Title, Type, Area, etc.) + - Paste the description into GitHub issue body + - Leave the "Child Issues" section for later + +2. **Create Child Issues:** + - For each parent issue, copy the relevant child issue sections + - Create each child issue in GitHub + - In the child issue body, add: `**Parent Issue:** #PARENT_NUMBER` + - Use GitHub issue linking to link parent ↔ child + +3. **Linking Parent & Child Issues:** + - Use GitHub's parent issue feature (if available) + - Or add explicit link in both issues: "**Parent:** #NNN" and "**Child:** #MMM" + +4. **Automation & Labels:** + - Let the automated labeling system assign labels + - Don't manually force labels; trust the automation + - If automation doesn't work, that's evidence to debug! + +5. **Tracking & Execution:** + - Update the active projects file as issues are created + - Track progress by marking issues as "In Progress" → "Complete" + - Review each audit before moving to implementation + +### Command-Line Approach (Using GitHub CLI) + +If you prefer to create all issues via CLI: + +```bash +# Create parent issue 1 +gh issue create \ + --title "[Audit] Issue Templates, Automation, & AI Agent Integration" \ + --body-file issue-1-parent.md \ + --label "type:audit,area:automation,area:labels,priority:important" \ + --milestone "Documentation Audit Sprint" + +# Create child issue 1.1 +gh issue create \ + --title "[Child] Audit: Issue Template Inventory & Standardization" \ + --body-file issue-1-1-child.md \ + --label "type:audit,area:documentation,priority:normal" \ + --milestone "Documentation Audit Sprint" +``` + +--- + +## Part 6: Success Criteria & Next Steps + +### Success Criteria for This Audit Phase +- [ ] All 5 parent issues created in GitHub +- [ ] All ~25 child issues created in GitHub +- [ ] All parent/child relationships linked +- [ ] Audit issues assigned to appropriate team members +- [ ] Active projects file updated with issue references + +### Next Steps (After Audits Complete) +1. Review audit findings and consolidate into implementation plan +2. Create implementation issues based on audit recommendations +3. Execute implementations in waves (following existing pattern) +4. Update templates, configs, documentation based on findings +5. Verify automated labeling system works for issues +6. Document the complete flow for AI agents + +--- + +## Part 7: Related Context + +### Existing Related Issues +- #512 — Wave 3A: README & Mermaid Diagram Discovery & Audit +- #513 — Wave 3B: README & Mermaid Diagram Repair & Update +- #519 — Documentation Index & Quickstart Guide (merged) + +### Existing Active Project Files +- `next-issues-execution-plan.md` (update with new audit issues) +- `launch-agents-checklist.md` (track testing of new automation) + +### Key Documentation Files (Source of Truth) +- `CLAUDE.md` — Repository boundaries and structure +- `docs/LABEL_STRATEGY.md` — Label philosophy and strategy +- `docs/AUTOMATION_GOVERNANCE.md` — Automation standards +- `.github/labels.yml` — Canonical label definitions +- `.github/issue-types.yml` — Canonical issue type definitions + +--- + +## Part 8: Execution Timeline + +### Proposed Wave Timeline +- **Week 1:** Create all audit issues (parent + child) +- **Week 2-3:** Execute audits (investigations, gather findings) +- **Week 4:** Review audit findings, consolidate recommendations +- **Week 5+:** Execute implementations based on audit outcomes + +### Checkpoints +- After issue creation: Verify all issues linked correctly +- After each audit: Review findings and document in issue comments +- Before implementation: Consolidate all findings into implementation plan + +--- + +**Document Status:** ✅ Ready for execution + +**Next Action:** Use the structures and templates above to create GitHub issues. Share issue numbers and update this document once created. diff --git a/.github/projects/active/next-issues-execution-plan.md b/.github/projects/active/next-issues-execution-plan.md index 1d65ab382..a537b4f8d 100644 --- a/.github/projects/active/next-issues-execution-plan.md +++ b/.github/projects/active/next-issues-execution-plan.md @@ -516,3 +516,48 @@ Archival checklist per file: 4. Update this roadmap file with archival record --- + +--- + +## Wave 5 — Documentation & Automation Audit (🆕 PROPOSED) + +**Objective**: Systematically audit all documentation, templates, and canonical configurations to identify gaps in the issue automation system and consolidate duplicated documentation. + +**Status**: Proposed — audit prompt created, ready for GitHub issue creation + +**Scope**: +- 5 parent audit issues +- ~25 child audit issues +- Covers: templates, canonical configs, documentation, README files, file organization + +**Execution Plan**: +- Use prompt document: `.github/projects/active/DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md` +- Create all issues from prompt +- Track progress in active projects folder +- Consolidate findings into implementation wave + +**Why This Matters**: +- Issue labeling automation isn't working (PR labeling works fine) +- Root cause likely in how templates/configs relate or how AI agents create issues +- Clear documentation will guide all future automation fixes + +**Key Deliverables**: +1. Issue template audit & standardization recommendations +2. Canonical config validation (labels, issue-types, issue-fields) +3. Documentation consolidation & deduplication plan +4. README & Mermaid diagram accessibility audit + fixes +5. File organization alignment with CLAUDE.md + +**Estimated Effort**: 15-20 hours of investigation + implementation + +**Owner**: Claude Code (investigation phase), then implementation team + +**Next Action**: +1. Review `DOCUMENTATION_AUDIT_PROMPT_COMPREHENSIVE.md` +2. Create GitHub issues from prompt structure +3. Assign to team members +4. Execute audits and gather findings +5. Consolidate recommendations into implementation plan + +--- + diff --git a/.github/projects/active/wave-5-documentation-audit/INDEX.md b/.github/projects/active/wave-5-documentation-audit/INDEX.md new file mode 100644 index 000000000..20f0b5fe2 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/INDEX.md @@ -0,0 +1,190 @@ +--- +title: "Wave 5 Documentation Audit - Issue Index" +description: "Complete index of all parent and child issues for the Documentation Audit project" +version: "1.0.0" +created_date: "2026-05-31" +status: "ready-for-review" +--- + +# Wave 5 Documentation Audit — Issue Index + +This directory contains all parent and child issues for the comprehensive documentation audit initiative. **GitHub issues have been created (#649–#673) and are ready for execution.** + +## 📋 How to Use This Directory + +1. **Review issue files** to understand the scope and requirements for each audit +2. **Check reference links** to navigate to related documentation and configuration files +3. **Track progress** by updating issue status in GitHub and referencing these files +4. **Access full details** by opening the corresponding GitHub issue (links in table below) + +--- + +## 📁 Directory Structure + +``` +wave-5-documentation-audit/ +├── INDEX.md (this file) +├── parents/ +│ ├── 01-issue-templates-automation-audit.md +│ ├── 02-canonical-configs-audit.md +│ ├── 03-documentation-consolidation-audit.md +│ ├── 04-readme-mermaid-audit.md +│ └── 05-file-organization-audit.md +├── children/ +│ ├── 01-1-template-inventory.md +│ ├── 01-2-template-automation-mapping.md +│ ├── 01-3-labeler-rules-audit.md +│ ├── 01-4-ai-instructions.md +│ ├── 02-1-labels-color-consistency.md +│ ├── 02-2-issue-types-mapping.md +│ ├── 02-3-issue-fields-config.md +│ ├── 02-4-config-relationships.md +│ ├── 03-1-issue-creation-docs.md +│ ├── 03-2-pr-creation-docs.md +│ ├── 03-3-labeling-docs.md +│ ├── 03-4-file-organization-alignment.md +│ ├── 03-5-update-index.md +│ ├── 04-1-discover-audit-readmes.md +│ ├── 04-2-validate-mermaid-syntax.md +│ ├── 04-3-accessibility-compliance.md +│ ├── 04-4-update-readmes.md +│ ├── 05-1-current-vs-planned.md +│ ├── 05-2-agent-script-locations.md +│ └── 05-3-migration-plan.md +└── templates/ + └── (reusable issue templates) +``` + +--- + +## 🎯 Issue Summary + +### Parent Issues (5 total) + +| Issue | Title | Type | Area | Effort | Status | +|-------|-------|------|------|--------|--------| +| [#649](https://github.com/lightspeedwp/.github/issues/649) | Issue Templates, Automation, & AI Agent Integration | Audit | automation, labels | M | open | +| [#650](https://github.com/lightspeedwp/.github/issues/650) | Canonical Config Files (labels, issue-types, issue-fields) | Audit | labels, automation | L | open | +| [#651](https://github.com/lightspeedwp/.github/issues/651) | Documentation Consolidation - Reduce Duplication | Audit | documentation | XL | open | +| [#652](https://github.com/lightspeedwp/.github/issues/652) | 44 README Files - Mermaid Diagrams & Accessibility | Audit | documentation, a11y | XL | open | +| [#653](https://github.com/lightspeedwp/.github/issues/653) | File Organization - Align with CLAUDE.md Boundaries | Audit | core | L | open | + +### Child Issues by Parent + +#### Parent #649: Issue Templates & Automation (4 children) + +- [#654](https://github.com/lightspeedwp/.github/issues/654): Issue Template Inventory & Standardization (Audit, S) +- [#655](https://github.com/lightspeedwp/.github/issues/655): Issue Template → Automation Trigger Mapping (Audit, M) +- [#656](https://github.com/lightspeedwp/.github/issues/656): Issue Labeling Rules in labeler.yml (Audit, M) +- [#657](https://github.com/lightspeedwp/.github/issues/657): Clear AI Agent Instructions for Issue Creation (Task, M) + +#### Parent #650: Canonical Configs (4 children) + +- [#658](https://github.com/lightspeedwp/.github/issues/658): labels.yml Color Consistency & Strategy (Audit, M) +- [#659](https://github.com/lightspeedwp/.github/issues/659): Issue Types Alignment with Templates & Labels (Audit, M) +- [#660](https://github.com/lightspeedwp/.github/issues/660): Issue Fields Configuration vs. GitHub API (Audit, M) +- [#661](https://github.com/lightspeedwp/.github/issues/661): Canonical Config File Interdependencies (Task, L) + +#### Parent #651: Documentation Consolidation (5 children) + +- [#662](https://github.com/lightspeedwp/.github/issues/662): Issue Creation Docs - Consolidate (Audit, M) +- [#663](https://github.com/lightspeedwp/.github/issues/663): PR Creation Docs - Consolidate (Audit, M) +- [#664](https://github.com/lightspeedwp/.github/issues/664): Labeling Docs - Consolidate (Audit, M) +- [#665](https://github.com/lightspeedwp/.github/issues/665): File Organization vs. CLAUDE.md (Audit, M) +- [#666](https://github.com/lightspeedwp/.github/issues/666): Update Documentation Index (Task, M) + +#### Parent #652: README & Mermaid Audit (4 children) + +- [#667](https://github.com/lightspeedwp/.github/issues/667): Discover All 44 README Files (Audit, M) +- [#668](https://github.com/lightspeedwp/.github/issues/668): Validate Mermaid Diagram Syntax (Audit, L) +- [#669](https://github.com/lightspeedwp/.github/issues/669): Mermaid Accessibility Compliance (Audit, L) +- [#670](https://github.com/lightspeedwp/.github/issues/670): Fix & Refresh 44 README Files (Task, XL) + +#### Parent #653: File Organization (3 children) + +- [#671](https://github.com/lightspeedwp/.github/issues/671): Current vs. Planned File Organization (Audit, M) +- [#672](https://github.com/lightspeedwp/.github/issues/672): Agent & Script Files - Migration Status (Audit, M) +- [#673](https://github.com/lightspeedwp/.github/issues/673): File Organization Refactoring Plan (Task, L) + +--- + +## 🔗 Reference Links Preserved + +All issues include links to: + +- **Configuration files:** `.github/labels.yml`, `issue-types.yml`, `labeler.yml`, `issue-fields.yml` +- **Documentation files:** All files in `docs/` with full GitHub URLs +- **Templates:** Issue, PR, and Discussion templates +- **Instructions:** All `.instructions.md` files across `instructions/` +- **Related issues:** #512, #513 (Wave 3 README audit) +- **Main reference:** CLAUDE.md + +See each issue file for specific links. + +--- + +## ✅ Pre-Creation Checklist + +Before creating issues in GitHub, verify: + +- [ ] All parent issue files exist in `parents/` +- [ ] All child issue files exist in `children/` +- [ ] All reference links are correct (can check by opening in GitHub) +- [ ] All issue titles are clear and specific +- [ ] All effort estimates are reasonable +- [ ] All parent-child relationships are documented +- [ ] All acceptance criteria are specific and measurable +- [ ] All deliverables are clear + +--- + +## 📊 Statistics + +- **Total Issues:** 25 (5 parents + 20 children) +- **Total Effort:** ~85-95 hours (if executed sequentially) +- **Expected Timeline:** 5-6 weeks (depending on team capacity) + +**Effort Breakdown:** + +- Audits: ~50-60 hours +- Implementation/fixes: ~25-35 hours + +--- + +## 🚀 Next Steps + +1. **Triage Phase** (Current) + - Review all issue files in this directory + - Prioritize which audits to execute first + - Assign team members to issues + - Verify reference links are correct + +2. **Execution Phase** + - Execute audits in parallel (can run simultaneously) + - Document findings in GitHub issue comments + - Consolidate findings across related audits + +3. **Implementation Phase** (Follows completion of audits) + - Create implementation issues based on audit findings + - Fix issues identified in audits + - Update documentation and configuration files + - Verify changes work correctly (test automated labeling, etc.) + +--- + +## 📝 GitHub Issues Created + +✅ All 5 parent issues created (#649–#653) +✅ All 20 child issues created (#654–#673) +✅ Parent-child relationships established in GitHub +✅ All reference links included and preserved +✅ All effort estimates provided +✅ All acceptance criteria specified + +**Status:** Issues ready for execution — see GitHub links in tables above + +--- + +**Last Updated:** 2026-05-31 +**Created By:** Claude Code +**For:** LightSpeed Team diff --git a/.github/projects/active/wave-5-documentation-audit/children/01-1-template-inventory.md b/.github/projects/active/wave-5-documentation-audit/children/01-1-template-inventory.md new file mode 100644 index 000000000..84327f998 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/01-1-template-inventory.md @@ -0,0 +1,52 @@ +--- +issue_number: 654 +file_type: "task" +description: "Inventory and audit of issue templates for standardization" +parent_issue: 649 +title: "[Child of #649] Audit: Issue Template Inventory & Standardization" +type: "type:audit" +area: "area:documentation" +priority: "priority:normal" +status: "status:needs-triage" +effort: "S" +--- + +## Overview + +Inventory and audit of all issue templates in `.github/ISSUE_TEMPLATE/` to verify standardization, completeness, and consistency. + +## Scope + +- Inventory all `.md` files in `.github/ISSUE_TEMPLATE/` +- Check if each template has required frontmatter +- Verify each template's relationship to an issue type in `issue-types.yml` +- Document which templates are actively used vs. deprecated +- Check `config.yml` for completeness + +## Audit Checklist + +- [ ] Create inventory spreadsheet with all templates +- [ ] Verify frontmatter structure in each template +- [ ] Cross-reference each template with `issue-types.yml` +- [ ] Document usage status for each template +- [ ] Check `.github/ISSUE_TEMPLATE/config.yml` for accuracy +- [ ] Identify deprecated or unused templates + +## Deliverables + +- Audit report as issue comment +- Spreadsheet: Template Name | Issue Type | Frontmatter Status | Usage Status | Last Updated | Notes +- List of standardization recommendations + +## Related Files + +- `.github/ISSUE_TEMPLATE/` (all `.md` files) +- `.github/ISSUE_TEMPLATE/config.yml` +- `.github/ISSUE_TEMPLATE/README.md` +- `.github/issue-types.yml` + +## Related Documentation + +- [Issue Templates Directory](https://github.com/lightspeedwp/.github/blob/develop/.github/ISSUE_TEMPLATE/README.md) +- [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_TYPES.md) +- [Issue Creation Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_CREATION_GUIDE.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/01-2-template-automation-mapping.md b/.github/projects/active/wave-5-documentation-audit/children/01-2-template-automation-mapping.md new file mode 100644 index 000000000..35cccf7f9 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/01-2-template-automation-mapping.md @@ -0,0 +1,52 @@ +--- +issue_number: 655 +file_type: "task" +description: "Map issue templates to their automation triggers" +parent_issue: 649 +title: "[Child of #649] Audit: Issue Template → Automation Trigger Mapping" +type: "type:audit" +area: "area:automation" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Map each issue template to the automation it should trigger and identify gaps between expected vs. actual automation. + +## Scope + +- For each issue template, document what automation should trigger +- Check if issue templates set up frontmatter that triggers labeling +- Compare with PR templates to understand the gap +- Identify missing automation rules in `labeler.yml` for issue scenarios +- Document how AI agents should structure issues for proper automation + +## Audit Checklist + +- [ ] Create automation expectation list for each template +- [ ] Test each template and document what automation actually triggers +- [ ] Compare PR template automation vs. issue template automation +- [ ] Identify which `labeler.yml` rules apply to issues +- [ ] Document automation gaps (expected but missing) +- [ ] Identify heuristics used for issue labeling + +## Deliverables + +- Mapping document: Template → Expected Automation → Current Status → Missing Pieces +- Gap analysis report +- Recommendations for closing automation gaps + +## Related Files + +- `.github/ISSUE_TEMPLATE/` (all templates) +- `.github/PULL_REQUEST_TEMPLATE/` (for comparison) +- `.github/labeler.yml` (automation rules) +- `.github/issue-types.yml` (issue type definitions) + +## Related Documentation + +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) +- [Labeling Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/LABELING.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/01-3-labeler-rules-audit.md b/.github/projects/active/wave-5-documentation-audit/children/01-3-labeler-rules-audit.md new file mode 100644 index 000000000..c7c9fd01a --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/01-3-labeler-rules-audit.md @@ -0,0 +1,53 @@ +--- +issue_number: 656 +file_type: "task" +description: "Audit labeling rules for issue-specific automation" +parent_issue: 649 +title: "[Child of #649] Audit: Issue Labeling Rules in labeler.yml" +type: "type:audit" +area: "area:labels" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Comprehensive audit of labeling rules in `.github/labeler.yml` to identify issue-specific rules, gaps, and opportunities for improvement. + +## Scope + +- Review `.github/labeler.yml` for issue-specific rules +- Compare coverage between PR rules and issue rules +- Identify gaps (e.g., file path-based rules for issues) +- Document current issue detection heuristics +- Check if content/title-based rules exist for issues + +## Audit Checklist + +- [ ] Extract all issue-specific rules from `labeler.yml` +- [ ] Extract all PR-specific rules from `labeler.yml` +- [ ] Compare coverage between issue and PR rules +- [ ] Identify types of rules present (branch-based, file-based, content-based) +- [ ] Determine what heuristics are used for issues vs. PRs +- [ ] Document gaps and opportunities + +## Deliverables + +- Current issue rules inventory +- PR vs. issue rule comparison matrix +- Report of identified gaps +- Recommendations for adding issue rules + +## Related Files + +- `.github/labeler.yml` +- `.github/labels.yml` (canonical label definitions) +- `.github/issue-types.yml` (issue type mapping) +- `scripts/agents/includes/` (labeling agent code) + +## Related Documentation + +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Labeler Configuration](https://github.com/lightspeedwp/.github/blob/develop/.github/labeler.yml) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/01-4-ai-instructions.md b/.github/projects/active/wave-5-documentation-audit/children/01-4-ai-instructions.md new file mode 100644 index 000000000..4b31ea048 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/01-4-ai-instructions.md @@ -0,0 +1,56 @@ +--- +issue_number: 657 +file_type: "task" +description: "Create clear instructions for AI agents on issue creation" +parent_issue: 649 +title: "[Child of #649] Implement: Clear AI Agent Instructions for Issue Creation" +type: "type:task" +area: "area:automation" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Create or update clear, step-by-step instructions for how AI agents should create GitHub issues to ensure proper template usage, automation triggering, and label assignment. + +## Scope + +- Write clear instructions for AI agents on issue creation +- Include template selection guidelines +- Include frontmatter structure for issue automation +- Include label assignment strategy +- Include examples of well-formed issues +- Document the complete flow from intent → template → automation → result + +## Checklist + +- [ ] Document template selection criteria +- [ ] Document required frontmatter fields +- [ ] Document label assignment strategy +- [ ] Create step-by-step instructions for issue creation +- [ ] Create multiple examples (bug, feature, task, etc.) +- [ ] Document what automation should trigger +- [ ] Include troubleshooting section + +## Deliverables + +- Updated `.github/custom-instructions.md` with issue creation section +- New or updated instruction file for AI agent issue creation +- Examples of correctly-formatted issues +- Troubleshooting guide + +## Related Files + +- `.github/custom-instructions.md` (main target for updates) +- `.github/ISSUE_TEMPLATE/` (templates to reference) +- `.github/issue-types.yml` (types available) +- `docs/ISSUE_CREATION_GUIDE.md` (existing guidance) + +## Related Documentation + +- [Issue Creation Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_CREATION_GUIDE.md) +- [Custom Instructions](https://github.com/lightspeedwp/.github/blob/develop/.github/custom-instructions.md) +- [Issue Templates README](https://github.com/lightspeedwp/.github/blob/develop/.github/ISSUE_TEMPLATE/README.md) +- [AGENTS.md - AI Rules](https://github.com/lightspeedwp/.github/blob/develop/AGENTS.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/02-1-labels-color-consistency.md b/.github/projects/active/wave-5-documentation-audit/children/02-1-labels-color-consistency.md new file mode 100644 index 000000000..17008b830 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/02-1-labels-color-consistency.md @@ -0,0 +1,53 @@ +--- +issue_number: 658 +file_type: "task" +description: "Verify label colors follow the documented strategy" +parent_issue: 650 +title: "[Child of #650] Audit: labels.yml Color Consistency & Strategy Alignment" +type: "type:audit" +area: "area:labels" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Verify that all 200+ labels in `labels.yml` follow the documented color strategy and that colors are consistent within label families. + +## Scope + +- Review all labels in `.github/labels.yml` +- Check if each label's color matches the documented strategy +- Identify grey labels that should have family colors +- Verify color hex codes are valid +- Document color family assignments (status, priority, type, area, etc.) + +## Audit Checklist + +- [ ] Extract all labels and their colors +- [ ] Review documented color strategy in `LABEL_STRATEGY.md` +- [ ] Check each label family color consistency +- [ ] Identify grey labels (`E1E4E8`, `9198A1`, etc.) and verify intentionality +- [ ] Verify all hex codes are valid CSS colors +- [ ] Document any color inconsistencies +- [ ] Verify color families align with label function + +## Deliverables + +- Color consistency audit report +- Spreadsheet: Label Name | Current Color | Expected Color | Family | Status | Recommendation +- List of labels requiring color updates +- Updated color strategy documentation (if needed) + +## Related Files + +- `.github/labels.yml` +- `docs/LABEL_STRATEGY.md` +- `docs/ISSUE_LABELS.md` + +## Related Documentation + +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Issue Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_LABELS.md) +- [Canonical Labels File](https://github.com/lightspeedwp/.github/blob/develop/.github/labels.yml) diff --git a/.github/projects/active/wave-5-documentation-audit/children/02-2-issue-types-mapping.md b/.github/projects/active/wave-5-documentation-audit/children/02-2-issue-types-mapping.md new file mode 100644 index 000000000..be67744d9 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/02-2-issue-types-mapping.md @@ -0,0 +1,55 @@ +--- +issue_number: 659 +file_type: "task" +description: "Verify issue types align with templates and labels" +parent_issue: 650 +title: "[Child of #650] Audit: Issue Types Alignment with Templates & Labels" +type: "type:audit" +area: "area:labels" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Verify that all issue types in `issue-types.yml` have matching templates and labels, and that colors are consistent. + +## Scope + +- Review all issue types in `.github/issue-types.yml` +- Verify each type has a matching issue template in `.github/ISSUE_TEMPLATE/` +- Verify each type has a matching label in `.github/labels.yml` +- Check if type colors match label colors +- Identify unused types or orphaned templates + +## Audit Checklist + +- [ ] Extract all issue types from `issue-types.yml` +- [ ] Extract all issue templates from `.github/ISSUE_TEMPLATE/` +- [ ] Extract all `type:*` labels from `labels.yml` +- [ ] Create three-way mapping: Type ↔ Template ↔ Label +- [ ] Verify color consistency between type and label +- [ ] Identify orphaned templates without a type +- [ ] Identify types without templates +- [ ] Document alignment gaps + +## Deliverables + +- Issue types alignment audit report +- Mapping table: Issue Type | Template | Label | Color Match | Status +- List of orphaned or missing items +- Recommendations for alignment fixes + +## Related Files + +- `.github/issue-types.yml` +- `.github/labels.yml` +- `.github/ISSUE_TEMPLATE/` (all templates) +- `docs/ISSUE_TYPES.md` + +## Related Documentation + +- [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_TYPES.md) +- [Issue Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_LABELS.md) +- [Issue Templates](https://github.com/lightspeedwp/.github/blob/develop/.github/ISSUE_TEMPLATE/README.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/02-3-issue-fields-config.md b/.github/projects/active/wave-5-documentation-audit/children/02-3-issue-fields-config.md new file mode 100644 index 000000000..cde5bf3c0 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/02-3-issue-fields-config.md @@ -0,0 +1,55 @@ +--- +issue_number: 660 +file_type: "task" +description: "Validate issue fields configuration against GitHub API" +parent_issue: 650 +title: "[Child of #650] Audit: Issue Fields Configuration vs. GitHub API" +type: "type:audit" +area: "area:labels" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Validate that `issue-fields.yml` configuration is complete, correct, and aligns with GitHub's issue fields API. + +## Scope + +- Review `.github/issue-fields.yml` configuration +- Verify custom fields are properly defined +- Check field mappings to GitHub API +- Verify field values match what GitHub supports +- Test field creation/update via automation + +## Audit Checklist + +- [ ] Extract all custom fields from `issue-fields.yml` +- [ ] Verify field naming conventions +- [ ] Check field types (single_select, date, text, etc.) +- [ ] Verify field values are valid GitHub options +- [ ] Check field descriptions are clear and complete +- [ ] Verify required field configurations +- [ ] Test field creation via API or workflow +- [ ] Identify any deprecated or unsupported fields + +## Deliverables + +- Issue fields validation report +- Field configuration checklist +- Any identified GitHub API misalignments +- Test results and recommendations +- Documentation updates (if needed) + +## Related Files + +- `.github/issue-fields.yml` +- docs/ISSUE-FIELDS.md +- docs/ISSUE_TYPES.md + +## Related Documentation + +- [Issue Fields Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE-FIELDS.md) +- [GitHub API - Issue Fields](https://docs.github.com/en/rest/reference/issues) +- [Canonical Issue Fields](https://github.com/lightspeedwp/.github/blob/develop/.github/issue-fields.yml) diff --git a/.github/projects/active/wave-5-documentation-audit/children/02-4-config-relationships.md b/.github/projects/active/wave-5-documentation-audit/children/02-4-config-relationships.md new file mode 100644 index 000000000..9c6a7726a --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/02-4-config-relationships.md @@ -0,0 +1,57 @@ +--- +issue_number: 661 +file_type: "task" +description: "Document relationships between canonical config files" +parent_issue: 650 +title: "[Child of #650] Document: Canonical Config File Interdependencies" +type: "type:task" +area: "area:labels" +priority: "priority:important" +status: "status:needs-triage" +effort: "L" +--- + +## Overview + +Create comprehensive documentation of how canonical config files (labels.yml, issue-types.yml, labeler.yml, issue-fields.yml) relate to each other and how automation uses them. + +## Scope + +- Create diagram showing how all config files interact +- Document the flow: issue creation → template selection → type assignment → label application → field population +- Identify all dependencies and relationships +- Document which tools/agents use which configs +- Create reference guide for extending configs + +## Checklist + +- [ ] Create Mermaid diagram showing config relationships +- [ ] Document data flow from issue creation to automation completion +- [ ] Document all tool/agent dependencies +- [ ] Create reference guide for adding new labels/types/fields +- [ ] Document config format and validation rules +- [ ] Create troubleshooting guide for config issues +- [ ] Document how configs are synced across repos + +## Deliverables + +- Relationship diagram (Mermaid, accessible for light/dark mode) +- Config interdependencies documentation +- Data flow diagram (issue creation → automation) +- Reference guide for extending configs +- New file: `docs/CANONICAL_CONFIGS_GUIDE.md` + +## Related Files + +- `.github/labels.yml` +- `.github/issue-types.yml` +- `.github/labeler.yml` +- `.github/issue-fields.yml` +- `docs/LABEL_STRATEGY.md` +- `scripts/agents/includes/` (labeling agent code) + +## Related Documentation + +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) +- [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_TYPES.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/03-1-issue-creation-docs.md b/.github/projects/active/wave-5-documentation-audit/children/03-1-issue-creation-docs.md new file mode 100644 index 000000000..4fd45460b --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/03-1-issue-creation-docs.md @@ -0,0 +1,62 @@ +--- +issue_number: 662 +file_type: "task" +description: "Audit and consolidate issue creation documentation" +parent_issue: 651 +title: "[Child of #651] Audit: Issue Creation Docs - Consolidate Overlapping Files" +type: "type:audit" +area: "area:documentation" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Audit all documentation related to issue creation to identify duplication and overlap, and propose a consolidation strategy. + +## Scope + +Review all issue creation related files: + +- `docs/ISSUE_CREATION_GUIDE.md` +- `docs/ISSUE_LABELS.md` +- `docs/ISSUE_TYPES.md` +- `.github/ISSUE_TEMPLATE/README.md` +- `docs/index.md` (if references issues) +- `instructions/issues.instructions.md` + +## Audit Checklist + +- [ ] Read through all 6 files listed above +- [ ] Identify overlapping content between files +- [ ] Document what information is in each file +- [ ] Note cross-references and links between files +- [ ] Identify gaps or missing information +- [ ] Propose where each piece of info should live +- [ ] Identify files that could be merged or archived + +## Deliverables + +- Consolidation audit report +- Consolidation matrix: Current File | Content | Proposed Location | Action (Keep/Merge/Archive) +- List of cross-references to update +- Proposed new structure for issue creation docs + +## Related Files + +- `docs/ISSUE_CREATION_GUIDE.md` +- `docs/ISSUE_LABELS.md` +- `docs/ISSUE_TYPES.md` +- `.github/ISSUE_TEMPLATE/README.md` +- `instructions/issues.instructions.md` +- `docs/index.md` + +## Related Documentation + +- [Issue Creation Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_CREATION_GUIDE.md) +- [Issue Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_LABELS.md) +- [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_TYPES.md) +- [Issue Templates README](https://github.com/lightspeedwp/.github/blob/develop/.github/ISSUE_TEMPLATE/README.md) +- [Issue Instructions](https://github.com/lightspeedwp/.github/blob/develop/instructions/issues.instructions.md) +- [Documentation Index](https://github.com/lightspeedwp/.github/blob/develop/docs/index.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/03-2-pr-creation-docs.md b/.github/projects/active/wave-5-documentation-audit/children/03-2-pr-creation-docs.md new file mode 100644 index 000000000..7f5e71730 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/03-2-pr-creation-docs.md @@ -0,0 +1,59 @@ +--- +issue_number: 663 +file_type: "task" +description: "Audit and consolidate PR creation documentation" +parent_issue: 651 +title: "[Child of #651] Audit: PR Creation Docs - Consolidate Overlapping Files" +type: "type:audit" +area: "area:documentation" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Audit all documentation related to PR creation to identify duplication and overlap, and propose a consolidation strategy. + +## Scope + +Review all PR creation related files: + +- `docs/PR_CREATION_PROCESS.md` +- `docs/PR_LABELS.md` +- `.github/PULL_REQUEST_TEMPLATE/README.md` +- `instructions/pull-requests.instructions.md` +- `docs/BRANCHING_STRATEGY.md` + +## Audit Checklist + +- [ ] Read through all 5 files listed above +- [ ] Identify overlapping content between files +- [ ] Document what information is in each file +- [ ] Note cross-references and links between files +- [ ] Identify gaps or missing information +- [ ] Propose where each piece of info should live +- [ ] Identify files that could be merged or archived + +## Deliverables + +- Consolidation audit report +- Consolidation matrix: Current File | Content | Proposed Location | Action +- List of cross-references to update +- Proposed new structure for PR creation docs + +## Related Files + +- `docs/PR_CREATION_PROCESS.md` +- `docs/PR_LABELS.md` +- `.github/PULL_REQUEST_TEMPLATE/README.md` +- `instructions/pull-requests.instructions.md` +- `docs/BRANCHING_STRATEGY.md` + +## Related Documentation + +- [PR Creation Process](https://github.com/lightspeedwp/.github/blob/develop/docs/PR_CREATION_PROCESS.md) +- [PR Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/PR_LABELS.md) +- [PR Templates README](https://github.com/lightspeedwp/.github/blob/develop/.github/PULL_REQUEST_TEMPLATE/README.md) +- [Pull Requests Instructions](https://github.com/lightspeedwp/.github/blob/develop/instructions/pull-requests.instructions.md) +- [Branching Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/BRANCHING_STRATEGY.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/03-3-labeling-docs.md b/.github/projects/active/wave-5-documentation-audit/children/03-3-labeling-docs.md new file mode 100644 index 000000000..90f687a4b --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/03-3-labeling-docs.md @@ -0,0 +1,62 @@ +--- +issue_number: 664 +file_type: "task" +description: "Audit and consolidate labeling documentation" +parent_issue: 651 +title: "[Child of #651] Audit: Labeling Docs - Consolidate Overlapping Files" +type: "type:audit" +area: "area:documentation" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Audit all documentation related to labeling to identify duplication, consolidate into a single source of truth, and eliminate redundancy. + +## Scope + +Review all labeling related files: + +- `docs/LABEL_STRATEGY.md` +- `docs/LABELING.md` +- `docs/ISSUE_LABELS.md` +- `docs/PR_LABELS.md` +- `docs/AUTOMATION_GOVERNANCE.md` (label section) +- Agent specs for labeling + +## Audit Checklist + +- [ ] Read through all 6 files listed above +- [ ] Identify overlapping content between files +- [ ] Document what information is in each file +- [ ] Note cross-references and links between files +- [ ] Identify the "source of truth" for each topic +- [ ] Identify gaps or missing information +- [ ] Propose consolidation strategy +- [ ] Recommend which file should be primary reference + +## Deliverables + +- Labeling documentation audit report +- Content matrix: File | Topic | Is Unique | Is Duplicated | Should Be Where +- List of files that could be merged +- Proposed unified structure for labeling docs + +## Related Files + +- `docs/LABEL_STRATEGY.md` +- `docs/LABELING.md` +- `docs/ISSUE_LABELS.md` +- `docs/PR_LABELS.md` +- `docs/AUTOMATION_GOVERNANCE.md` +- `.github/agents/labeling.agent.md` (if exists) + +## Related Documentation + +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Labeling Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/LABELING.md) +- [Issue Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_LABELS.md) +- [PR Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/PR_LABELS.md) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/03-4-file-organization-alignment.md b/.github/projects/active/wave-5-documentation-audit/children/03-4-file-organization-alignment.md new file mode 100644 index 000000000..bf14158e2 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/03-4-file-organization-alignment.md @@ -0,0 +1,57 @@ +--- +issue_number: 665 +file_type: "task" +description: "Audit documentation folder structure vs. CLAUDE.md" +parent_issue: 651 +title: "[Child of #651] Audit: Documentation Folder Structure vs. CLAUDE.md Boundaries" +type: "type:audit" +area: "area:core" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Audit current documentation folder organization against the planned structure in CLAUDE.md to identify misplacements and reorganization needs. + +## Scope + +- Review current structure of `docs/`, `.github/`, `instructions/`, and related folders +- Compare against CLAUDE.md guidance for where documentation should live +- Identify misplaced files +- Identify missing documentation +- Propose reorganization plan with rationale + +## Audit Checklist + +- [ ] Extract current documentation file structure +- [ ] Review CLAUDE.md repository boundaries section +- [ ] Create mapping: Current Location → Expected Location +- [ ] Identify files in wrong folder +- [ ] Identify folders that need to be created +- [ ] Identify files that should be merged or archived +- [ ] Document rationale for any reorganization +- [ ] Create migration plan with dependencies + +## Deliverables + +- Current state documentation inventory +- Mapping table: File | Current Location | Expected Location (per CLAUDE.md) | Action +- Reorganization proposal with rationale +- Migration plan with step-by-step instructions documented in the central /docs/MIGRATION.md file +- Impact assessment (what breaks if we move X?) + +## Related Files + +- `CLAUDE.md` (source of truth) +- `docs/` (all files) +- `.github/` (all subfolders) +- `instructions/` (all files) +- `README.md` (root) + +## Related Documentation + +- [CLAUDE.md - Repository Boundaries](https://github.com/lightspeedwp/.github/blob/develop/CLAUDE.md#repository-boundaries) +- [File Organisation Instructions](https://github.com/lightspeedwp/.github/blob/develop/.github/instructions/file-organisation.instructions.md) +- [Organization Overview](https://github.com/lightspeedwp/.github/blob/develop/docs/ORGANIZATION.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/03-5-update-index.md b/.github/projects/active/wave-5-documentation-audit/children/03-5-update-index.md new file mode 100644 index 000000000..2efff16a4 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/03-5-update-index.md @@ -0,0 +1,58 @@ +--- +issue_number: 666 +file_type: "task" +description: "Update documentation index with complete inventory" +parent_issue: 651 +title: "[Child of #651] Update: Documentation Index (docs/index.md) - Complete & Current" +type: "type:task" +area: "area:documentation" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Create or update the documentation index in docs/INDEX.md to provide a complete, current, and organized guide to all documentation in the repository. + +## Scope + +- Review current docs/INDEX.md +- Add/update all documentation files across the repo +- Organize by topic (issue creation, PR creation, labeling, automation, etc.) +- Add brief description for each file +- Add link to related template/config files +- Ensure all cross-references are correct + +## Checklist + +- [ ] Review current documentation index +- [ ] Create complete inventory of all documentation files +- [ ] Organize files by logical topic/category +- [ ] Write brief description (1-2 sentences) for each file +- [ ] Add links to related templates and config files +- [ ] Verify all internal links are correct +- [ ] Add table of contents or navigation aids +- [ ] Add "Getting Started" section for new users +- [ ] Add links to tools and agents + +## Deliverables + +- Updated docs/INDEX.md with complete inventory +- Organized by topic with descriptions +- Cross-references and links verified +- (Optional) Table of contents or visual site map +- (Optional) "New User" quick-start section + +## Related Files + +- docs/INDEX.md (main target) +- All files in `docs/` +- Key files in `.github/` +- Key files in `instructions/` + +## Related Documentation + +- [Current Documentation Index](https://github.com/lightspeedwp/.github/blob/develop/docs/index.md) +- [Root README](https://github.com/lightspeedwp/.github/blob/develop/README.md) +- [CLAUDE.md](https://github.com/lightspeedwp/.github/blob/develop/CLAUDE.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/04-1-discover-audit-readmes.md b/.github/projects/active/wave-5-documentation-audit/children/04-1-discover-audit-readmes.md new file mode 100644 index 000000000..2cf552830 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/04-1-discover-audit-readmes.md @@ -0,0 +1,54 @@ +--- +issue_number: 667 +file_type: "task" +description: "Discover and inventory all README.md files" +parent_issue: 652 +title: "[Child of #652] Audit: Discover All 44 README.md Files - Inventory" +type: "type:audit" +area: "area:documentation" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Discover, inventory, and audit all README.md files across the repository to create a comprehensive baseline for subsequent audits and improvements. + +## Scope + +- Use script or manual inspection to find all README.md files +- Create inventory spreadsheet with metadata for each +- Categorize by: Root/Core, Feature folders, Sub-folders, Test/Config +- Check each README for broken links, outdated content +- Identify which ones have Mermaid diagrams +- Note file sizes and last update dates + +## Audit Checklist + +- [ ] Find all README.md files in repo +- [ ] Create spreadsheet with columns: Path | Size | Last Updated | Has Mermaid | Issues Found +- [ ] Categorize each README by folder type +- [ ] Check for broken links in each README +- [ ] Check for outdated content indicators +- [ ] Note presence and count of Mermaid diagrams +- [ ] Document any immediate issues found + +## Deliverables + +- Complete README inventory spreadsheet/CSV +- List of READMEs by category (with counts) +- Initial issues log (broken links, outdated content) +- Mermaid diagram inventory (which READMEs have diagrams, how many) + +## Related Files + +- All README.md files across repository +- `.github/` folder and subfolders +- `docs/` folder and subfolders +- `agents/`, `scripts/`, `workflows/`, `instructions/` folders + +## Related Documentation + +- [Documentation Index](https://github.com/lightspeedwp/.github/blob/develop/docs/index.md) +- [Related Issues: #512 & #513](https://github.com/lightspeedwp/.github/issues/512) diff --git a/.github/projects/active/wave-5-documentation-audit/children/04-2-validate-mermaid-syntax.md b/.github/projects/active/wave-5-documentation-audit/children/04-2-validate-mermaid-syntax.md new file mode 100644 index 000000000..d5eda4971 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/04-2-validate-mermaid-syntax.md @@ -0,0 +1,53 @@ +--- +issue_number: 668 +file_type: "task" +description: "Validate Mermaid diagram syntax in all files" +parent_issue: 652 +title: "[Child of #652] Audit: Validate Mermaid Syntax in All Diagrams" +type: "type:audit" +area: "area:documentation" +priority: "priority:normal" +status: "status:needs-triage" +effort: "L" +--- + +## Overview + +Validate Mermaid diagram syntax across all README files to identify and document parsing errors. + +## Scope + +- For each README with Mermaid diagrams, validate syntax +- Check for parse errors in each diagram +- Verify diagram type is supported by Mermaid +- Test rendering in Mermaid Live Editor +- Document specific errors and required fixes + +## Audit Checklist + +- [ ] Extract all Mermaid diagrams from READMEs +- [ ] Test each diagram in Mermaid Live Editor +- [ ] Document any syntax errors found +- [ ] Verify diagram type (flowchart, sequence, state, etc.) +- [ ] Check for unsupported diagram types +- [ ] Document specific line numbers of errors +- [ ] Create list of diagrams needing fixes + +## Deliverables + +- Mermaid syntax validation report +- List of diagrams with errors +- Specific error descriptions and line numbers +- Recommendations for fixes +- Spreadsheet: README | Diagram Type | Has Error | Error Description | Severity + +## Related Files + +- All README.md files with Mermaid diagrams +- Mermaid documentation + +## Related Documentation + +- [Mermaid Official Docs](https://mermaid.js.org/) +- [Mermaid Live Editor](https://mermaid.live/) +- [Documentation Formats Guide](https://github.com/lightspeedwp/.github/blob/develop/instructions/documentation-formats.instructions.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/04-3-accessibility-compliance.md b/.github/projects/active/wave-5-documentation-audit/children/04-3-accessibility-compliance.md new file mode 100644 index 000000000..749179c82 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/04-3-accessibility-compliance.md @@ -0,0 +1,54 @@ +--- +issue_number: 669 +file_type: "task" +description: "Audit Mermaid diagrams for accessibility compliance" +parent_issue: 652 +title: "[Child of #652] Audit: Mermaid Diagram Accessibility (WCAG AA, Light/Dark Mode)" +type: "type:audit" +area: "area:a11y" +priority: "priority:normal" +status: "status:needs-triage" +effort: "L" +--- + +## Overview + +Audit Mermaid diagrams for accessibility compliance (WCAG AA standards) and proper rendering in light/dark modes. + +## Scope + +- For each Mermaid diagram, check for accessibility attributes: + - `accTitle` (accessible title) + - `accDescr` (accessible description) +- Test diagrams in light and dark mode +- Verify color contrast (WCAG AA standards) +- Document which diagrams need accessibility improvements + +## Audit Checklist + +- [ ] Create list of all Mermaid diagrams +- [ ] Check each diagram for `accTitle` attribute +- [ ] Check each diagram for `accDescr` attribute +- [ ] Test each diagram in light mode +- [ ] Test each diagram in dark mode +- [ ] Verify color contrast ratios meet WCAG AA (4.5:1 minimum) +- [ ] Document accessibility gaps + +## Deliverables + +- Accessibility audit report +- Spreadsheet: Diagram | Has accTitle | Has accDescr | Light Mode OK | Dark Mode OK | Contrast OK | Fixes Needed +- List of diagrams requiring accessibility improvements +- Specific recommendations for each diagram + +## Related Files + +- All README.md files with Mermaid diagrams +- Mermaid documentation + +## Related Documentation + +- [Accessibility Instructions](https://github.com/lightspeedwp/.github/blob/develop/instructions/a11y.instructions.md) +- [WCAG 2.2 Standards](https://www.w3.org/WAI/WCAG22/quickref/) +- [Mermaid Accessibility Docs](https://mermaid.js.org/) +- [Documentation Formats Guide](https://github.com/lightspeedwp/.github/blob/develop/instructions/documentation-formats.instructions.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/04-4-update-readmes.md b/.github/projects/active/wave-5-documentation-audit/children/04-4-update-readmes.md new file mode 100644 index 000000000..09bb3e3b2 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/04-4-update-readmes.md @@ -0,0 +1,61 @@ +--- +issue_number: 670 +file_type: "task" +description: "Fix and refresh README files with current information" +parent_issue: 652 +title: "[Child of #652] Update: Fix & Refresh 44 README Files with Current Information" +type: "type:task" +area: "area:documentation" +priority: "priority:normal" +status: "status:needs-triage" +effort: "XL" +--- + +## Overview + +Implementation phase: Update all 44 README files with current information, fix syntax errors, add/update Mermaid diagrams with accessibility attributes, and ensure consistent formatting. + +## Scope + +This is the implementation phase following audits from child issues 4.1-4.3: + +- Update outdated content based on audit findings +- Fix broken links identified in audits +- Add/update Mermaid diagrams with proper accessibility attributes +- Ensure diagrams render correctly in light/dark mode +- Apply consistent formatting across all READMEs + +## Checklist + +- [ ] Review findings from audit child issues +- [ ] Update each README with current folder/file purpose +- [ ] Fix all broken links identified in audits +- [ ] Add `accTitle` and `accDescr` to all Mermaid diagrams +- [ ] Test all diagrams in light and dark mode +- [ ] Verify color contrast meets WCAG AA +- [ ] Apply consistent README structure/formatting +- [ ] Verify all cross-references are correct + +## Deliverables + +- All 44 README.md files updated +- Repair report documenting all changes +- Verification report: all links working, diagrams accessible +- Before/after comparison (key changes) + +## Related Files + +All 44 README.md files across the repository + +## Related Issues + +- Child 4.1 — Discover & Audit READMEs +- Child 4.2 — Validate Mermaid Syntax +- Child 4.3 — Accessibility Compliance +- [#512 — Wave 3A Discovery & Audit](https://github.com/lightspeedwp/.github/issues/512) +- [#513 — Wave 3B Repair & Update](https://github.com/lightspeedwp/.github/issues/513) + +## Related Documentation + +- [Accessibility Instructions](https://github.com/lightspeedwp/.github/blob/develop/instructions/a11y.instructions.md) +- [Documentation Formats Guide](https://github.com/lightspeedwp/.github/blob/develop/instructions/documentation-formats.instructions.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/05-1-current-vs-planned.md b/.github/projects/active/wave-5-documentation-audit/children/05-1-current-vs-planned.md new file mode 100644 index 000000000..e1e78e0c7 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/05-1-current-vs-planned.md @@ -0,0 +1,52 @@ +--- +issue_number: 671 +file_type: "task" +description: "Audit current file organization vs. CLAUDE.md" +parent_issue: 653 +title: "[Child of #653] Audit: Current File Organization vs. CLAUDE.md Boundaries" +type: "type:audit" +area: "area:core" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Audit current repository file organization against the planned structure defined in CLAUDE.md to identify misalignments. + +## Scope + +- Map current structure of `.github/`, root folders, and all major directories +- Compare against CLAUDE.md definitions for reusable vs. GitHub-native assets +- Identify misplacements of files/folders +- Document what's in the wrong location according to CLAUDE.md + +## Audit Checklist + +- [ ] Extract current directory structure +- [ ] Review CLAUDE.md repository boundaries section (source of truth) +- [ ] Create mapping: Current Location | Expected Location (per CLAUDE.md) | Status +- [ ] Identify items in wrong location +- [ ] Identify missing expected folders +- [ ] Identify unexpected items in `.github/` +- [ ] Document rationale for any current misplacements + +## Deliverables + +- Current state audit report +- Mapping document: Path | Current Location | Expected Location | Status +- List of misaligned items +- Impact assessment (what needs to move, what's OK as is) + +## Related Files + +- All folders and major files across repository +- `.github/` (entire folder) +- Root level folders: `agents/`, `scripts/`, `schemas/`, `docs/`, `workflows/`, etc. + +## Related Documentation + +- [CLAUDE.md - Repository Boundaries](https://github.com/lightspeedwp/.github/blob/develop/CLAUDE.md#repository-boundaries) +- [File Organisation Instructions](https://github.com/lightspeedwp/.github/blob/develop/.github/instructions/file-organisation.instructions.md) +- [Organization Overview](https://github.com/lightspeedwp/.github/blob/develop/docs/ORGANIZATION.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/05-2-agent-script-locations.md b/.github/projects/active/wave-5-documentation-audit/children/05-2-agent-script-locations.md new file mode 100644 index 000000000..656366c2c --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/05-2-agent-script-locations.md @@ -0,0 +1,55 @@ +--- +issue_number: 672 +file_type: "task" +description: "Audit agent and script file migration status" +parent_issue: 653 +title: "[Child of #653] Audit: Agent & Script Files - Migration Status" +type: "type:audit" +area: "area:core" +priority: "priority:normal" +status: "status:needs-triage" +effort: "M" +--- + +## Overview + +Audit the current location of agent and script files to determine migration status and identify items still in `.github/` that should be in root folders. + +## Scope + +- Check if `.github/agents/` still exists (should have moved to `/agents`) +- Check if `.github/scripts/` exists (should have moved to `/scripts`) +- Verify what remains in `.github/` vs. what's in root folders +- Document migration status for each file/folder +- Identify any duplication or orphaned files + +## Audit Checklist + +- [ ] List all files in `.github/agents/` (if exists) +- [ ] List all files in `.github/scripts/` (if exists) +- [ ] List all files in `agents/` (root level) +- [ ] List all files in `scripts/` (root level) +- [ ] Check for duplicate files in both locations +- [ ] Verify referenced paths in workflows/configs point to correct locations +- [ ] Document which files have been migrated vs. which haven't + +## Deliverables + +- Migration status audit report +- File inventory: Path | Current Location | Expected Location | Status | Notes +- List of files still needing migration +- List of potential duplicate files +- Recommendations for completion + +## Related Files + +- `.github/agents/` (if exists) +- `.github/scripts/` (if exists) +- `agents/` (root level) +- `scripts/` (root level) +- `.github/workflows/` (references to check) + +## Related Documentation + +- [CLAUDE.md - Repository Boundaries](https://github.com/lightspeedwp/.github/blob/develop/CLAUDE.md#repository-boundaries) +- [AGENTS.md](https://github.com/lightspeedwp/.github/blob/develop/AGENTS.md) diff --git a/.github/projects/active/wave-5-documentation-audit/children/05-3-migration-plan.md b/.github/projects/active/wave-5-documentation-audit/children/05-3-migration-plan.md new file mode 100644 index 000000000..d66e63db8 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/children/05-3-migration-plan.md @@ -0,0 +1,62 @@ +--- +issue_number: 673 +file_type: "task" +description: "Create detailed migration plan for file reorganization" +parent_issue: 653 +title: "[Child of #653] Plan: File Organization Refactoring - Migration & Validation" +type: "type:task" +area: "area:core" +priority: "priority:normal" +status: "status:needs-triage" +effort: "L" +--- + +## Overview + +Create a detailed migration plan for reorganizing files to align with CLAUDE.md structure, including impact assessment and validation steps. + +## Scope + +- Create detailed plan for reorganizing files to match CLAUDE.md +- Include impact assessment (what breaks if we move X?) +- Include validation checklist (how to verify moves worked?) +- Include rollback plan (how to recover if something goes wrong?) +- Create implementation timeline and sequencing +- Document any prerequisite work needed + +## Checklist + +- [ ] Review findings from child issues 5.1 and 5.2 +- [ ] Create step-by-step migration plan +- [ ] Identify dependencies (what must be moved first?) +- [ ] Document what will break during migration +- [ ] Create validation checklist for each move +- [ ] Create rollback procedures for each step +- [ ] Identify communication needed for team +- [ ] Create timeline with milestones + +## Deliverables + +- Detailed migration plan documented in the central /docs/MIGRATION.md file +- Dependency graph (what must happen first) +- Impact assessment for each major move +- Validation checklist for each step +- Rollback procedures +- Implementation timeline +- Communication plan for team + +## Related Files + +- All folders and files identified in child issues 5.1 and 5.2 +- `.github/` and root level folders + +## Related Issues + +- Child 5.1 — Current vs. Planned audit +- Child 5.2 — Agent & Script migration status + +## Related Documentation + +- [CLAUDE.md - Repository Boundaries](https://github.com/lightspeedwp/.github/blob/develop/CLAUDE.md#repository-boundaries) +- [File Organisation Instructions](https://github.com/lightspeedwp/.github/blob/develop/.github/instructions/file-organisation.instructions.md) +- [AGENTS.md](https://github.com/lightspeedwp/.github/blob/develop/AGENTS.md) diff --git a/.github/projects/active/wave-5-documentation-audit/parents/01-issue-templates-automation-audit.md b/.github/projects/active/wave-5-documentation-audit/parents/01-issue-templates-automation-audit.md new file mode 100644 index 000000000..d1ea7c148 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/parents/01-issue-templates-automation-audit.md @@ -0,0 +1,66 @@ +--- +issue_number: 649 +file_type: "project" +description: "Comprehensive audit of issue templates, automation integration, and AI agent instructions" +title: "[Audit] Issue Templates, Automation, & AI Agent Integration" +type: "type:audit" +area: + - "area:automation" + - "area:labels" +priority: "priority:important" +status: "status:needs-triage" +effort: "M" +children: + - "1.1-template-inventory" + - "1.2-template-automation-mapping" + - "1.3-labeler-rules-audit" + - "1.4-ai-instructions" +--- + +## Overview + +Comprehensive audit of issue templates, their relationship to the automated labeling system, and how AI agents should create issues to trigger proper automation. + +## Current Problems + +1. Issue templates exist (`.github/ISSUE_TEMPLATE/*.md`) but don't consistently trigger automation +2. PR templates work well, but issue templates don't map clearly to labeling rules +3. `.github/labeler.yml` has rules for PRs and branches, but minimal rules for issues +4. AI agents don't have clear instructions on how to structure issues for automation + +## Areas to Audit + +See child issues for detailed audits of: + +- Issue template inventory and standardization +- Mapping between templates and automation triggers +- Missing automation rules in labeler.yml for issue types +- AI agent instructions for issue creation + +## Acceptance Criteria + +- [ ] All issue templates audited and categorized +- [ ] Clear mapping between template usage and automation triggers +- [ ] Labeler.yml rules for issues identified and documented +- [ ] AI agent instructions for issue creation updated + +## Related Files + +- `.github/ISSUE_TEMPLATE/` (all files) +- `.github/ISSUE_TEMPLATE/config.yml` +- `.github/ISSUE_TEMPLATE/README.md` +- `.github/labeler.yml` (issue rules section) +- `.github/issue-types.yml` +- `docs/ISSUE_CREATION_GUIDE.md` +- `.github/custom-instructions.md` + +## Related Issues + +- Parent Issue in Wave 5 Documentation Audit + +## Related Documentation + +- [Issue Creation Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_CREATION_GUIDE.md) +- [Issue Templates README](https://github.com/lightspeedwp/.github/blob/develop/.github/ISSUE_TEMPLATE/README.md) +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) diff --git a/.github/projects/active/wave-5-documentation-audit/parents/02-canonical-configs-audit.md b/.github/projects/active/wave-5-documentation-audit/parents/02-canonical-configs-audit.md new file mode 100644 index 000000000..da8813a16 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/parents/02-canonical-configs-audit.md @@ -0,0 +1,68 @@ +--- +issue_number: 650 +file_type: "project" +description: "Comprehensive audit of canonical configuration files and their relationships" +title: "[Audit] Canonical Config Files (labels, issue-types, issue-fields)" +type: "type:audit" +area: + - "area:labels" + - "area:automation" +priority: "priority:important" +status: "status:needs-triage" +effort: "L" +children: + - "2.1-labels-color-consistency" + - "2.2-issue-types-mapping" + - "2.3-issue-fields-config" + - "2.4-config-relationships" +--- + +## Overview + +Comprehensive audit of canonical configuration files that define labels, issue types, issue fields, and how they relate to each other. + +## Current Problems + +1. `labels.yml` has 200+ labels but many are grey and don't follow the color strategy +2. `issue-types.yml` defines 26 issue types but mapping to templates is unclear +3. `issue-fields.yml` defines custom fields but their usage in templates is unclear +4. No clear documentation on how these files work together or how to extend them +5. Inconsistencies between canonical files and documentation + +## Areas to Audit + +See child issues for detailed audits of: + +- Label color consistency and family grouping +- Issue type mapping and template correlation +- Issue fields configuration and GitHub API alignment +- Relationship and interdependencies between config files +- Missing or unused labels/types + +## Acceptance Criteria + +- [ ] All labels verified against color strategy +- [ ] Issue type definitions aligned with templates +- [ ] Issue fields configuration validated +- [ ] All interdependencies documented +- [ ] Deprecations and removals identified + +## Related Files + +- `.github/labels.yml` +- `.github/labeler.yml` +- `.github/issue-types.yml` +- `.github/issue-fields.yml` +- `docs/LABEL_STRATEGY.md` +- `docs/ISSUE_LABELS.md` +- `docs/ISSUE_TYPES.md` +- `docs/ISSUE-FIELDS.md` + +## Related Documentation + +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Issue Labels Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_LABELS.md) +- [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_TYPES.md) +- [Issue Fields Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE-FIELDS.md) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) +- [Canonical Labels File](https://github.com/lightspeedwp/.github/blob/develop/.github/labels.yml) diff --git a/.github/projects/active/wave-5-documentation-audit/parents/03-documentation-consolidation-audit.md b/.github/projects/active/wave-5-documentation-audit/parents/03-documentation-consolidation-audit.md new file mode 100644 index 000000000..9279219e8 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/parents/03-documentation-consolidation-audit.md @@ -0,0 +1,67 @@ +--- +issue_number: 651 +file_type: "project" +description: "Comprehensive audit and consolidation of documentation to reduce duplication and improve clarity" +title: "[Audit] Documentation Consolidation - Reduce Duplication Across Docs" +type: "type:audit" +area: "area:documentation" +priority: "priority:important" +status: "status:needs-triage" +effort: "XL" +children: + - "3.1-issue-creation-docs" + - "3.2-pr-creation-docs" + - "3.3-labeling-docs" + - "3.4-file-organization-alignment" + - "3.5-update-index" +--- + +## Overview + +Audit of 40+ documentation files across `docs/` to identify duplication, overlap, and opportunities for consolidation. + +## Current Problems + +1. Multiple files document similar topics (e.g., 3-4 files on PR creation) +2. Files reference each other with inconsistent linking patterns +3. Some documentation is in `docs/`, some in `.github/`, some in `instructions/` +4. Duplication makes updates difficult and creates sync/consistency issues +5. Documentation index (`docs/index.md`) is incomplete or outdated + +## Areas to Audit + +See child issues for detailed audits of: + +- Issue creation documentation (4+ files involved) +- PR creation documentation (3+ files involved) +- Labeling documentation (3+ files involved) +- Automation governance documentation (2+ files involved) +- File organization and folder structure alignment +- Documentation index and cross-referencing + +## Acceptance Criteria + +- [ ] All docs audited and duplication mapped +- [ ] Consolidation strategy created +- [ ] Obsolete files identified for archival +- [ ] Updated cross-reference links documented + +## Related Files + +- `docs/` (all .md files) +- `docs/index.md` +- `.github/README.md` +- `README.md` (root) +- Various `.instructions.md` files in `instructions/` +- `.github/ISSUE_TEMPLATE/README.md` +- `.github/PULL_REQUEST_TEMPLATE/README.md` + +## Related Documentation + +- [Documentation Index](https://github.com/lightspeedwp/.github/blob/develop/docs/index.md) +- [Issue Creation Guide](https://github.com/lightspeedwp/.github/blob/develop/docs/ISSUE_CREATION_GUIDE.md) +- [PR Creation Process](https://github.com/lightspeedwp/.github/blob/develop/docs/PR_CREATION_PROCESS.md) +- [Label Strategy](https://github.com/lightspeedwp/.github/blob/develop/docs/LABEL_STRATEGY.md) +- [Automation Governance](https://github.com/lightspeedwp/.github/blob/develop/docs/AUTOMATION_GOVERNANCE.md) +- [Root README](https://github.com/lightspeedwp/.github/blob/develop/README.md) +- [.github README](https://github.com/lightspeedwp/.github/blob/develop/.github/README.md) diff --git a/.github/projects/active/wave-5-documentation-audit/parents/04-readme-mermaid-audit.md b/.github/projects/active/wave-5-documentation-audit/parents/04-readme-mermaid-audit.md new file mode 100644 index 000000000..7b14cb3df --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/parents/04-readme-mermaid-audit.md @@ -0,0 +1,65 @@ +--- +issue_number: 652 +file_type: "project" +description: "Comprehensive audit of README files, Mermaid diagrams, and accessibility compliance" +title: "[Audit] 44 README Files - Mermaid Diagrams & Accessibility Review" +type: "type:audit" +area: + - "area:documentation" + - "area:a11y" +priority: "priority:normal" +status: "status:needs-triage" +effort: "XL" +children: + - "4.1-discover-audit-readmes" + - "4.2-validate-mermaid-syntax" + - "4.3-accessibility-compliance" + - "4.4-update-readmes" +--- + +## Overview + +Comprehensive audit of README.md files across the repository (~30–40) to verify Mermaid diagram syntax, accessibility compliance, and content freshness. + +## Current Problems + +1. Mermaid diagrams may have syntax errors or be outdated +2. Diagrams may lack accessibility attributes (accTitle, accDescr) +3. Diagrams may not work in light/dark mode +4. README content may be outdated or incomplete +5. No systematic way to verify diagram accessibility compliance + +## Areas to Audit + +See child issues for detailed audits of: + +- Root & core README files +- Feature folder README files +- Sub-folder README files +- Test/config README files +- Mermaid diagram syntax validation +- Accessibility compliance (WCAG AA) +- Light/dark mode rendering + +## Acceptance Criteria + +- [ ] All README files inventoried (actual count per audit report) +- [ ] Mermaid diagram syntax validated +- [ ] Accessibility attributes added where needed +- [ ] Content freshness verified and updated +- [ ] Audit report generated + +## Related Files + +All README.md files across the repository (see audit report for inventory) + +## Related Issues + +- [#512 — Wave 3A: README & Mermaid Diagram Discovery & Audit](https://github.com/lightspeedwp/.github/issues/512) +- [#513 — Wave 3B: README & Mermaid Diagram Repair & Update](https://github.com/lightspeedwp/.github/issues/513) + +## Related Documentation + +- [Documentation Index](https://github.com/lightspeedwp/.github/blob/develop/docs/index.md) +- [Accessibility Instructions](https://github.com/lightspeedwp/.github/blob/develop/instructions/a11y.instructions.md) +- [Documentation Formats Guide](https://github.com/lightspeedwp/.github/blob/develop/instructions/documentation-formats.instructions.md) diff --git a/.github/projects/active/wave-5-documentation-audit/parents/05-file-organization-audit.md b/.github/projects/active/wave-5-documentation-audit/parents/05-file-organization-audit.md new file mode 100644 index 000000000..57a467827 --- /dev/null +++ b/.github/projects/active/wave-5-documentation-audit/parents/05-file-organization-audit.md @@ -0,0 +1,62 @@ +--- +issue_number: 653 +file_type: "project" +description: "Comprehensive audit of file organization and alignment with CLAUDE.md repository structure" +title: "[Audit] File Organization - Align with CLAUDE.md Repository Boundaries" +type: "type:audit" +area: "area:core" +priority: "priority:normal" +status: "status:needs-triage" +effort: "L" +children: + - "5.1-current-vs-planned" + - "5.2-agent-script-locations" + - "5.3-migration-plan" +--- + +## Overview + +Audit current file organization against the planned structure defined in CLAUDE.md and identify misalignments requiring refactoring. + +## Current Problems + +1. `.github/agents/` still exists but agents moved to `/agents` in root +2. `.github/scripts/` exists but scripts moved to `/scripts` in root +3. `.github/schemas/` exists but should be `/schema` or `/schemas` in root +4. Documentation in both `docs/` and `.github/docs/` +5. Uncertainty about which folders are reusable vs. GitHub-native + +## Areas to Audit + +See child issues for detailed audits of: + +- `.github/` contents vs. root-level portable assets +- Agent file locations and migration status +- Script file locations and migration status +- Schema/config file locations +- Documentation folder organization +- Workflows folder structure +- Instructions folder organization + +## Acceptance Criteria + +- [ ] Current state mapped against CLAUDE.md +- [ ] All misalignments documented +- [ ] Migration plan with impact assessment and rollback procedures documented in `/docs/MIGRATION.md` +- [ ] Impact assessment completed + +## Related Files + +- `CLAUDE.md` (source of truth for repo boundaries) +- `.github/` (all folders) +- `agents/` +- `scripts/` +- `schema/` or `schemas/` +- `workflows/` +- `instructions/` + +## Related Documentation + +- [CLAUDE.md - Repository Boundaries](https://github.com/lightspeedwp/.github/blob/develop/CLAUDE.md#repository-boundaries) +- [File Organisation Instructions](https://github.com/lightspeedwp/.github/blob/develop/.github/instructions/file-organisation.instructions.md) +- [AGENTS.md](https://github.com/lightspeedwp/.github/blob/develop/AGENTS.md) diff --git a/scripts/validation/validate-conventional-commits.js b/scripts/validation/validate-conventional-commits.js index 0309ea01b..a3780c758 100644 --- a/scripts/validation/validate-conventional-commits.js +++ b/scripts/validation/validate-conventional-commits.js @@ -69,8 +69,7 @@ function getGitLog(since, limit = 50) { cmd += " " + since + "..HEAD"; } - const output = execSync(cmd, { encoding: "utf8", stdio: "pipe" }); - const commitStrings = output + const commitStrings = execSync(cmd, { encoding: "utf8", stdio: "pipe" }) .split("---END-COMMIT---\n") .filter((s) => s.trim());