docs: complete Wave 5 child audits #654 #655 #656 #792
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,85 @@ | ||||||
| --- | ||||||
| file_type: documentation | ||||||
| title: Issue Labeling Rules Audit in labeler.yml | ||||||
| description: Audit of issue-specific vs PR-specific labeling coverage in labeler.yml, including gaps and recommendations. | ||||||
| created_date: "2026-06-03" | ||||||
| last_updated: "2026-06-03" | ||||||
| version: "1.0.0" | ||||||
| domain: governance | ||||||
| status: active | ||||||
| tags: [audit, labeler, issues, pull-requests, automation, wave-5] | ||||||
| --- | ||||||
|
|
||||||
| # Issue Labeling Rules Audit in labeler.yml (#656) | ||||||
|
|
||||||
| ## Executive Summary | ||||||
|
|
||||||
| `.github/labeler.yml` is currently structured around PR-friendly signals (`head-branch`, `changed-files`) and has limited native issue-specific rule expression. Issue labelling exists in practice through the unified labeling workflow and agent heuristics rather than through rich issue-specific config rules. | ||||||
|
|
||||||
| ## Scope and Inputs | ||||||
|
|
||||||
| - `.github/labeler.yml` | ||||||
| - `.github/workflows/labeling.yml` | ||||||
| - `scripts/agents/labeling.agent.js` | ||||||
| - `scripts/agents/includes/check-template-labels.js` | ||||||
|
|
||||||
| ## Current Rule Inventory | ||||||
|
|
||||||
| ### PR-Centric Rule Families in `.github/labeler.yml` | ||||||
|
|
||||||
| - `head-branch` mappings: | ||||||
| - status mapping (`status:needs-review`) | ||||||
| - type mappings (`type:feature`, `type:bug`, etc.) | ||||||
| - priority mappings (`priority:critical`, `priority:normal`) | ||||||
| - `changed-files` mappings: | ||||||
| - area labels (`area:ci`, `area:labels`, `area:documentation`, etc.) | ||||||
| - language labels (`lang:js`, `lang:md`, `lang:yaml`, etc.) | ||||||
|
|
||||||
| ### Issue-Specific Presence | ||||||
|
|
||||||
| - No explicit issue-template keyed rule groups in `.github/labeler.yml`. | ||||||
| - No first-class per-template deterministic mapping in this config. | ||||||
| - File contains an explicit note that issue-template-driven automation is planned, not active. | ||||||
|
|
||||||
| ## Heuristics Used for Issues Today | ||||||
|
|
||||||
| Although `labeler.yml` is PR-oriented, issues are still processed because `labeling.yml` runs on issue events and `labeling.agent.js` applies: | ||||||
|
|
||||||
| - content-based type detection from title/body keyword maps | ||||||
| - canonicalization and one-hot enforcement | ||||||
| - default-label application logic | ||||||
|
|
||||||
| This means issue automation currently depends more on code heuristics than on declarative `labeler.yml` issue rules. | ||||||
|
|
||||||
| ## PR vs Issue Comparison Matrix | ||||||
|
|
||||||
| | Rule Capability | PR Coverage | Issue Coverage | | ||||||
| |---|---|---| | ||||||
| | Branch-prefix type mapping | Strong (`head-branch`) | None (no branch context) | | ||||||
| | Changed-files area/lang mapping | Strong (`changed-files`) | None (no changed files) | | ||||||
| | Declarative deterministic mapping in `labeler.yml` | Strong | Weak | | ||||||
| | Content/title/body heuristic mapping | Moderate (agent fallback) | Strong (primary path) | | ||||||
| | Canonical label normalization | Strong | Strong | | ||||||
|
|
||||||
| ## Findings | ||||||
|
|
||||||
| 1. `labeler.yml` has broad PR coverage and narrow issue-native coverage. | ||||||
| 2. Issue labelling works, but largely through procedural logic in `labeling.agent.js`. | ||||||
|
Contributor
There was a problem hiding this comment. To maintain consistency with the American English spelling convention used throughout the repository, please use "labeling" instead of "labelling".
Suggested change
|
||||||
| 3. The current setup is functional but less deterministic for issue templates than for PR workflows. | ||||||
|
|
||||||
| ## Recommendations | ||||||
|
|
||||||
| 1. Introduce declarative issue mapping support in `labeler.yml` (title/body/template pattern blocks). | ||||||
| 2. Align issue templates with deterministic labels to reduce heuristic dependency. | ||||||
| 3. Keep `labeling.agent.js` keyword detection as fallback for non-template or freeform issues. | ||||||
| 4. Add a CI assertion that each numbered issue template maps to at least one canonical `type:*` outcome path. | ||||||
|
|
||||||
| ## Validation Notes | ||||||
|
|
||||||
| - Issue workflow triggers verified via `.github/workflows/labeling.yml` (`issues` events enabled). | ||||||
| - PR-centric rule bias verified in `.github/labeler.yml`. | ||||||
| - Heuristic enforcement confirmed in `scripts/agents/labeling.agent.js`. | ||||||
|
|
||||||
| ## Related Issue | ||||||
|
|
||||||
| - Closes #656 | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,99 @@ | ||||||
| --- | ||||||
| file_type: documentation | ||||||
| title: Issue Template to Automation Trigger Mapping Audit | ||||||
| description: Mapping of issue templates to expected and actual automation triggers, with gap analysis and remediation steps. | ||||||
| created_date: "2026-06-03" | ||||||
| last_updated: "2026-06-03" | ||||||
| version: "1.0.0" | ||||||
| domain: governance | ||||||
| status: active | ||||||
| tags: [audit, automation, issue-templates, labeling, workflows, wave-5] | ||||||
| --- | ||||||
|
|
||||||
| # Issue Template to Automation Trigger Mapping Audit (#655) | ||||||
|
|
||||||
| ## Executive Summary | ||||||
|
|
||||||
| Issue templates are structurally standardised, but they do not currently provide deterministic label/type triggers in frontmatter. Automation is therefore primarily workflow-driven and heuristic-driven after issue creation. | ||||||
|
Contributor
There was a problem hiding this comment. To maintain consistency with the American English spelling convention used throughout the repository (e.g.,
Suggested change
|
||||||
|
|
||||||
| Key result: | ||||||
|
|
||||||
| - Expected: template metadata should deterministically map to labels/type. | ||||||
| - Actual: template selection itself does not directly set labels; labeling is applied by workflow and agent heuristics. | ||||||
|
|
||||||
| ## Mapping Model | ||||||
|
|
||||||
| ### Inputs Reviewed | ||||||
|
|
||||||
| - `.github/ISSUE_TEMPLATE/*.md` (numbered templates) | ||||||
| - `.github/PULL_REQUEST_TEMPLATE/*.md` | ||||||
| - `.github/labeler.yml` | ||||||
| - `.github/workflows/labeling.yml` | ||||||
| - `scripts/agents/labeling.agent.js` | ||||||
|
|
||||||
| ### Actual Trigger Path for Issues | ||||||
|
|
||||||
| 1. User creates issue from template. | ||||||
| 2. `labeling.yml` runs on `issues` events (`opened`, `edited`, `reopened`, `labeled`, `unlabeled`, `transferred`). | ||||||
| 3. `scripts/agents/labeling.agent.js` executes. | ||||||
| 4. Agent applies: | ||||||
| - labeler rules from `.github/labeler.yml` (limited for issues) | ||||||
| - defaults/one-hot normalization | ||||||
| - content-based type detection from issue title/body | ||||||
|
|
||||||
| ## Template Metadata Readiness | ||||||
|
|
||||||
| Across 26 numbered issue templates: | ||||||
|
|
||||||
| - `name`: 26/26 | ||||||
| - `description`: 26/26 | ||||||
| - `labels`: 0/26 | ||||||
| - `title`: 0/26 | ||||||
| - `assignees`: 0/26 | ||||||
|
|
||||||
| Impact: template files provide guidance text, but do not deterministically encode expected labels/type at creation time. | ||||||
|
|
||||||
| ## PR Template Comparison | ||||||
|
|
||||||
| PR automation is stronger because PR context carries branch and file-diff signals used by `.github/labeler.yml`: | ||||||
|
|
||||||
| - `head-branch` mappings drive many `type:*`, `status:*`, and `priority:*` outcomes. | ||||||
| - `changed-files` mappings drive `area:*` and `lang:*` labels. | ||||||
|
|
||||||
| Issue context has no branch or changed-files signals, so the current `.github/labeler.yml` rule design naturally favours PR events. | ||||||
|
Contributor
There was a problem hiding this comment. To maintain consistency with the American English spelling convention used throughout the repository, please use "favors" instead of "favours".
Suggested change
|
||||||
|
|
||||||
| ## Template-to-Automation Mapping Status | ||||||
|
|
||||||
| | Template Set | Expected Automation | Current Status | Missing Pieces | | ||||||
| |---|---|---|---| | ||||||
| | Numbered issue templates (`01`-`26`) | Deterministic `type:*` and baseline triage labels on create | Partial (agent infers from text) | No template `labels`, no deterministic per-template mapping in config | | ||||||
|
There was a problem hiding this comment.
For template-created issues without an existing Useful? React with 👍 / 👎. |
||||||
| | Issue templates for support/triage flows | Consistent intake labels (area/priority/type) | Partial | No explicit issue-template label maps in `.github/labeler.yml` | | ||||||
| | PR templates (`pr_*`) | Type/area/lang/status automation | Strong | N/A (already branch/file powered) | | ||||||
|
|
||||||
| ## Gap Analysis | ||||||
|
|
||||||
| 1. Determinism gap: | ||||||
| Issue template selection does not directly map to canonical labels. | ||||||
|
|
||||||
| 2. Signal gap: | ||||||
| `.github/labeler.yml` depends heavily on branch/file signals unavailable for issues. | ||||||
|
|
||||||
| 3. Consistency gap: | ||||||
| Issue outcomes rely more on keyword heuristics than explicit template intent. | ||||||
|
|
||||||
| ## Recommendations | ||||||
|
|
||||||
| 1. Add `labels` keys to issue template frontmatter for canonical type labels where safe. | ||||||
| 2. Add issue-focused rule blocks (title/body pattern maps) to complement current PR-centric rules. | ||||||
| 3. Document a canonical mapping table in docs: `template file -> type label -> default area/priority`. | ||||||
| 4. Keep heuristics as fallback, not primary path, for template-created issues. | ||||||
|
|
||||||
| ## Validation Notes | ||||||
|
|
||||||
| - Workflow trigger coverage verified in `.github/workflows/labeling.yml`. | ||||||
| - Rule source verified in `.github/labeler.yml`. | ||||||
| - Heuristic source verified in `scripts/agents/labeling.agent.js`. | ||||||
|
|
||||||
| ## Related Issue | ||||||
|
|
||||||
| - Closes #655 | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,131 @@ | ||||||
| --- | ||||||
| file_type: documentation | ||||||
| title: Issue Template Inventory and Standardization Audit | ||||||
| description: Inventory and standardization audit of numbered issue templates with issue-type alignment checks. | ||||||
| created_date: "2026-06-03" | ||||||
| last_updated: "2026-06-03" | ||||||
| version: "1.0.0" | ||||||
| domain: governance | ||||||
| status: active | ||||||
| tags: [audit, issue-templates, issue-types, standardization, wave-5] | ||||||
| --- | ||||||
|
|
||||||
| # Issue Template Inventory and Standardization Audit (#654) | ||||||
|
|
||||||
| ## Executive Summary | ||||||
|
|
||||||
| Audit scope covered `.github/ISSUE_TEMPLATE/`, `.github/ISSUE_TEMPLATE/config.yml`, `.github/ISSUE_TEMPLATE/README.md`, and `.github/issue-types.yml`. | ||||||
|
|
||||||
| Current state: | ||||||
|
|
||||||
| - 26 numbered issue templates are present (`01`-`26`) and sequenced. | ||||||
| - Every numbered template includes basic template metadata (`name`, `description`). | ||||||
| - Numbered templates do not include `labels`, `title`, or `assignees` frontmatter keys. | ||||||
| - Template-to-issue-type parity is partial: 26 templates exist for 29 issue types. | ||||||
| - `config.yml` is valid but minimal (blank issues disabled + one support link). | ||||||
|
|
||||||
| ## Inventory | ||||||
|
|
||||||
| ### Templates Found | ||||||
|
|
||||||
| Numbered templates: 26 | ||||||
|
|
||||||
| - `01-task.md` | ||||||
| - `02-bug.md` | ||||||
| - `03-feature.md` | ||||||
| - `04-design.md` | ||||||
| - `05-epic.md` | ||||||
| - `06-story.md` | ||||||
| - `07-improvement.md` | ||||||
| - `08-user-experience-feedback.md` | ||||||
| - `09-code-refactor.md` | ||||||
| - `10-build-ci.md` | ||||||
| - `11-automation.md` | ||||||
| - `12-testing-coverage.md` | ||||||
| - `13-performance.md` | ||||||
| - `14-a11y.md` | ||||||
| - `15-security.md` | ||||||
| - `16-compatibility.md` | ||||||
| - `17-integration-issue.md` | ||||||
| - `18-release.md` | ||||||
| - `19-maintenance.md` | ||||||
| - `20-documentation.md` | ||||||
| - `21-research.md` | ||||||
| - `22-audit.md` | ||||||
| - `23-code-review.md` | ||||||
| - `24-ai-ops.md` | ||||||
| - `25-content-modelling.md` | ||||||
| - `26-help.md` | ||||||
|
|
||||||
| Additional non-template file in folder: `README.md`. | ||||||
|
|
||||||
| ## Frontmatter Standardization Check | ||||||
|
|
||||||
| Across all 26 numbered templates: | ||||||
|
|
||||||
| - `name`: present in 26/26 | ||||||
| - `description`: present in 26/26 | ||||||
| - `title`: present in 0/26 | ||||||
| - `labels`: present in 0/26 | ||||||
| - `assignees`: present in 0/26 | ||||||
|
|
||||||
| This is internally consistent, but it means templates do not directly pre-apply canonical type labels. | ||||||
|
|
||||||
| ## Issue-Type Alignment | ||||||
|
|
||||||
| `issue-types.yml` currently defines 29 issue types. | ||||||
|
|
||||||
| Mapped by intent to templates (26): | ||||||
|
|
||||||
| - Present: Task, Bug, Feature, Design, Epic, Story, Improvement, Refactor, Build, Automation, Testing, Performance, Accessibility, Security, Compatibility, Integration, Release, Maintenance, Documentation, Research, Audit, Review, AI Ops, Content Modelling, User Experience Feedback, Help. | ||||||
|
|
||||||
| Missing dedicated templates (3): | ||||||
|
|
||||||
| - Chore (`type:chore`) | ||||||
| - Question (`type:question`) | ||||||
| - Support (`type:support`) | ||||||
|
|
||||||
| ## Usage Status and Recency | ||||||
|
|
||||||
| No template in the numbered set is marked deprecated. | ||||||
|
|
||||||
| Last-touch pattern from git history: | ||||||
|
|
||||||
| - `01`-`07`: updated 2026-05-29 | ||||||
| - `08`-`26`: updated 2026-06-01 | ||||||
|
|
||||||
| Interpretation: all templates appear actively maintained during Wave 5 work; none appear stale by date alone. | ||||||
|
|
||||||
| ## `config.yml` Completeness | ||||||
|
|
||||||
| Current config: | ||||||
|
|
||||||
| - `blank_issues_enabled: false` | ||||||
| - one `contact_links` support entry | ||||||
|
|
||||||
| Assessment: | ||||||
|
|
||||||
| - Valid for GitHub issue template config. | ||||||
| - Minimal but complete for current operating model. | ||||||
|
|
||||||
| ## Findings | ||||||
|
|
||||||
| 1. Numbering and baseline standardization are good (26 sequential templates). | ||||||
| 2. Direct template-driven labelling is not configured in issue templates (`labels` absent in all numbered templates). | ||||||
|
Contributor
There was a problem hiding this comment. To maintain consistency with the American English spelling convention used throughout the repository, please use "labeling" instead of "labelling".
Suggested change
|
||||||
| 3. Type parity remains incomplete because 3 issue types do not have dedicated templates. | ||||||
|
|
||||||
| ## Recommendations | ||||||
|
|
||||||
| 1. Add three missing templates for Chore, Question, and Support to close 29-type parity. | ||||||
| 2. Add explicit `labels` to issue templates where deterministic type assignment is desired. | ||||||
| 3. Keep `config.yml` minimal but add a short comment block documenting why blank issues are disabled. | ||||||
|
|
||||||
| ## Validation Notes | ||||||
|
|
||||||
| - Template file inventory collected from `.github/ISSUE_TEMPLATE/*.md`. | ||||||
| - Issue-type source of truth: `.github/issue-types.yml`. | ||||||
| - Frontmatter-key coverage derived via static scan of numbered templates. | ||||||
|
|
||||||
| ## Related Issue | ||||||
|
|
||||||
| - Closes #654 | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To maintain consistency with the American English spelling convention used throughout the repository (e.g.,
labeling.yml,labeling.agent.js, andstandardization), please use "labeling" instead of "labelling".