Phase 1A: Audit & Migrate Instructions (Restructured)

[ashleyshaw]

Audit Summary

Audit and migrate instructions from .github/instructions/ to separate structure:

• Portable standards → root instructions/ folder
• Repo-local guidance → .github/instructions/ (control-plane-specific only)

Currently 47 files with 502+ references across 156 files need cataloging and migration.

Audit Checklist / Scope

• Identify and categorize all 47 instruction files (portable vs. repo-local)
• Document all 502+ reference locations
• Map migration dependencies
• Identify "high-touch" files requiring multiple updates
• Review migration precedent (plugin-structure.instructions.md)
• Plan archive handling (.archive/ migration)

Findings / Risks

Current State:

• 47 instruction files mixed between portable standards and repo-local guidance
• 502 references across 156 files (423 in docs, 17 in scripts, 5 in workflows, 57 in config)
• 8 broken links in CLAUDE.md pointing to wrong locations
• Unclear separation between portable and repo-local assets

Risks:

• Low risk: Files are well-isolated, audit precedent exists
• Moderate effort: 502 references require systematic updates
• High impact: Fixes broken documentation links and prevents future confusion

Remediation Actions

1. Categorization — Separate 47 files into portable (12) and repo-local (35)
2. Reference mapping — Document all 502 locations requiring updates
3. Link fixes — Correct 8 broken links in CLAUDE.md
4. Migration plan — Detail file moves and reference updates
5. Validation — Ensure CI passes after migration
6. Documentation — Update file-organisation.instructions.md with new structure

Acceptance Criteria

• Audit scope and findings documented
• All 47 instruction files categorized
• All 502 reference locations identified and logged
• Migration plan detailed with step-by-step actions
• Archive handling plan documented
• Risk assessment completed
• Estimated effort calculated

Additional Context

Related: Schema consolidation (#1292), Agents reorganization (#1293), Parent epic (#1290)
Pattern precedent: plugin-structure.instructions.md already successfully migrated from .github/instructions/ to root
Timeline: 2-3 hours for complete audit

---

Definition of Ready (DoR)

• Audit scope and goals defined
• Migration approach documented
• Dependencies mapped
• Risk assessment planned

Definition of Done (DoD)

• Audit performed and all 47 files cataloged
• All 502 reference locations documented
• Findings and risks documented in report
• Migration actions and sequence defined
• Remediation plan assigned to Phase 3
• Blocked by: None
• Blocking: Phase 3 migrations (Phase 3: Execute File Migrations & Reference Updates #1296)

[linear-code]

LS-1839

[github-actions]

⏱️ Aging and SLA annotation

• Age: 5 day(s)
• SLA state: Within SLA
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-07-29T17:26:14.278Z

Maintained by project-meta-sync workflow.

[ashleyshaw]

Duplicate: Template restructuring applied to original issues instead. See #1291, #1292, #1293, #1295 for restructured content with proper audit/documentation templates.

[github-actions]

⚠️ This issue was closed but the Definition of Done (DoD) is not complete.

Unchecked DoD items found. Please complete all checklist items before closing this issue.

To close this issue:

• ✅ Complete all DoD checklist items and check them off
• 🔁 Close the issue again

To force close this issue without completing DoD:

• Add the meta:force-close label
• The system will then allow closure

For more information on Definition of Done standards, see the issue template guide: https://github.com/lightspeedwp/.github/issues/new/choose

[github-actions]

✅ Issue checklists finalised after closure.