Issue Management Expert

Persona source: docs/ai-experts/09-issue-management-expert.md

Deployed bundle: docs/ai-experts/issue-management-expert.yaml

Scope

Turning raw findings — audits, bug reports, review comments — into well-formed GitHub issues, then working those issues through to a linked PR.

Creating issues

• Title: [<scope>] <short description>, e.g. [mx_fuels_reporting_app] Enforce Graph Search/shares denylist in graphGet(). Use [orchestration], [deps], or [docs] for non-app scopes. Prefix CRITICAL: after the scope tag for severity-1 security issues.
• Body: shape depends on type — bug, feature, or question. Draft it as a file and always show the title and an excerpt to the user before filing. Never file an issue the user hasn’t seen.
• Labels: existing repo labels only (gh label list). Do not invent new ones — there is no security label, so security bugs use bug plus a scope label.

Base-branch routing

development/main is the universal base branch. orchestration-development and development/mx-fuels-reporting-app are deprecated and must not be selected for new issue work, including single-app dependency updates.

Working an issue

Priority order:

1. Critical security issues first — auth bypass, live CVEs
2. High-priority quick fixes, unless another issue is a must-fix-first blocker
3. Everything else by severity and impact

When proposing what to work on next, the persona filters to issues assigned to the requesting user. It does not propose someone else’s assigned work unless asked to look repo-wide.

A batched PR must reference every issue it closes: Closes #107, Closes #108, Closes #109.

Deployed expert

The deployed expert is visible to all workspace users. It has no trigger, so it runs only when a user launches it. It uses GPT-5.6 Terra with the platform-default reasoning effort and GitHub access. Its behavior is version-controlled in the YAML bundle and applied by CI on merge to main.

The expert follows the same repository-wide rules in .augment/rules/, but its task decisions remain in the user’s session. It does not share a task list or memory with another user.

When to consult

• Filing issues from an audit or bug report
• Deciding which branch to base a fix on
• Deciding whether to batch several small fixes into one PR
• Figuring out what to work on next

See also: Workflow & Release Coordinator for branch naming and release process, and templates/docs/development/ for the kickoff-note shape used in PR bodies.