Problem

The Q workflow agent was getting confused by issue/PR context. In run #63962, Q read issue #21812 (about a CodeQL violation from slice pre-allocation) and tried to revert a Go code change instead of optimizing agentic workflows. The PR it attempted to create had the title:

"revert: undo slice pre-allocation optimization to fix CodeQL violations (#21763)"

This is completely outside Q's scope.

Root Cause

1. No upfront plan announcement — the agent jumped into investigation without declaring what it would do
2. Ambiguous context guidance — the issue/PR context sections said "use this context to inform your investigation" without making clear the context is background info only
3. No explicit scope constraint — nothing prevented the agent from editing non-workflow files

Changes Made

.github/workflows/q.md

1. Added mission scope constraint at the top of the Mission section:

   Your sole mission is to optimize agentic workflows in .github/workflows/. You MUST NOT fix general code bugs, revert commits, or address issues unrelated to agentic workflow configuration.

2. Added Phase 0 plan announcement step: Before doing any investigation, the agent must post an add_comment with its investigation plan — which workflows it will analyze, what issues it will look for, and what changes it anticipates. This provides transparency and a checkpoint.

3. Clarified context sections: Issue/PR/Discussion context sections now explicitly say:

   "The issue context is background information only. Do NOT fix code bugs, revert commits, or perform work unrelated to .github/workflows/*.md files."

4. Added scope rule to Change Quality: New bullet: "Stay in scope: Only modify .github/workflows/*.md files — never edit Go, JavaScript, YAML, or lock files"

Expected Improvements

• Q will announce its plan before starting work, giving users visibility
• Q will not confuse issue/PR context with a general code fix work order
• Q will stay focused on agentic workflow optimization in all cases

Validation

✅ q.md compiled successfully with no errors or warnings.

References

• Run analyzed: #63962 (failure due to out-of-scope PR attempt)

• Triggered by: @pelikhan on issue [workflow-style] Normalize report formatting for non-compliant workflows #21812

• Fixes [workflow-style] Normalize report formatting for non-compliant workflows #21812

🎩 Equipped by Q · ◷

• expires on Mar 21, 2026, 4:11 PM UTC

To create a pull request with the changes:

# Download the patch from the workflow run
gh run download 23304243899 -n agent-artifacts -D /tmp/agent-artifacts-23304243899

# Create a new branch
git checkout -b q/clearer-agent-plan-fa4edf8ee65be419 main

# Apply the patch (--3way handles cross-repo patches)
git am --3way /tmp/agent-artifacts-23304243899/aw-q-clearer-agent-plan.patch

# Push the branch and create the pull request
git push origin q/clearer-agent-plan-fa4edf8ee65be419
gh pr create --title '[q] improve(q): clarify agent scope and add plan announcement step (#21812)' --base main --head q/clearer-agent-plan-fa4edf8ee65be419 --repo github/gh-aw