Docs: add persona pattern matrix, incident dedup-key templates, and design-token governance trigger guidance#43585
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
|
@copilot refactor the section 2 into a compact decision table and a separate file with details to keep the instructions file smaller. |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Addressed in Section 2 in |
|
✅ PR Code Quality Reviewer completed the code quality review. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #43585 does not have the 'implementation' label and has only 1 new line of code in business logic directories (threshold: 100). |
There was a problem hiding this comment.
Pull request overview
This PR updates the gh-aw agentic-workflow authoring docs to make common workflow design decisions easier to apply consistently, especially around persona-specific patterns, incident deduplication keys, and PR-triggered design-token governance.
Changes:
- Added a persona-to-pattern quick matrix to clarify trigger/tool/output/noop defaults per persona.
- Extracted detailed trigger/escalation guidance into a dedicated doc and linked to it from the main “create” guide.
- Expanded trigger examples with a dedicated design-token governance pattern and added incident dedup-key templates.
Show a summary per file
| File | Description |
|---|---|
| pkg/cli/data/agentic_workflows_fallback_aw_files.json | Adds the new trigger-details doc to the fallback AW doc set. |
| .github/skills/agentic-workflows/SKILL.md | Adds the new trigger-details doc to the skill’s routed documentation list. |
| .github/aw/triggers.md | Adds PR-triggered design-token governance guidance (paths, validation, noop rules). |
| .github/aw/github-agentic-workflows.md | Adds a persona-to-pattern quick matrix at the top-level guidance doc. |
| .github/aw/create-agentic-workflow.md | Replaces embedded long-form trigger guidance with a scenario table linking to detailed sections. |
| .github/aw/create-agentic-workflow-trigger-details.md | New detailed guidance doc (reporting/digest, persona map, escalation, incident dedup keys, compliance, coverage). |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 6/6 changed files
- Comments generated: 1
- Review effort level: Low
| - **Schema/API review on PRs**: trigger `pull_request` with `paths:` scoped to backend contract files (for example `db/migrate/**`, `migrations/**`, `schema/**`, `openapi/**`, `api/**`), read via `github` (`gh-proxy`), publish findings with `add-comment`, call `noop` when contracts are unchanged. | ||
| - **Visual regression on UI changes**: trigger `pull_request`, use only `playwright` + `cache-memory` (no extra tools), keep network minimal (allowlist only target preview/app hosts if required), state the exact baseline source (`cache-memory` key, artifact, or branch path), publish via `add-comment`, call `noop` when UI paths are unchanged. | ||
| - **Design-token governance on PRs**: | ||
| - trigger `pull_request` with `paths:` scoped to token sources and theme/config files (for example `tokens/**`, `**/*tokens*.json`, `**/theme/**`, `**/tailwind*.{js,ts}`, `**/*design-token*`) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review: Docs — persona matrix, incident dedup-key templates, design-token governance
The structural refactor (extracting sections 2a–2e into a new details file with a redirect table) is a net improvement — it reduces the height of create-agentic-workflow.md without losing any guidance. The anchor links in the redirect table correctly resolve to headings in the new file, and the fallback JSON and SKILL.md are consistently updated.
Two blocking issues need fixing before merge:
1. Inaccurate frontmatter description in the new file (line 2 of create-agentic-workflow-trigger-details.md)
The current description says "Detailed trigger and escalation guidance" but the file covers 7 domains (reporting, personas, backend review, PR escalation, incident dedup, compliance, coverage). The agent reads this field to decide whether to load the file. A too-narrow description risks the file being skipped in relevant scenarios (e.g., compliance or persona-framed requests).
2. Format inconsistency in triggers.md (Design-token governance entry)
All other entries in the Engineering-focused list in triggers.md are compact single-line bullets. The new Design-token governance entry uses indented multi-line sub-bullets, breaking the established pattern. This inconsistency can confuse agents that read the list with positional assumptions.
Non-blocking observations
- The two persona tables (
github-agentic-workflows.mdfor Backend/Frontend/DevOps andcreate-agentic-workflow-trigger-details.mdfor PM/Designer/Legal) cover different dimensions (engineering vs non-engineering) so the split is intentional, but there is no cross-link between them — consider adding a forward reference from one to the other so an agent discovering the engineering matrix also finds the non-engineering one. - Design-token coverage appears in three places:
triggers.md(new entry), the quick matrix (Frontend Developer row), and the details file persona map (Designer row). This is intentional layering, but a sentence like"See also: Persona-to-Pattern Quick Matrix"in the triggers.md entry would make the relationship explicit.
🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 74.4 AIC · ⌖ 6.58 AIC · ⊞ 4.9K
| @@ -0,0 +1,109 @@ | |||
| --- | |||
| description: Detailed trigger and escalation guidance referenced by create-agentic-workflow.md section 2. | |||
There was a problem hiding this comment.
The frontmatter description says "Detailed trigger and escalation guidance" but the file covers 7 distinct areas (reporting, personas, backend review, PR escalation, incident dedup, compliance, and coverage) — not just trigger and escalation. The agent uses this description to decide whether to load the file, so a too-narrow description risks the file being skipped in relevant scenarios.
Suggested update:
description: Scenario-specific authoring guidance for create-agentic-workflow.md section 2 — reporting, personas, PR escalation, incident dedup-keys, compliance, and coverage.@copilot please address this.
|
|
||
| - **Schema/API review on PRs**: trigger `pull_request` with `paths:` scoped to backend contract files (for example `db/migrate/**`, `migrations/**`, `schema/**`, `openapi/**`, `api/**`), read via `github` (`gh-proxy`), publish findings with `add-comment`, call `noop` when contracts are unchanged. | ||
| - **Visual regression on UI changes**: trigger `pull_request`, use only `playwright` + `cache-memory` (no extra tools), keep network minimal (allowlist only target preview/app hosts if required), state the exact baseline source (`cache-memory` key, artifact, or branch path), publish via `add-comment`, call `noop` when UI paths are unchanged. | ||
| - **Design-token governance on PRs**: |
There was a problem hiding this comment.
The Design-token governance entry uses an indented multi-line sub-bullet format while all other entries in this section (Schema/API review, Visual regression, Deployment incident triage, Dependency-license compliance) are written as single inline bullets.
This format inconsistency will confuse the agent reading this file, which expects a uniform list structure. Either flatten to a single-line bullet matching the pattern of surrounding entries, or convert all entries in this section to the same multi-line format.
Suggested single-line form (matching surrounding style):
- **Design-token governance on PRs**: trigger `pull_request` with `paths:` scoped to token sources and theme/config files (for example `tokens/**`, `**/*tokens*.json`, `**/theme/**`, `**/tailwind*.{js,ts}`, `**/*design-token*`), read via `github` (`gh-proxy`) and validate linked token references before assessment, publish actionable findings with `add-comment`, call `noop` when no token files changed, when required references are absent, or when no policy/token drift is detected.@copilot please address this.
Review Summary — PR #43585Applied 📋 Issues found (6)
@copilot please address the review comments above.
|
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — requesting changes on cross-navigation gaps and terminology inconsistencies introduced by the content extraction.
📋 Key Themes & Highlights
Key Themes
- Navigation dead ends: The new Persona-to-Pattern Quick Matrix in
github-agentic-workflows.mdand the routing table increate-agentic-workflow.mddon't link to each other or to the new detailed file's sections, so readers land in the matrix without a path forward. - Persona vocabulary split: Two separate tables now use different persona naming conventions ("Backend Engineer / Frontend Developer / DevOps" vs. "PM / Designer / Legal") across two files, with no cross-reference connecting them.
- Missing routing table entry: Design-token governance was added to
triggers.mdin this PR but has no corresponding row in the routing table increate-agentic-workflow.md. - Stale-looking examples: Dedup-key examples hardcode today's date (
2026-07-05), which will look stale within weeks. - Drifting frontmatter: The new file's description references "section 2" — a section number that is now meaningless since the parent doc no longer has numbered subsections.
Positive Highlights
- ✅ Clean content extraction: the new dedicated file is a well-structured reference with clear headings and good anchor compatibility.
- ✅ Incident dedup-key templates are concrete and actionable with explicit
window-idnormalization rules. - ✅ Design-token governance trigger pattern is thorough: scoped
paths:, explicit validation step, and explicitnoopconditions. - ✅ Anchor links in the routing table match the actual headings — no broken links introduced.
- ✅ Metadata updated consistently across
SKILL.mdand the fallback JSON.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 90.3 AIC · ⌖ 6.45 AIC · ⊞ 6.7K
Comment /matt to run again
| | PR analyzers deciding comment vs issue vs noop | `pull_request` + escalation logic | [PR analyzer escalation](create-agentic-workflow-trigger-details.md#pr-analyzer-escalation-guidance) | | ||
| | Incident workflows | `workflow_run` / `deployment_status` with `create-issue` dedup | [Incident dedup-key templates](create-agentic-workflow-trigger-details.md#incident-dedup-key-templates-workflow_run-and-deployment_status) | | ||
| | Dependency-license and policy compliance | `pull_request` with manifest `paths:` | [Compliance review guidance](create-agentic-workflow-trigger-details.md#compliance-review-guidance) | | ||
| | Coverage analysis | `pull_request` or CI-linked triggers with explicit fallback | [Coverage-analysis guidance](create-agentic-workflow-trigger-details.md#coverage-analysis-guidance) | |
There was a problem hiding this comment.
[/grill-with-docs] The routing table is missing a row for design-token governance — even though a new design-token trigger pattern was added to triggers.md in this same PR. Users reading the routing table have no path to that guidance.
💡 Suggested addition
Add a row to the routing table (line 93, before the closing line):
| Design-token governance on PRs | `pull_request` with token/theme `paths:` and `add-comment` | [Design-token governance](triggers.md#design-token-governance-on-prs) |This mirrors how other PR-scoped patterns (Backend, Compliance) are surfaced, and makes the new triggers.md entry discoverable from the routing table.
@copilot please address this.
| @@ -0,0 +1,109 @@ | |||
| --- | |||
| description: Detailed trigger and escalation guidance referenced by create-agentic-workflow.md section 2. | |||
There was a problem hiding this comment.
[/grill-with-docs] The frontmatter description says "referenced by create-agentic-workflow.md section 2" but this file covers what were previously sections 2a through 2e — the phrase "section 2" is misleading and will drift as the parent doc evolves.
💡 Suggested fix
Replace the description:
description: >
Detailed trigger-scenario guidance for recurring reports, persona-oriented workflows,
incident dedup-key templates, compliance, and coverage. Referenced from create-agentic-workflow.md.This makes the scope self-describing without relying on section numbering that can change.
@copilot please address this.
|
|
||
| ```text | ||
| # workflow_run incident key | ||
| incident:workflow_run:<workflow-name>:<job-name-or-unknown>:<error-signature>:<window-id> |
There was a problem hiding this comment.
[/grill-with-docs] The dedup-key examples hardcode a real date (2026-07-05). When this doc is read months later, concrete dates look stale and may mislead authors into thinking date-based keys should use today's date rather than the actual window ID.
💡 Suggested fix
Replace the hardcoded date examples with a placeholder that signals the pattern:
example: incident:workflow_run:CI:lint:eslint-error:<YYYY-MM-DD>
example: incident:deployment_status:production:vercel:build-timeout:<YYYY-MM-DD>
Or use a clearly-fictional past date like 2024-01-15 to signal "use the run date" without anchoring to today.
@copilot please address this.
| |---|---|---|---|---| | ||
| | Backend Engineer | `pull_request` with `paths:` scoped to migrations, schema, and API contracts | `github` (`gh-proxy`) | `add-comment` for PR-local findings; `create-issue` only for cross-cutting incidents | `noop` when no backend contract files changed | | ||
| | Frontend Developer | `pull_request` with `paths:` scoped to UI, design-token, and asset files | `github` (`gh-proxy`), optional `playwright`, optional `cache-memory` for baselines | `add-comment` | `noop` when no UI/token files changed or no actionable visual/token issues were found | | ||
| | DevOps Engineer | `workflow_run` for GitHub Actions failures, `deployment_status` for external deployment failures | `github` (`gh-proxy`) with `actions: read` or `deployments: read` | `create-issue` with stable dedup key | `noop` when status is non-terminal, self-recovered, or an open incident already exists for the same dedup key | |
There was a problem hiding this comment.
[/grill-with-docs] The DevOps Engineer row says "create-issue with stable dedup key" but doesn't link to the new dedup-key templates just added in this same PR. The Backend Engineer and Frontend Developer rows also have no links. The Persona-to-Pattern Quick Matrix stands alone without guiding readers to the detailed guidance.
💡 Suggested fix
Add a footer row or inline links, e.g.:
| DevOps Engineer | ... | ... | `create-issue` with stable dedup key ([templates](create-agentic-workflow-trigger-details.md#incident-dedup-key-templates-workflow_run-and-deployment_status)) | ... |Or add a note after the table:
See create-agentic-workflow-trigger-details.md for detailed guidance per scenario.
This makes the matrix a navigation entry point rather than a dead end.
@copilot please address this.
|
|
||
| | Persona or scenario | Trigger and scope | Typical tools and outputs | Required prompt details | | ||
| |---|---|---|---| | ||
| | Program Manager or information-worker digest | `schedule` plus `workflow_dispatch` for previews, reruns, and backfills | `github` (`gh-proxy`); `create-issue` by default | Define the report window, grouping dimensions, deduplication key, and `noop` behavior for empty windows | |
There was a problem hiding this comment.
[/grill-with-docs] The Persona-oriented scenario map table covers PM/Design/Legal but the three personas in the new Quick Matrix in github-agentic-workflows.md are Backend Engineer, Frontend Developer, and DevOps Engineer. These two tables use different persona vocabularies, which will confuse authors who look up a persona in one doc and can't find it in the other.
💡 Suggested fix
Either:
- Extend the Quick Matrix in
github-agentic-workflows.mdto include the PM/Design/Legal personas from this table, or - Align this table's persona names to match (e.g., rename "Designer or design-governance review" → "Frontend Developer / Design Governance"), or
- Add a cross-reference note: "For PM, design, and compliance personas, see the Persona-oriented scenario map."
Consistent vocabulary across both documents avoids navigation dead ends.
@copilot please address this.
| ### 2. Choose the trigger | ||
|
|
||
| Use the smallest trigger that matches the request. See [triggers.md](triggers.md) for the full decision matrix, scenario examples, and `noop` patterns. | ||
| Use the smallest trigger that matches the request. |
There was a problem hiding this comment.
[/grill-with-docs] The trigger section header ("### 2. Choose the trigger") lost its cross-reference to triggers.md when the inline guidance was extracted. The new routing table only appears after the "Common mappings" bullet list — a reader who already knows their trigger type may not scroll down to discover the routing table.
💡 Suggested fix
Restore a brief forward reference immediately after the section intro:
### 2. Choose the trigger
Use the smallest trigger that matches the request. See the scenario table below, or [triggers.md](triggers.md) for the full decision matrix.This preserves the original discoverability without re-expanding the inline content.
@copilot please address this.
There was a problem hiding this comment.
Two correctness issues that need fixing before merge
1. Contradictory noop condition in design-token guidance (triggers.md line 37)
The new clause "when required references are absent from the in-scope changes" directly contradicts the existing PR Checks with Linked References pattern in github-agentic-workflows.md, which says to add-comment when a required link is missing. An agent following the new triggers.md rule will silently no-op where it should request a missing design spec. See inline comment.
2. Undefined "CI-linked triggers" term (create-agentic-workflow.md line 93)
This term has no definition in any file in this repo. An agent authoring a coverage workflow cannot resolve it to a concrete event type, and a naive guess of workflow_run without scoping would fire on every CI completion. Replace with the explicit workflow_run wording consistent with the rest of the trigger guidance. See inline comment.
Other observations (non-blocking)
- The
**/tailwind*.{js,ts}glob in triggers.md line 34 uses brace expansion, which GitHub Actions path filters do not support. Already flagged by an existing review comment — not repeated here. - The refactored section 2 table in
create-agentic-workflow.mdis a clear improvement: dense inline guidance is now properly delegated to the new trigger-details file. The structure is sound. - SKILL.md and fallback JSON are correctly updated to include the new file.
🔎 Code quality review by PR Code Quality Reviewer · 153.9 AIC · ⌖ 5.43 AIC · ⊞ 5.4K
Comment /review to run again
| - trigger `pull_request` with `paths:` scoped to token sources and theme/config files (for example `tokens/**`, `**/*tokens*.json`, `**/theme/**`, `**/tailwind*.{js,ts}`, `**/*design-token*`) | ||
| - read via `github` (`gh-proxy`) and validate linked token references (style dictionary source, token registry, or design-spec URL) before assessment | ||
| - publish actionable findings with `add-comment` | ||
| - call `noop` when no token files changed, when required references are absent from the in-scope changes, or when no policy/token drift is detected |
There was a problem hiding this comment.
Ambiguous noop condition will cause agents to silently pass unvalidatable token PRs instead of requesting the missing reference — directly contradicts github-agentic-workflows.md linked-reference guidance.
💡 Details and suggested fix
The clause "when required references are absent from the in-scope changes" is underspecified: agents cannot deterministically infer whether "required references" means a design-spec URL in the PR description, links embedded in the changed token files, or a token-registry file not part of the diff.
More critically, this directly contradicts the existing guidance in github-agentic-workflows.md § "PR Checks with Linked References":
Link missing →
add-commentrequesting it, orcreate-issueif policy requires a blocking escalation
An agent following this triggers.md line would silently noop when token files are changed but the PR body omits the design-spec URL — the exact case where an add-comment requesting the reference is the correct action.
Suggested fix:
- call `noop` when no token files changed or when no policy/token drift is detected
- call `add-comment` requesting the missing design-spec or token-registry reference when token files changed but no linked reference is present in the PR bodyThis makes the noop boundary unambiguous and aligns with the linked-reference pattern already in github-agentic-workflows.md.
| | PR analyzers deciding comment vs issue vs noop | `pull_request` + escalation logic | [PR analyzer escalation](create-agentic-workflow-trigger-details.md#pr-analyzer-escalation-guidance) | | ||
| | Incident workflows | `workflow_run` / `deployment_status` with `create-issue` dedup | [Incident dedup-key templates](create-agentic-workflow-trigger-details.md#incident-dedup-key-templates-workflow_run-and-deployment_status) | | ||
| | Dependency-license and policy compliance | `pull_request` with manifest `paths:` | [Compliance review guidance](create-agentic-workflow-trigger-details.md#compliance-review-guidance) | | ||
| | Coverage analysis | `pull_request` or CI-linked triggers with explicit fallback | [Coverage-analysis guidance](create-agentic-workflow-trigger-details.md#coverage-analysis-guidance) | |
There was a problem hiding this comment.
"CI-linked triggers" is undefined — agents cannot derive a concrete trigger from this description and may choose the wrong event type.
💡 Details and suggested fix
The coverage-analysis row:
| Coverage analysis |
pull_requestor CI-linked triggers with explicit fallback | ...
"CI-linked triggers" has no definition in any referenced file. In this codebase the meaningful options are workflow_run (reacting to a CI workflow completing) or push. An agent authoring a coverage workflow will not know which to use and may default to workflow_run with no workflows: scoping, which would fire on every completed workflow — a correctness bug.
Suggested fix:
| Coverage analysis | `pull_request` or `workflow_run` (from a CI workflow) with explicit fallback | ...Or if both cases should be preserved:
| Coverage analysis | `pull_request` for PR-gate checks; `workflow_run` when consuming CI-produced artifacts | ...This is consistent with how workflow_run is described in every other row and trigger-selection guide.
This updates the agentic-workflow authoring guidance to incorporate findings from persona exploration: stronger persona-to-trigger mapping, clearer incident deduplication patterns, and more explicit design-token governance behavior. The goal is to make high-signal workflow design choices easier to apply consistently.
Persona guidance consolidation (
.github/aw/github-agentic-workflows.md)noopcriteria for:Incident workflow dedup standardization (
.github/aw/create-agentic-workflow.md)workflow_rundeployment_statuserror-signature,window-id, duplicate suppression, andnoophandling).Design-token governance pattern (
.github/aw/triggers.md)paths, required reference validation (token registry/spec/source), output behavior (add-comment), and explicitnoopconditions.