Maintainer Issue And PR Management

Trigger

• Use when a maintainer asks the agent to create, update, close, or otherwise manage a GitHub issue or PR
• Use when issue creation needs codebase analysis before deciding scope, ownership, labels, acceptance criteria, or validation

Required Surfaces

• contributor_interface

Conditional Surfaces

• harness_docs
• harness_exec
• router_config_contract
• signal_runtime
• decision_logic
• algorithm_selection
• plugin_runtime
• python_cli_schema
• python_cli_runtime
• dashboard_config_ui
• dashboard_console_backend
• k8s_operator
• training_stack

Stop Conditions

• The requested issue or PR action depends on code intent that has not been inspected in the current repository state
• The requested labels, title, or validation summary would contradict the canonical templates or current harness rules
• A destructive delete is requested without a clear target and rationale; prefer close with reason unless the maintainer explicitly wants deletion

Must Read

• CONTRIBUTING.md
• .github/PULL_REQUEST_TEMPLATE.md
• tools/agent/maintainer-policy.yaml
• .prowlabels.yaml

Workflow

1. Resolve the repo context first.
   • If the issue or PR is based on a code change, inspect the relevant code before drafting anything.
   • If changed paths are known or can be estimated, run make agent-report ENV=cpu|amd CHANGED_FILES="..." to resolve the primary skill, impacted surfaces, and expected validation.
2. Classify the artifact before writing.
   • Issues use the canonical issue templates as the schema for title and body.
   • PRs use the canonical PR template as the schema for title, purpose, affected modules, test plan or results, and checklist expectations.
3. Apply canonical labels and naming.
   • New issues start with the template type label and needs-acceptance.
   • Anyone with repository write permission may comment /accept after confirming scope and exactly one owning wg/* label; the workflow then replaces needs-acceptance with accepted.
   • Use .prowlabels.yaml for command-driven area/* and priority/* taxonomy; do not treat those labels as lifecycle state.
   • Use ready-for-dev only for accepted, unassigned work with review capacity. help wanted and good first issue are curated subsets.
   • Do not invent labels outside the repository taxonomy unless the maintainer explicitly asks for a new label.
4. Keep code analysis and management metadata aligned.
   • New implementation issues should cite the relevant files, symbols, or surfaces discovered during analysis.
   • If the work spans multiple resumable loops, link or update the indexed execution plan instead of hiding the plan only in the issue body.
   • If the desired architecture still diverges from the repo after the planned change, link or update the indexed tech-debt entry instead of leaving the gap only in the issue or PR text.
5. Enforce PR conventions.
   • A non-trivial PR must link an accepted issue with exactly one Workgroup owner before entering Maintainer review.
   • PR titles use exactly one leading [Type] prefix from .github/PULL_REQUEST_TEMPLATE.md; affected modules belong in labels and the PR body, not stacked [][] prefixes.
   • Commits intended for PRs must use git commit -s.
   • Commit messages do not need to repeat the PR title prefixes unless the maintainer explicitly wants them.

Gotchas

• Do not draft labels, validation summaries, or scope from memory; inspect the current templates, labels, and repo state first.
• If an issue or PR exposes real architecture debt or multi-loop execution needs, put that state in the indexed debt or plan docs instead of hiding it only in the ticket text.

Standard Commands

• make agent-report ENV=cpu|amd CHANGED_FILES="..."
• make agent-validate
• make agent-ci-gate CHANGED_FILES="..."
• make agent-feature-gate ENV=cpu|amd CHANGED_FILES="..."

Acceptance

• Issue and PR management requests are grounded in the current repo state rather than memory
• Issue drafts include the canonical title/body shape plus the correct default and maintainer-applied labels
• PR drafts or updates include the canonical title classification, signoff expectation, affected-module context, and validation results or blockers