docs(#685): Add type-to-project-field mapping and decision tree#700
Conversation
|
Warning Review limit reached
More reviews will be available in 28 minutes and 26 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthroughThis PR consolidates GitHub label taxonomy documentation and governance. It extends the issue type system from 25 to 32 types, updates automation rules for AI and Automation branch prefixes, refactors label protection policies, and introduces comprehensive strategy and inventory documentation with type selection guidance. ChangesLabel Governance and Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request standardizes the repository's GitHub governance, templates, and automation configurations by updating issue and PR templates, saved replies, and project roadmaps, while introducing new configurations for Mergify, codespell, and label governance. The review feedback highlights several critical issues: configuration discrepancies in issue-fields.yml, conflicting ESLint rules for ES modules in .eslint.config.cjs, redundant auto-merge rules in mergify.yml, and the use of legacy labels in the label governance policy. Additionally, missing branch mappings for ai/ and automation/ were identified in labeler.yml, and multiple Markdown files were flagged for containing duplicate footer blocks that violate the repository's single-footer standard.
| enabled_issue_types: | ||
| - Bug | ||
| - Feature | ||
| - Task | ||
| - Epic | ||
| - Maintenance | ||
| - Chore | ||
| - Research | ||
| - Support | ||
| - Documentation | ||
| - Release |
There was a problem hiding this comment.
There is a discrepancy between the enabled_issue_types list and the target values defined in project_field_mappings.Type. Specifically, Design, Automation, and Integration are used as target values in the mapping but are missing from enabled_issue_types. Conversely, Epic, Maintenance, and Support are enabled but are collapsed into Task or Chore in the mapping, meaning they will never be assigned. Please align enabled_issue_types with the 10 mapped target values.
enabled_issue_types:
- Bug
- Feature
- Task
- Release
- Design
- Chore
- Automation
- Integration
- Research
- Documentation| files: ["**/*.js"], | ||
| ignores: [ | ||
| "**/*.mjs", | ||
| "scripts/**/*.js", | ||
| ".github/agents/**/*.js", |
There was a problem hiding this comment.
The CommonJS files block matches all **/*.js files but only ignores a subset of the ES module paths. This causes files under .github/metrics/, .github/scripts/, and docs/ai/ to be matched by both the CommonJS and ES Modules blocks, leading to conflicting sourceType configurations. Please add the remaining ES module paths to the ignores array of the CommonJS block.
files: ["**/*.js"],
ignores: [
"**/*.mjs",
"scripts/**/*.js",
".github/agents/**/*.js",
".github/metrics/**/*.js",
".github/scripts/**/*.js",
"docs/ai/**/*.js",
],
| - name: Auto-merge Dependabot dependency updates on develop | ||
| conditions: | ||
| - author=dependabot[bot] | ||
| - base=develop | ||
| - label=area:dependencies | ||
| - check-success=check | ||
| - check-success=lint | ||
| - check-success=validate | ||
| - -draft | ||
| actions: | ||
| merge: | ||
| method: squash |
There was a problem hiding this comment.
The first rule for auto-merging Dependabot updates matches all Dependabot PRs on develop with the area:dependencies label. This overlaps with the second rule for security updates, making the second rule redundant. To make them mutually exclusive and ensure proper rule evaluation, please explicitly exclude security updates from the first rule using - -label=meta:dependabot-security.
- name: Auto-merge Dependabot dependency updates on develop
conditions:
- author=dependabot[bot]
- base=develop
- label=area:dependencies
- -label=meta:dependabot-security
- check-success=check
- check-success=lint
- check-success=validate
- -draft
actions:
merge:
method: squash| never_delete_labels: | ||
| - a11y | ||
| - audit | ||
| - automation | ||
| - bats | ||
| - blocker | ||
| - bug | ||
| - checklist | ||
| - ci | ||
| - comp:help-tabs | ||
| - configuration | ||
| - codex | ||
| - cross-reference | ||
| - css | ||
| - dependencies | ||
| - documentation | ||
| - github_actions | ||
| - governance | ||
| - javascript | ||
| - js | ||
| - lang:javascript | ||
| - maintenance | ||
| - meta | ||
| - meta:duplicate | ||
| - onboarding | ||
| - package.json | ||
| - path-resolution | ||
| - php | ||
| - quickstart | ||
| - security | ||
| - standards | ||
| - test |
There was a problem hiding this comment.
The never_delete_labels list contains legacy/unprefixed label names (e.g., bug, automation, test, a11y, security, maintenance, documentation, audit, ci, dependencies, javascript, js, php, css) instead of the active canonical prefixed labels (e.g., type:bug, type:automation, type:test, type:a11y, type:security, type:maintenance, type:documentation, type:audit, area:ci, area:dependencies, lang:js, lang:php, lang:css). When destructive cleanup is enabled, this could lead to the accidental deletion of active canonical labels. Please update the list to include the canonical prefixed labels.
never_delete_labels:
- type:bug
- type:feature
- type:documentation
- type:task
- type:release
- type:design
- type:chore
- type:refactor
- type:maintenance
- type:automation
- type:test
- type:ai-ops
- type:ci
- type:build
- type:integration
- type:dependency
- type:compatibility
- type:research
- type:investigation
- type:security
- type:performance
- type:qa
- type:audit
- type:epic
- type:question
- type:support
- type:content-modelling
- type:story
- type:review
- area:ci
- area:dependencies
- area:labels
- area:security
- area:a11y
- area:documentation
- area:tests
- area:scripts
- area:assets
- area:woocommerce
- lang:php
- lang:js
- lang:css
- lang:md
- lang:json
- lang:yaml
- comp:help-tabs
- meta:duplicate
- meta:dependabot-security| "type:question": | ||
| head-branch: ["^question/.*"] | ||
| "type:support": | ||
| head-branch: ["^support/.*"] |
There was a problem hiding this comment.
The branch prefixes ai/ and automation/ are used in the repository (as documented in NEXT_ISSUES_EXECUTION_PLAN.md), but they are not mapped to their corresponding issue types in labeler.yml. Please add mappings for type:ai-ops and type:automation to ensure automatic labeling works for these branches.
"type:question":
head-branch: ["^question/.*"]
"type:support":
head-branch: ["^support/.*"]
"type:ai-ops":
head-branch: ["^ai/.*"]
"type:automation":
head-branch: ["^automation/.*"]References
- Documentation and governance files in the
docs/directory must use UPPERCASE naming with underscores (e.g.,GOVERNANCE_REVISION_LOG.md), as the lowercase-with-hyphens naming convention applies to other asset types and not todocs/files.
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | ||
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) | ||
|
|
||
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | ||
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) | ||
|
|
||
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | ||
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) |
There was a problem hiding this comment.
The footer block is duplicated three times at the end of this file. Please remove the duplicate blocks to adhere to the single-footer standard defined in FOOTER_REMEDIATION_GUIDE.md.
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | |
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) | |
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | |
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) | |
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | |
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) | |
| *Maintained with ❤️ by the 🚀 LightSpeedWP Automation Team* | |
| [Org Profile](https://github.com/lightspeedwp/.github/tree/main/profile) |
| *Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!* | ||
| [Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors) | ||
|
|
||
| **❓ Questions?** [Open an issue](https://github.com/lightspeedwp/.github/issues/new), start a [Discussion](https://github.com/orgs/lightspeedwp/discussions), or contact [support@lightspeedwp.agency](mailto:support@lightspeedwp.agency) | ||
| *Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!* | ||
| [Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors) |
There was a problem hiding this comment.
The footer block is duplicated twice at the end of this file. Please remove the duplicate block to adhere to the single-footer standard defined in FOOTER_REMEDIATION_GUIDE.md.
| *Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!* | |
| [Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors) | |
| **❓ Questions?** [Open an issue](https://github.com/lightspeedwp/.github/issues/new), start a [Discussion](https://github.com/orgs/lightspeedwp/discussions), or contact [support@lightspeedwp.agency](mailto:support@lightspeedwp.agency) | |
| *Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!* | |
| [Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors) | |
| *Built by 🧱 LightSpeedWP with ☕, 🚀, and open-source spirit!* | |
| [Contributors](https://github.com/lightspeedwp/lsx-demo-theme/graphs/contributors) |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) |
There was a problem hiding this comment.
The footer block is duplicated seven times at the end of this file. Please remove the duplicate blocks to adhere to the single-footer standard defined in FOOTER_REMEDIATION_GUIDE.md.
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) | ||
|
|
||
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | ||
| [Contact](https://lightspeedwp.agency/contact) |
There was a problem hiding this comment.
The footer block is duplicated twice at the end of this file. Please remove the duplicate block to adhere to the single-footer standard defined in FOOTER_REMEDIATION_GUIDE.md.
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) | |
| *Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP* | |
| [Contact](https://lightspeedwp.agency/contact) |
| _Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_ | ||
|
|
||
| _Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_ |
There was a problem hiding this comment.
The footer block is duplicated twice at the end of this file. Please remove the duplicate block to adhere to the single-footer standard defined in FOOTER_REMEDIATION_GUIDE.md.
| _Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_ | |
| _Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_ | |
| _Docs signed by 🤖 Copilot for LightSpeedWP – always fresh!_ |
- Fix issue-fields.yml: Align enabled_issue_types with 10 project field values (Design, Automation, Integration) - Fix mergify.yml: Exclude security updates from first Dependabot rule to avoid redundancy - Fix label-governance-policy.yml: Replace legacy labels with canonical prefixed labels for safe cleanup - Fix labeler.yml: Add missing branch mappings for type:ai-ops (ai/*) and type:automation (automation/*) - Fix duplicate footer blocks: Remove duplicates in 6 Markdown files to adhere to single-footer standard https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d423921aef
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "type:ai-ops": | ||
| head-branch: ["^ai/.*"] | ||
| "type:automation": | ||
| head-branch: ["^automation/.*"] |
There was a problem hiding this comment.
For PRs opened from the newly recognised ai/* or automation/* branches, these rules add a type label but the separate status:needs-review rule above does not include either prefix. The in-repo labeler only applies labels whose own branch pattern matches, so those PRs will be left without the review status label and downstream project sync falls back to the generic default instead of marking them ready for review.
Useful? React with 👍 / 👎.
| - `priority:high` — Important feature or significant bug; impacts many users | ||
| - `priority:medium` — Normal feature; moderate impact; scheduled work | ||
| - `priority:normal` — Default; no special urgency | ||
| - `priority:low` — Nice-to-have enhancement; can be deferred |
There was a problem hiding this comment.
This new strategy section documents priority:high, priority:medium, and priority:low, but the canonical .github/labels.yml priority set is priority:critical, priority:important, priority:normal, and priority:minor. If triagers follow this guidance they will apply or create non-canonical labels, which label sync treats as extra label drift rather than valid priorities.
Useful? React with 👍 / 👎.
…trategy - labeler.yml: Add ai/* and automation/* branch prefixes to status:needs-review rule so PRs from new AI Ops and Automation branches get the review status label (fixes Codex P2 comment: ensure type labels have corresponding status label) - LABEL_STRATEGY.md: Align priority label names with canonical set (priority:critical, priority:important, priority:normal, priority:minor) instead of non-canonical (critical, high, medium, low) (fixes Codex P2 comment: ensure documentation matches canonical labels.yml) https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
There was a problem hiding this comment.
Pull request overview
This PR updates governance documentation and canonical label/project field configuration for the .github control-plane repository, focused on issue type mappings, label inventory, and triage automation.
Changes:
- Adds label strategy and inventory documentation, including family counts, colour references, and usage guidance.
- Expands issue type/project field mapping documentation and updates project field options.
- Cleans duplicate README footers and adjusts label automation/Mergify dependency rules.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
docs/LABEL_STRATEGY.md |
Adds label taxonomy, governance, assignment, and reference documentation. |
docs/LABEL_INVENTORY.md |
Adds a full label inventory grouped by semantic family. |
docs/ISSUE_TYPES.md |
Adds type-to-project-field mapping and a type selection decision tree. |
docs/ISSUE_FIELDS.md |
Updates the master type-to-project-field mapping table. |
.github/issue-fields.yml |
Updates enabled project field type values. |
.github/labeler.yml |
Adds branch mappings for AI and automation work. |
.github/label-governance-policy.yml |
Updates protected labels for governance cleanup. |
.github/mergify.yml |
Separates general Dependabot updates from security-labelled ones. |
.github/README.md |
Removes duplicated footer content. |
.github/PULL_REQUEST_TEMPLATE/README.md |
Removes duplicated footer content. |
.github/ISSUE_TEMPLATE/README.md |
Removes duplicated footer content. |
.github/projects/README.md |
Removes duplicated footer content. |
.github/metrics/README.md |
Removes duplicated footer content. |
.github/instructions/.archive/README.md |
Removes duplicated footer content. |
|
|
||
| ## Type-to-Project-Field Mapping | ||
|
|
||
| All 27 issue types map to 10 project field values for organization and automation. This mapping preserves semantic distinctions whilst grouping related workflows. |
| | **Integration** | Integration | External system integrations, dependencies | type:integration, type:dependency | | ||
|
|
||
| **Total Coverage**: All 25 types mapped; 0 unmapped types | ||
| ### 1.1 Complete Type Mapping (27 Types → 10 Project Fields) |
| | Family | Count | Purpose | Key Labels | | ||
| | --- | --- | --- | --- | | ||
| | **Status** | 20 | Workflow state and blockers | needs-planning, ready, in-progress, needs-review, blocked | | ||
| | **Priority** | 5 | Urgency and impact | critical, high, medium, low, normal | |
|
|
||
| --- | ||
|
|
||
| ## Priority Labels (5) |
|
|
||
| --- | ||
|
|
||
| ## Area Labels (25) |
| - [`.github/labels.yml`](./.github/labels.yml) — Canonical label definitions | ||
| - [`.github/labeler.yml`](./.github/labeler.yml) — Automated labeling rules |
| - [LightSpeed Coding Standards](./instructions/coding-standards.instructions.md) | ||
| - [LightSpeed Accessibility Standards](./instructions/a11y.instructions.md) |
| - [`docs/LABEL_COLOR_STRATEGY.md`](./LABEL_COLOR_STRATEGY.md) — Detailed colour specifications | ||
| - [`docs/ISSUE_TYPES.md`](./ISSUE_TYPES.md) — Type definitions and decision tree | ||
| - [`docs/ISSUE_FIELDS.md`](./ISSUE_FIELDS.md) — Project field mappings | ||
| - [`.github/labels.yml`](./.github/labels.yml) — Canonical label definitions |
| - Use `priority:important` for planned quarterly work | ||
| - Use `priority:minor` for backlog items without committed timeline | ||
|
|
||
| ### 2.3 Type Labels (25 Labels) |
- ISSUE_FIELDS.md: Updated heading and summary from 25/27 types to 32 types - LABEL_STRATEGY.md: Fixed priority count from 5 to 4 (canonical labels: critical, important, normal, minor) - LABEL_STRATEGY.md: Updated type count from 25 to 32 - LABEL_STRATEGY.md: Fixed non-canonical type names (type:accessibility → type:a11y, type:improvement → type:improve) - LABEL_STRATEGY.md: Fixed relative paths to .github/ and instructions/ files (use ../ prefix) - LABEL_INVENTORY.md: Fixed priority count from 5 to 4 - LABEL_INVENTORY.md: Fixed type count from 27 to 32 - LABEL_INVENTORY.md: Fixed area count from 25 to 32 - LABEL_INVENTORY.md: Fixed relative path to .github/labels.yml https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
coderabbitai
Bot
added
priority:normal
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/ISSUE_FIELDS.md (2)
1-22:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFrontmatter is missing required metadata keys
This file still needs
statusandlanguagein frontmatter to meet the docs schema baseline.As per coding guidelines, "All
.mdfiles in this repository should include YAML frontmatter with required fields: file_type, title, description, version, last_updated, owners, tags, status, stability, domain" and "Specify language in frontmatter".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/ISSUE_FIELDS.md` around lines 1 - 22, The YAML frontmatter in ISSUE_FIELDS.md is missing required keys `status` and `language`; update the top-matter to include both (e.g., status: stable/draft and language: en) alongside the existing keys (file_type, title, description, version, last_updated, owners, tags, stability, domain) so the document conforms to the docs schema baseline; ensure valid YAML formatting and update last_updated if appropriate.
176-176:⚠️ Potential issue | 🟠 Major | ⚡ Quick winStale “25 types” references conflict with the new 32-type mapping
The document now maps 32 canonical types, but these lines still refer to 25. Please normalise these references so migration and governance guidance stays consistent.
As per coding guidelines, "
**/docs/**/*.md: ... Confirm documentation is up to date, accurate, and cross-referenced."Also applies to: 277-283, 401-402
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/ISSUE_FIELDS.md` at line 176, Update the stale "25 types" references to "32 types" so the document's mappings are consistent: replace the phrase in the table row containing "**Type** | single_select" (the row that currently ends with "**Expanded mapping** — all 25 types covered") and the other occurrences around the blocks indicated (the text spans near lines shown in the review, e.g., the sections covering the canonical type mapping and migration/governance notes) to read "32 types" (or "all 32 types covered") and confirm the wording is identical in the related paragraphs referenced (the sections around the other occurrences at the later ranges) to keep migration and governance guidance consistent with the new 32-type mapping.docs/ISSUE_TYPES.md (1)
1-23:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFrontmatter schema mismatch (
domain/language)Tiny metadata snag: this frontmatter uses
categorybut the repo rule requiresdomain, and it also needs an explicitlanguagefield.As per coding guidelines, "All
.mdfiles in this repository should include YAML frontmatter with required fields: file_type, title, description, version, last_updated, owners, tags, status, stability, domain" and "Specify language in frontmatter".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/ISSUE_TYPES.md` around lines 1 - 23, Frontmatter is missing the required domain and language keys: replace the existing "category: governance" key with "domain: governance" (or add "domain" with the same value) and add an explicit "language" key (e.g., "language: en" or "language: en-US") to the YAML frontmatter at the top of the file; ensure other required keys (file_type, title, description, version, last_updated, owners, tags, status, stability) remain unchanged and the frontmatter stays valid YAML.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/ISSUE_TYPES.md`:
- Around line 86-103: The doc currently claims "All 27 issue types" and lists a
table under "Project Field" that doesn't match the canonical Type (32) label
set; update the opening sentence to reference 32 issue types, revise the table
rows (the Issue Types column for each Project Field) to include any
missing/renamed types from the canonical inventory, and ensure the total count
in the prose matches the sum of types in the table; use the canonical list
defined elsewhere (the Type (32) label set) as the source of truth and keep the
link to ISSUE_FIELDS.md#2-mapping-rationale intact.
- Around line 111-177: Summary: The decision-tree fenced code block lacks an
explicit language tag; update the opening fence to include a language (e.g.,
`text`). Edit the fenced block that begins with "START: What's the nature of the
work?" in ISSUE_TYPES.md and change the opening ``` to ```text (leave the
content and closing fence unchanged) so the markdown uses an explicit language
tag per the coding guidelines.
In `@docs/LABEL_INVENTORY.md`:
- Around line 323-327: The summary counts in the stats table (entries "Priority
| 5", "Type | 27", "Area | 31") are inconsistent with the earlier headings
"Priority (4)", "Type Labels (32)", and "Area Labels (32)"; update the document
so the numeric totals match: reconcile and correct either the headings or the
stats table to reflect the true counts, adjust the counts for Priority, Type,
and Area everywhere they appear (search for "Priority (", "Type Labels (", "Area
Labels (" and the stats table rows "Priority |", "Type |", "Area |"), and verify
cross-references in the rest of docs to ensure the labels/totals are consistent.
- Around line 1-22: The YAML frontmatter in LABEL_INVENTORY.md is missing
required metadata keys; add the `status` and `language` fields to the existing
frontmatter (alongside existing keys like file_type, title, description,
version, last_updated, owners, tags, stability, domain) so the document
satisfies the repo schema; choose an appropriate value for `status` (e.g.,
"stable" or "draft") and a valid language code for `language` (e.g., "en" or
"en-US") and ensure the new keys are placed in the top YAML block.
- Around line 46-66: The image alt text currently uses color codes like "BFD4F2"
for label swatches (e.g., the rows for labels such as `status:needs-planning`,
`status:ready`, `status:in-progress`, etc.); replace those color-code alts with
meaningful purpose-driven text (e.g., "status:needs-planning swatch" or "Status:
Ready (green) badge") or use an empty alt ("") for purely decorative swatches,
updating every markdown image entry listed (including the other ranges called
out) so alt attributes describe the label's purpose rather than its color code.
In `@docs/LABEL_STRATEGY.md`:
- Around line 111-177: The untyped fenced code block containing the decision
tree (the "decision tree" fence shown between the Primary/Specialised Types and
Assignment Rules) needs an explicit language tag; update that fenced block in
LABEL_STRATEGY.md to use a language identifier (e.g., add ```text or ```markdown
or another appropriate tag) so markdown linting and rendering are deterministic
and follow the guideline to "Use fenced code blocks with explicit language
tags."
- Around line 1-22: The frontmatter block in LABEL_STRATEGY.md is missing the
required keys `status` and `language`; update the YAML frontmatter at the top of
the file (the block containing title, file_type, version, etc.) to add a
`status` field (e.g., "draft" or "stable") and a `language` field (e.g., "en" or
"en-US") so it conforms to the repository schema that requires file_type, title,
description, version, last_updated, owners, tags, status, stability, and domain.
---
Outside diff comments:
In `@docs/ISSUE_FIELDS.md`:
- Around line 1-22: The YAML frontmatter in ISSUE_FIELDS.md is missing required
keys `status` and `language`; update the top-matter to include both (e.g.,
status: stable/draft and language: en) alongside the existing keys (file_type,
title, description, version, last_updated, owners, tags, stability, domain) so
the document conforms to the docs schema baseline; ensure valid YAML formatting
and update last_updated if appropriate.
- Line 176: Update the stale "25 types" references to "32 types" so the
document's mappings are consistent: replace the phrase in the table row
containing "**Type** | single_select" (the row that currently ends with
"**Expanded mapping** — all 25 types covered") and the other occurrences around
the blocks indicated (the text spans near lines shown in the review, e.g., the
sections covering the canonical type mapping and migration/governance notes) to
read "32 types" (or "all 32 types covered") and confirm the wording is identical
in the related paragraphs referenced (the sections around the other occurrences
at the later ranges) to keep migration and governance guidance consistent with
the new 32-type mapping.
In `@docs/ISSUE_TYPES.md`:
- Around line 1-23: Frontmatter is missing the required domain and language
keys: replace the existing "category: governance" key with "domain: governance"
(or add "domain" with the same value) and add an explicit "language" key (e.g.,
"language: en" or "language: en-US") to the YAML frontmatter at the top of the
file; ensure other required keys (file_type, title, description, version,
last_updated, owners, tags, status, stability) remain unchanged and the
frontmatter stays valid YAML.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 033921b4-e70e-426c-b410-495706947cdc
📒 Files selected for processing (14)
.github/ISSUE_TEMPLATE/README.md.github/PULL_REQUEST_TEMPLATE/README.md.github/README.md.github/instructions/.archive/README.md.github/issue-fields.yml.github/label-governance-policy.yml.github/labeler.yml.github/mergify.yml.github/metrics/README.md.github/projects/README.mddocs/ISSUE_FIELDS.mddocs/ISSUE_TYPES.mddocs/LABEL_INVENTORY.mddocs/LABEL_STRATEGY.md
💤 Files with no reviewable changes (6)
- .github/instructions/.archive/README.md
- .github/ISSUE_TEMPLATE/README.md
- .github/projects/README.md
- .github/PULL_REQUEST_TEMPLATE/README.md
- .github/metrics/README.md
- .github/README.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{md,mdx,yaml,yml}
📄 CodeRabbit inference engine (CLAUDE.md)
Use UK English throughout (optimise, organisation, colour, behaviour)
Files:
docs/LABEL_STRATEGY.mddocs/ISSUE_FIELDS.mddocs/LABEL_INVENTORY.mddocs/ISSUE_TYPES.md
**/*.md
📄 CodeRabbit inference engine (.github/instructions/markdown.instructions.md)
**/*.md: Use one H1 (#) per file; keep heading levels sequential (never skip from H2 to H4)
Use fenced code blocks with explicit language tags (bash,yaml,markdown, etc.)
Keep links relative for in-repo files; verify they resolve before merging
Use1.for ordered lists and-for unordered lists
Keep all wording in UK English (optimise, organisation, colour, behaviour, analyse)
Do not add areferences:frontmatter field — use inline links or a footer section instead
Blank lines before and after headings, code blocks, and block-level elements
Maximum line length: 120 characters (soft limit; prefer wrapping at natural sentence boundaries)
All.mdfiles in this repository should include YAML frontmatter with required fields: file_type, title, description, version, last_updated, owners, tags, status, stability, domain
Every image (![]()) must have descriptive alt text explaining the image's purpose, not its appearance. Empty alt (![ ]()) is valid only for purely decorative images
Link text must describe the destination — never use 'click here', 'read more', or bare URLs as visible text
Every table must have a header row (| Header |). Avoid merged cells
Use headings to communicate document structure, not for visual styling
Do not rely on colour alone to convey information in diagrams or callout blocks
Mermaid diagrams must includeaccTitleandaccDescrattributes for accessibility
Specify language in frontmatter; use plain language, avoid jargon where possibleFollow the Frontmatter Schema defined in schema/frontmatter.schema.json for all documentation files
Files:
docs/LABEL_STRATEGY.mddocs/ISSUE_FIELDS.mddocs/LABEL_INVENTORY.mddocs/ISSUE_TYPES.md
**/docs/**/*.md
⚙️ CodeRabbit configuration file
**/docs/**/*.md: Review documentation files:
- Ensure markdown is linted and formatted per project style guides.
- Flag illogical folder structures, file naming, or misplaced content.
- Confirm documentation is up to date, accurate, and cross-referenced.
- Ensure accessibility (heading hierarchy, alt text for images, UK English).
Files:
docs/LABEL_STRATEGY.mddocs/ISSUE_FIELDS.mddocs/LABEL_INVENTORY.mddocs/ISSUE_TYPES.md
🪛 LanguageTool
docs/LABEL_STRATEGY.md
[uncategorized] ~29-~29: The official name of this software platform is spelled with a capital “H”.
Context: ...LightSpeed Team Reference Config: .github/labels.yml, .github/labeler.yml ---...
(GITHUB)
[uncategorized] ~35-~35: The official name of this software platform is spelled with a capital “H”.
Context: ...nsive label strategy for the LightSpeed .github repository. It defines the taxonomy of...
(GITHUB)
[style] ~124-~124: Would you like to use the Oxford spelling “Specialized”? The spelling ‘Specialised’ is also correct.
Context: ...n— Bots, actions, scripts, tooling **Specialised Types** (16 additional): -type:epic`...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~126-~126: Loose punctuation mark.
Context: ... Types** (16 additional): - type:epic, type:story — Narrative/planning - `ty...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~150-~150: Would you like to use the Oxford spelling “localized”? The spelling ‘localised’ is also correct.
Context: ...s**: - Assign area labels when work is localised to a component - Multiple area labels a...
(OXFORD_SPELLING_Z_NOT_S)
[misspelling] ~164-~164: This word is normally spelled with a hyphen.
Context: ...e change - Omit if changes are platform/framework agnostic ### 2.6 Discussion Labels (7 Labels) ...
(EN_COMPOUNDS_FRAMEWORK_AGNOSTIC)
[style] ~168-~168: Would you like to use the Oxford spelling “Categorize”? The spelling ‘Categorise’ is also correct.
Context: ...cussion Labels (7 Labels) Purpose: Categorise GitHub Discussions (not applicable to i...
(OXFORD_SPELLING_Z_NOT_S)
[typographical] ~265-~265: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...STRATEGY.md`) 3. Write description: 1-2 sentences explaining when to use (not w...
(HYPHEN_TO_EN)
[uncategorized] ~267-~267: The official name of this software platform is spelled with a capital “H”.
Context: ...it is) 4. Update files: - Add to .github/labels.yml with name, colour, descript...
(GITHUB)
[uncategorized] ~268-~268: The official name of this software platform is spelled with a capital “H”.
Context: ...h name, colour, description - Update .github/labeler.yml if it affects PR/branch la...
(GITHUB)
[uncategorized] ~277-~277: The official name of this software platform is spelled with a capital “H”.
Context: ...3. Remove from configs: Remove from .github/labels.yml and .github/labeler.yml 4...
(GITHUB)
docs/LABEL_INVENTORY.md
[style] ~47-~47: Would you like to use the Oxford spelling “categorization”? The spelling ‘categorisation’ is also correct.
Context: ...eeds triage | Issue needs investigation/categorisation | | status:ready | 
[style] ~99-~99: Would you like to use the Oxford spelling “optimization”? The spelling ‘optimisation’ is also correct.
Context: ... improvement | Task | Speed, efficiency optimisation | | type:a11y | 
[style] ~137-~137: Would you like to use the Oxford spelling “categorizing”? The spelling ‘categorising’ is also correct.
Context: ...-- ## Release Scope Labels (4) Labels categorising release impact. | Label | Color | Desc...
(OXFORD_SPELLING_Z_NOT_S)
[style] ~181-~181: Would you like to use the Oxford spelling “Internationalization”? The spelling ‘Internationalisation’ is also correct.
Context: ...ceholder.com/20/C5DEF5?text=+) C5DEF5 | Internationalisation | | area:ci | 
[uncategorized] ~252-~252: The official name of this content management system is spelled with a capital “P”.
Context: ...r | Description | | --- | --- | --- | | compat:wordpress | 
[style] ~302-~302: Would you like to use the Oxford spelling “categorization”? The spelling ‘categorisation’ is also correct.
Context: ...bels (7) Labels for GitHub Discussions categorisation (not for issues/PRs). | Label | Color ...
(OXFORD_SPELLING_Z_NOT_S)
[style] ~306-~306: Using many exclamation marks might seem excessive (in this case: 150 exclamation marks for a text that’s 22765 characters long)
Context: ...- | --- | | discussion:announcement | FBCA04 | Official announcements | |
discussion:showcase | 0E8A16 | Show & Tell | |
discussion:community | 6f42c1 | Community/general | |
discussion:feedback | 1d76db | Feedback/suggestions | |
discussion:support | d73a4a | Support/troubleshooting | |
discussion:sponsorship | f9d0c4 | Sponsorship/funding | |
discussion:partnership | 
🔇 Additional comments (4)
.github/issue-fields.yml (1)
165-169: LGTM!.github/label-governance-policy.yml (1)
13-65: LGTM!.github/labeler.yml (1)
11-12: LGTM!Also applies to: 42-45
.github/mergify.yml (1)
7-7: LGTM!
| ## Type-to-Project-Field Mapping | ||
|
|
||
| All 27 issue types map to 10 project field values for organization and automation. This mapping preserves semantic distinctions whilst grouping related workflows. | ||
|
|
||
| | Project Field | Issue Types | When to Use | | ||
| | --- | --- | --- | | ||
| | **Bug** | type:bug | Broken/incorrect behaviour, errors, regressions | | ||
| | **Feature** | type:feature, type:improve, type:enhancement | Net-new capabilities or enhancements to existing features | | ||
| | **Design** | type:design, type:a11y, type:ui | Design artefacts, specifications, accessibility work | | ||
| | **Documentation** | type:documentation | Docs, guides, knowledge base, onboarding materials | | ||
| | **Chore** | type:chore, type:refactor, type:maintenance | Maintenance, code quality, housekeeping, updates | | ||
| | **Automation** | type:automation, type:test, type:build, type:ai-ops, type:ci | Workflow automation, testing, CI/CD, tooling, agents | | ||
| | **Research** | type:research, type:investigation | Discovery, investigation, proof-of-concepts, spikes | | ||
| | **Integration** | type:integration, type:dependency, type:compatibility | External systems, dependencies, cross-platform work | | ||
| | **Release** | type:release | Release management, deployment, version coordination | | ||
| | **Task** | type:task, type:epic, type:story, type:review, type:audit, type:question, type:support, type:content-modelling, type:performance, type:security | Catch-all for unspecified work, narratives, audits, and specialized domains | | ||
|
|
||
| **Mapping Rationale**: See [ISSUE_FIELDS.md](./ISSUE_FIELDS.md#2-mapping-rationale) for detailed reasoning on why these 27 types are grouped into 10 project field values instead of collapsing to 4 generic options. |
There was a problem hiding this comment.
Type mapping count is inconsistent with canonical taxonomy
This section says “All 27 issue types”, but the governance docs in this PR establish a canonical 32 type:* set. Please update the table/sentence so contributor guidance matches canonical mapping.
As per coding guidelines, "Use as the canonical reference for label families and especially the Type (32) label set ... Ensure any new/renamed/added type labels referenced by ISSUE_TYPES/ISSUE_FIELDS are consistent with the inventory’s list and family counts."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/ISSUE_TYPES.md` around lines 86 - 103, The doc currently claims "All 27
issue types" and lists a table under "Project Field" that doesn't match the
canonical Type (32) label set; update the opening sentence to reference 32 issue
types, revise the table rows (the Issue Types column for each Project Field) to
include any missing/renamed types from the canonical inventory, and ensure the
total count in the prose matches the sum of types in the table; use the
canonical list defined elsewhere (the Type (32) label set) as the source of
truth and keep the link to ISSUE_FIELDS.md#2-mapping-rationale intact.
- Add missing frontmatter fields (status, language) to ISSUE_FIELDS.md, ISSUE_TYPES.md, LABEL_STRATEGY.md, and LABEL_INVENTORY.md - Update stale '25 types' references to '32 types' throughout ISSUE_FIELDS.md (line 143, 152, 176, 277, 282, 401) - Replace image alt text using color codes with descriptive color names in LABEL_INVENTORY.md (20+ locations) - Fix frontmatter schema in ISSUE_TYPES.md (category→domain, add language field) - Add explicit language tag (text) to fenced code block in ISSUE_TYPES.md (decision tree) - Reconcile stats table counts in LABEL_INVENTORY.md (Priority 5→4, Type 27→32, Area 31→32) https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
…pes and Fields documentation Complete Wave 5.2.4 requirements: - ISSUE_TYPES.md: Add explicit type-to-project-field mapping table showing all 27 types grouped by 10 project fields - ISSUE_TYPES.md: Add comprehensive decision tree for selecting appropriate issue types - ISSUE_FIELDS.md: Enhance with complete master mapping table (32 types → 10 fields) for quick reference This provides clear guidance for contributors on: 1. How types map to project fields for automation 2. Step-by-step decision process for type selection 3. Consolidated reference table showing all types and their mappings Addresses Issue #685 acceptance criteria. https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
Create comprehensive label governance and reference documents: - docs/LABEL_STRATEGY.md: 7 semantic label families, color strategy, governance rules - docs/LABEL_INVENTORY.md: Complete inventory of all 150+ labels organized by 14 families Completes label documentation portion of Issue #685 acceptance criteria. https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Fix issue-fields.yml: Align enabled_issue_types with 10 project field values (Design, Automation, Integration) - Fix mergify.yml: Exclude security updates from first Dependabot rule to avoid redundancy - Fix label-governance-policy.yml: Replace legacy labels with canonical prefixed labels for safe cleanup - Fix labeler.yml: Add missing branch mappings for type:ai-ops (ai/*) and type:automation (automation/*) - Fix duplicate footer blocks: Remove duplicates in 6 Markdown files to adhere to single-footer standard https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
…trategy - labeler.yml: Add ai/* and automation/* branch prefixes to status:needs-review rule so PRs from new AI Ops and Automation branches get the review status label (fixes Codex P2 comment: ensure type labels have corresponding status label) - LABEL_STRATEGY.md: Align priority label names with canonical set (priority:critical, priority:important, priority:normal, priority:minor) instead of non-canonical (critical, high, medium, low) (fixes Codex P2 comment: ensure documentation matches canonical labels.yml) https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- ISSUE_FIELDS.md: Updated heading and summary from 25/27 types to 32 types - LABEL_STRATEGY.md: Fixed priority count from 5 to 4 (canonical labels: critical, important, normal, minor) - LABEL_STRATEGY.md: Updated type count from 25 to 32 - LABEL_STRATEGY.md: Fixed non-canonical type names (type:accessibility → type:a11y, type:improvement → type:improve) - LABEL_STRATEGY.md: Fixed relative paths to .github/ and instructions/ files (use ../ prefix) - LABEL_INVENTORY.md: Fixed priority count from 5 to 4 - LABEL_INVENTORY.md: Fixed type count from 27 to 32 - LABEL_INVENTORY.md: Fixed area count from 25 to 32 - LABEL_INVENTORY.md: Fixed relative path to .github/labels.yml https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Add missing frontmatter fields (status, language) to ISSUE_FIELDS.md, ISSUE_TYPES.md, LABEL_STRATEGY.md, and LABEL_INVENTORY.md - Update stale '25 types' references to '32 types' throughout ISSUE_FIELDS.md (line 143, 152, 176, 277, 282, 401) - Replace image alt text using color codes with descriptive color names in LABEL_INVENTORY.md (20+ locations) - Fix frontmatter schema in ISSUE_TYPES.md (category→domain, add language field) - Add explicit language tag (text) to fenced code block in ISSUE_TYPES.md (decision tree) - Reconcile stats table counts in LABEL_INVENTORY.md (Priority 5→4, Type 27→32, Area 31→32) https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
ashleyshaw
force-pushed
the
claude/clever-maxwell-DLIm4
branch
from
5f98412 to
79aefdb
Compare
- Updated last_updated to 2026-06-01 for files modified during rebase - Incremented versions to reflect rebase changes - Resolves frontmatter freshness validation failures
🔍 Reviewer Summary for PR #700CI Status: ✅ Recommendations
|
Summary
Completes Wave 5.2.4 documentation requirements by adding explicit type-to-project-field mappings and decision trees to guidance documents.
Updates:
Acceptance Criteria
Related Issues
https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
Generated by Claude Code