Skip to content

Refactor prompt library migration and label governance alignment#748

Merged
ashleyshaw merged 1 commit into
developfrom
codex/refactor-migrate-prompts-issues-736-740
Jun 1, 2026
Merged

Refactor prompt library migration and label governance alignment#748
ashleyshaw merged 1 commit into
developfrom
codex/refactor-migrate-prompts-issues-736-740

Conversation

@ashleyshaw
Copy link
Copy Markdown
Member

Summary

Validation

  • markdownlint: docs/LABELING.md, docs/LABEL_STRATEGY.md, docs/LABEL_INVENTORY.md (pass)
  • migration coverage checks: deprecation notices 46/46, move targets 38/38
  • issue/state checks completed via gh issue view and logs under active project artifacts

References

@ashleyshaw ashleyshaw merged commit e00e605 into develop Jun 1, 2026
5 of 14 checks passed
@ashleyshaw ashleyshaw deleted the codex/refactor-migrate-prompts-issues-736-740 branch June 1, 2026 20:17
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Jun 1, 2026

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 4f5acfe3-382d-4284-b8e4-7806ff4d8a86

📥 Commits

Reviewing files that changed from the base of the PR and between b9933c8 and f6833f0.

📒 Files selected for processing (116)
  • .github/labels.yml
  • .github/projects/active/refactor-migrate-prompts/INDEX.md
  • .github/projects/active/refactor-migrate-prompts/ISSUE_DRAFTS.md
  • .github/projects/active/refactor-migrate-prompts/ISSUE_EXECUTION_PLAN.md
  • .github/projects/active/refactor-migrate-prompts/ISSUE_REGISTER.md
  • .github/projects/active/refactor-migrate-prompts/RUN_LOG.md
  • .github/projects/active/refactor-migrate-prompts/artifacts/01-2-refactor-output.md
  • .github/projects/active/refactor-migrate-prompts/artifacts/01-3-migration-output.md
  • .github/projects/active/refactor-migrate-prompts/artifacts/01-4-validation-output.md
  • .github/projects/active/refactor-migrate-prompts/artifacts/issue-create-results.json
  • .github/projects/active/refactor-migrate-prompts/artifacts/migration-matrix.md
  • .github/projects/active/refactor-migrate-prompts/children/01-1-inventory-and-classify-prompts.md
  • .github/projects/active/refactor-migrate-prompts/children/01-2-refactor-org-wide-prompts-to-root-standard.md
  • .github/projects/active/refactor-migrate-prompts/children/01-3-migrate-files-update-cross-references-and-deprecations.md
  • .github/projects/active/refactor-migrate-prompts/children/01-4-validation-and-rollout.md
  • .github/projects/active/refactor-migrate-prompts/openspec-strict/README.md
  • .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-1-task-inventory-and-classify-prompts.md
  • .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-2-task-refactor-org-wide-prompts-to-root-standard.md
  • .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-3-task-migrate-files-update-references-and-deprecations.md
  • .github/projects/active/refactor-migrate-prompts/openspec-strict/children/01-4-task-validation-and-rollout-controls.md
  • .github/projects/active/refactor-migrate-prompts/openspec-strict/parents/01-epic-prompt-library-scope-and-migration-governance.md
  • .github/projects/active/refactor-migrate-prompts/openspec/README.md
  • .github/projects/active/refactor-migrate-prompts/openspec/children/01-1-task-inventory-and-classify-prompts.md
  • .github/projects/active/refactor-migrate-prompts/openspec/children/01-2-task-refactor-org-wide-prompts-to-root-standard.md
  • .github/projects/active/refactor-migrate-prompts/openspec/children/01-3-task-migrate-files-update-references-and-deprecations.md
  • .github/projects/active/refactor-migrate-prompts/openspec/children/01-4-task-validation-and-rollout-controls.md
  • .github/projects/active/refactor-migrate-prompts/openspec/parents/01-epic-prompt-library-scope-and-migration-governance.md
  • .github/projects/active/refactor-migrate-prompts/parents/01-prompt-scope-classification-and-target-architecture.md
  • .github/prompts/README.md
  • .github/prompts/add-frontmatter.prompt.md
  • .github/prompts/agents.prompt.md
  • .github/prompts/architecture-blueprint-generator.prompt.md
  • .github/prompts/breakdown-epic-arch.prompt.md
  • .github/prompts/breakdown-epic-pm.prompt.md
  • .github/prompts/breakdown-feature-implementation.prompt.md
  • .github/prompts/breakdown-feature-prd.prompt.md
  • .github/prompts/breakdown-plan.prompt.md
  • .github/prompts/breakdown-test.prompt.md
  • .github/prompts/build-agent-and-tests.prompt.md
  • .github/prompts/code-review.prompt.md
  • .github/prompts/conventional-commit.prompt.md
  • .github/prompts/create-agentsmd.prompt.md
  • .github/prompts/create-architectural-decision-record.prompt.md
  • .github/prompts/create-implementation-plan.prompt.md
  • .github/prompts/create-llms.prompt.md
  • .github/prompts/create-readme.prompt.md
  • .github/prompts/create-specification.prompt.md
  • .github/prompts/docs-from-comments.prompt.md
  • .github/prompts/docs-writeup.prompt.md
  • .github/prompts/documentation-writer.prompt.md
  • .github/prompts/finalize-agent-prompt.prompt.md
  • .github/prompts/folder-structure-blueprint-generator.prompt.md
  • .github/prompts/generate-custom-instructions-from-codebase.prompt.md
  • .github/prompts/git-flow-branch-creator.prompt.md
  • .github/prompts/github-copilot-starter.prompt.md
  • .github/prompts/inline-documentation.prompt.md
  • .github/prompts/multi-stage-dockerfile.prompt.md
  • .github/prompts/pr-description.prompt.md
  • .github/prompts/project-workflow-analysis-blueprint-generator.prompt.md
  • .github/prompts/prompt-builder.prompt.md
  • .github/prompts/python-mcp-server-generator.prompt.md
  • .github/prompts/readme-blueprint-generator.prompt.md
  • .github/prompts/remember.prompt.md
  • .github/prompts/repo-story-time.prompt.md
  • .github/prompts/reporting.prompt.md
  • .github/prompts/review-and-refactor.prompt.md
  • .github/prompts/shuffle-json-data.prompt.md
  • .github/prompts/technology-stack-blueprint-generator.prompt.md
  • .github/prompts/testing.prompt.md
  • .github/prompts/update-implementation-plan.prompt.md
  • .github/prompts/update-llms.prompt.md
  • .github/prompts/update-oo-component-documentation.prompt.md
  • .github/prompts/update-specification.prompt.md
  • .github/prompts/write-coding-standards-from-file.prompt.md
  • docs/LABELING.md
  • docs/LABEL_INVENTORY.md
  • docs/LABEL_STRATEGY.md
  • prompts/README.md
  • prompts/add-frontmatter.prompt
  • prompts/architecture-blueprint.prompt
  • prompts/code-review.prompt
  • prompts/conventional-commit.prompt
  • prompts/create-adr.prompt
  • prompts/create-agentsmd.prompt
  • prompts/create-implementation-plan.prompt
  • prompts/create-llms.prompt
  • prompts/create-readme.prompt
  • prompts/create-specification.prompt
  • prompts/dockerfile-multi-stage.prompt
  • prompts/docs-from-comments.prompt
  • prompts/documentation-writer.prompt
  • prompts/epic-breakdown-architecture.prompt
  • prompts/epic-breakdown-product.prompt
  • prompts/feature-breakdown-implementation.prompt
  • prompts/feature-breakdown-prd.prompt
  • prompts/folder-structure-blueprint.prompt
  • prompts/generate-custom-instructions-from-codebase.prompt
  • prompts/git-branch-creator.prompt
  • prompts/model-recommendation.prompt
  • prompts/plan-breakdown.prompt
  • prompts/project-workflow-analysis-blueprint.prompt
  • prompts/prompt-builder.prompt
  • prompts/python-mcp-server-generator.prompt
  • prompts/readme-blueprint.prompt
  • prompts/repo-story-time.prompt
  • prompts/reporting.prompt
  • prompts/review-and-refactor.prompt
  • prompts/shuffle-json-data.prompt
  • prompts/technology-stack-blueprint.prompt
  • prompts/test-breakdown.prompt
  • prompts/testing.prompt
  • prompts/update-implementation-plan.prompt
  • prompts/update-llms.prompt
  • prompts/update-oo-component-documentation.prompt
  • prompts/update-specification.prompt
  • prompts/write-coding-standards-from-file.prompt

📝 Walkthrough

Summary by CodeRabbit

Release Notes

  • New Features

    • Added area:quality label to categorise quality validation and QA-related issues.
    • Migrated organisation-wide prompts to canonical prompts/ directory with standardised structure.
  • Documentation

    • Updated prompt library README with migration status and canonical boundary guidance.
    • Added deprecation notices to legacy prompts in .github/prompts/ with successor references.
  • Refactor

    • Refactored 38+ prompts to standardised format with improved metadata and consistency.
    • Restructured prompt library governance and discoverability documentation.

Walkthrough

This PR executes a comprehensive refactoring and migration of a 71-prompt library from a nested .github/prompts/ directory to a canonical root prompts/ location, introducing the new area:quality label, standardising prompt metadata and structure across 47 prompts, and maintaining full governance and deprecation tracking throughout.

Changes

Prompt Library Refactor & Migration

Layer / File(s) Summary
Label taxonomy expansion
.github/labels.yml, docs/LABELING.md, docs/LABEL_INVENTORY.md, docs/LABEL_STRATEGY.md
New area:quality label added for quality validation and QA controls, positioned within the Area labels family; documentation updated to reflect the expanded label count (32 → 33).
Prompt migration governance
.github/projects/active/refactor-migrate-prompts/{INDEX,ISSUE_DRAFTS,ISSUE_EXECUTION_PLAN,ISSUE_REGISTER,RUN_LOG}.md, parents/01-*.md, children/01-*.md, openspec/ & openspec-strict/
Project index, parent epic and child task specifications, issue drafts with templates/labels/deliverables, execution plan with /opsx:propose command sequences, and both OpenSpec Strict and standard proposal pack documentation.
Migration decision matrix and implementation
.github/projects/active/refactor-migrate-prompts/artifacts/migration-matrix.md
Comprehensive mapping of 71 prompts to move/keep/merge/deprecate actions with target paths, successor mappings, and implementation notes for refactoring and deprecation-header guidance.
Migration execution evidence
.github/projects/active/refactor-migrate-prompts/artifacts/{01-2-refactor-output,01-3-migration-output,01-4-validation-output}.md, issue-create-results.json
Completion records for refactor (38 prompts refactored), migration (README/deprecation updates recorded), and validation (three validation gates passed); JSON record of created issues (EPIC-01, CHILD-01-1 through CHILD-01-4).
Legacy .github/prompts/ deprecation
.github/prompts/{*.prompt.md} (46 files), .github/prompts/README.md
Each legacy prompt marked deprecated with canonical successor path, effective date 2026-06-01, and migration reference; README updated to clarify .github-only control-plane scope and link to root canonical library.
Root prompts/ standardised refactor
prompts/{*.prompt} (47 files), prompts/README.md
Refactored prompt library with consistent YAML metadata (versioning, ownership, tags, status, stability, domain, migration source), structured instruction sections (Context/Task/Constraints/Acceptance Criteria/References), UK English constraints, and legacy source transition blocks; version bumped from 1.0.1 to 1.1.0 with migration status documentation.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

  • lightspeedwp/.github#736: The main PR implements the epic task itself—defining the prompt library scope, migration governance, and child work items as specified in that issue.
  • lightspeedwp/.github#737: Directly referenced in the PR as CHILD-01-1; the inventory and classify prompts task created from this issue.
  • lightspeedwp/.github#738: Directly implemented; the refactor-org-wide-prompts-to-root-standard task (CHILD-01-2) with 38 prompts successfully refactored.
  • lightspeedwp/.github#739: Directly implemented; the migrate-files-update-references-and-deprecations task (CHILD-01-3) with README updates and deprecation notices applied across 46 legacy prompts.
  • lightspeedwp/.github#740: Directly referenced in the run log; issue #740 (CHILD-01-4 validation task) relabelled from area:testing to the new area:quality label.

Possibly related PRs

  • lightspeedwp/.github#637: Earlier prompts consolidation effort; this PR continues that work by adding metadata standardisation, governance structure, and root-directory canonical promotion.
  • lightspeedwp/.github#418: Related label taxonomy changes; both PRs extend .github/labels.yml with new area or type labels and update corresponding documentation.
  • lightspeedwp/.github#427: Label validation infrastructure; the new area:quality label created here may be validated by schema checks added in PR #427.

Suggested labels

status:needs-review, priority:normal, area:labels, area:documentation, documentation, type:documentation, lang:md, meta:needs-changelog

Suggested reviewers

  • krugazul
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/refactor-migrate-prompts-issues-736-740

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request executes a comprehensive prompt library refactor and migration, consolidating organisation-wide reusable prompts into a root prompts/ directory while keeping GitHub control-plane specific prompts in .github/prompts/. It introduces detailed project documentation, OpenSpec proposals, execution logs, and deprecation shims for legacy prompts, alongside registering a new area:quality label. The review feedback correctly identifies a hardcoded absolute local path in the project index that needs to be repository-relative, and advises moving the migration matrix and tracking documentation to a centralized /docs/MIGRATION.md file to comply with repository guidelines.

- [Current .github prompt library](https://github.com/lightspeedwp/.github/tree/develop/.github/prompts)
- [Root prompts directory](https://github.com/lightspeedwp/.github/tree/develop/prompts)
- [Active projects directory](https://github.com/lightspeedwp/.github/tree/develop/.github/projects/active)
- `/Users/ash/.codex/worktrees/f767/.github/AGENTS.md`
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This line contains a hardcoded absolute local file path (/Users/ash/...). Absolute local paths are environment-specific and will fail for other contributors or in CI/CD environments. Please use a repository-relative path instead.

Suggested change
- `/Users/ash/.codex/worktrees/f767/.github/AGENTS.md`
- [.github/AGENTS.md](../../../AGENTS.md)

Comment thread prompts/README.md

- `prompts/` is the canonical location for organisation-wide reusable prompts.
- `.github/prompts/` is reserved for `.github` control-plane and repository-governance prompts.
- Migration authority: `.github/projects/active/refactor-migrate-prompts/artifacts/migration-matrix.md`.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

According to the repository guidelines, migration maps and notes must be documented in a central /docs/MIGRATION.md file to ensure contributors can follow migration rules across the repository. Please document the migration matrix in /docs/MIGRATION.md and update this reference.

Suggested change
- Migration authority: `.github/projects/active/refactor-migrate-prompts/artifacts/migration-matrix.md`.
- Migration authority: /docs/MIGRATION.md.
References
  1. Document migration maps and notes in a central /docs/MIGRATION.md file to ensure contributors can follow migration rules mentioned in README files across the repository.

Comment thread .github/prompts/README.md
Comment on lines +29 to +30
- Prompt migration and classification is tracked in:
- `.github/projects/active/refactor-migrate-prompts/artifacts/migration-matrix.md`
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

According to the repository guidelines, migration maps and notes must be documented in a central /docs/MIGRATION.md file. Please update this reference to point to /docs/MIGRATION.md once the migration matrix is documented there.

Suggested change
- Prompt migration and classification is tracked in:
- `.github/projects/active/refactor-migrate-prompts/artifacts/migration-matrix.md`
- Prompt migration and classification is tracked in /docs/MIGRATION.md.
References
  1. Document migration maps and notes in a central /docs/MIGRATION.md file to ensure contributors can follow migration rules mentioned in README files across the repository.

@github-actions github-actions Bot removed type:refactor Refactor or internal change type:chore Chore / small hygiene change documentation labels Jun 1, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 1, 2026

🔍 Reviewer Summary for PR #748

CI Status:success
Files changed: 116
Risk Distribution: 0 critical, 74 high, 0 medium, 42 low

Recommendations

  • ⚠️ Database migration without rollback plan documented

@ashleyshaw ashleyshaw restored the codex/refactor-migrate-prompts-issues-736-740 branch June 2, 2026 16:48
@ashleyshaw ashleyshaw deleted the codex/refactor-migrate-prompts-issues-736-740 branch June 2, 2026 18:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:documentation Docs & guides area:labels Label governance and routing lang:md Markdown content/docs meta:needs-changelog Requires a changelog entry before merge priority:normal Default priority status:needs-review Awaiting code review type:documentation Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant