[plan] Add scope/constraint guidance to developer.instructions to prevent complex workflow timeouts #19543

Objective

Add guidance in developer.instructions and/or AGENTS.md advising users to provide concrete constraints upfront (coverage report format, file path, scope) when requesting complex analysis workflows, to prevent agent timeout.

Background

Discussion #19488 reported that the "QA test coverage" scenario timed out after 8+ minutes. The root cause was an open-ended prompt with no constraints on the coverage report format (lcov, cobertura, jacoco), which caused the agent to spend excessive time exploring implementation details.

Approach

1. In .github/agents/developer.instructions.md, add a Scope Hints for Complex Workflows section with guidance like:

   • For file-parsing workflows: specify the file format (lcov, cobertura, jacoco, etc.)
   • For cross-branch diff workflows: specify the branch strategy (base/head, main/feature)
   • For reporting workflows: specify the output format (markdown, JSON, HTML)
   • General rule: the more constraints provided upfront, the faster and more accurate the generated workflow

2. Add example prompt formulations showing constrained vs. unconstrained requests:

### ✅ Constrained (faster, more accurate)
"Create a workflow that reads an lcov coverage report from `coverage/lcov.info`
and comments on PRs if coverage drops below 80%."

### ⚠️ Unconstrained (may cause timeout or vague output)
"Create a workflow that monitors test coverage."

3. Optionally add a note in the developer.instructions skill about handling complex analysis requests with timeouts.

Files to Modify

• .github/agents/developer.instructions.md — add scope hints section
• Optionally skills/developer.md or AGENTS.md if the guidance belongs there

Acceptance Criteria

• Guidance for providing constraints is documented with concrete examples
• Examples show constrained vs. unconstrained prompt formulations
• make recompile runs without errors

Generated by Plan Command for issue #discussion #19488 · ◷

• expires on Mar 6, 2026, 8:04 AM UTC