Description
docs/src/content/docs/guides/ai-issue-triage.md example workflow configures add-labels.allowed: [bug, feature, question, needs-info, priority/p0, priority/p1, priority/p2, duplicate]. bug/feature/question are GitHub default labels, but priority/p0, priority/p1, priority/p2, and needs-info are not. The guide explains the security rationale for restricting add-labels/add-comment but never mentions that non-default labels must already exist in the target repository — GitHub's label API returns a 404 otherwise. A new user copying the example verbatim into a fresh repo (a very likely first action for a getting-started guide) hits an opaque runtime failure with no signal in the doc explaining why.
For contrast, docs/src/content/docs/reference/safe-outputs.md's assign-milestone section already documents this class of failure well ("Without auto_create, the handler returns a clear error listing the available milestones and suggesting auto_create: true") — the issue-triage guide should meet the same bar.
Expected Impact
Prevents a first-run failure for new users following the tutorial as written; small, high-leverage documentation fix for onboarding trust.
Suggested Agent
General docs agent — add one sentence after the security-rationale paragraph in ai-issue-triage.md noting that non-default labels in allowed must be created ahead of time (e.g. via gh label create or the repo Settings > Labels page) before running the workflow.
Estimated Effort
Quick (< 1 hour)
Data Source
DeepReport Intelligence Briefing 2026-08-12, mined from User Experience Analysis Report #52088.
Generated by 🔬 Deep Report · agent · 198.4 AIC · ⌖ 54.5 AIC · ⊞ 11.4K · ◷
Description
docs/src/content/docs/guides/ai-issue-triage.mdexample workflow configuresadd-labels.allowed: [bug, feature, question, needs-info, priority/p0, priority/p1, priority/p2, duplicate].bug/feature/questionare GitHub default labels, butpriority/p0,priority/p1,priority/p2, andneeds-infoare not. The guide explains the security rationale for restrictingadd-labels/add-commentbut never mentions that non-default labels must already exist in the target repository — GitHub's label API returns a 404 otherwise. A new user copying the example verbatim into a fresh repo (a very likely first action for a getting-started guide) hits an opaque runtime failure with no signal in the doc explaining why.For contrast,
docs/src/content/docs/reference/safe-outputs.md'sassign-milestonesection already documents this class of failure well ("Withoutauto_create, the handler returns a clear error listing the available milestones and suggestingauto_create: true") — the issue-triage guide should meet the same bar.Expected Impact
Prevents a first-run failure for new users following the tutorial as written; small, high-leverage documentation fix for onboarding trust.
Suggested Agent
General docs agent — add one sentence after the security-rationale paragraph in
ai-issue-triage.mdnoting that non-default labels inallowedmust be created ahead of time (e.g. viagh label createor the repo Settings > Labels page) before running the workflow.Estimated Effort
Quick (< 1 hour)
Data Source
DeepReport Intelligence Briefing 2026-08-12, mined from User Experience Analysis Report #52088.