Skip to content

Add scope/constraint guidance to developer.instructions to prevent complex workflow timeouts#19549

Merged
pelikhan merged 3 commits intomainfrom
copilot/add-scope-guidance-to-instructions
Mar 4, 2026
Merged

Add scope/constraint guidance to developer.instructions to prevent complex workflow timeouts#19549
pelikhan merged 3 commits intomainfrom
copilot/add-scope-guidance-to-instructions

Conversation

Copy link
Contributor

Copilot AI commented Mar 4, 2026 •
edited
Loading

Open-ended workflow prompts (e.g. "monitor test coverage") cause agent timeouts by forcing exploration of multiple implementation paths. Upfront constraints eliminate this ambiguity.

Changes

  • New section ## Scope Hints for Complex Workflows in .github/agents/developer.instructions.md (before Quick Reference):
    • Workflow-type → required constraints lookup table (file-parsing, cross-branch diff, reporting, coverage, dependency audit, benchmarks)
    • Constrained vs. unconstrained prompt examples: 
      ✅ "Read an lcov report from `coverage/lcov.info` and comment on PRs if coverage drops below 80%."
⚠️  "Monitor test coverage."
    • Pre-submission checklist: input format/path, trigger event, success criterion, output destination, scope boundaries
  • Table of Contents updated with the new section entry

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • https://api.github.com/graphql
    • Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw (http block)
  • https://api.github.com/repos/actions/download-artifact/git/ref/tags/v8
    • Triggering command: /usr/bin/gh gh api /repos/actions/download-artifact/git/ref/tags/v8 --jq .object.sha (http block)
  • https://api.github.com/repos/actions/upload-artifact/git/ref/tags/v7
    • Triggering command: /usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v7 --jq .object.sha (http block)
  • https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b
    • Triggering command: /usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha (http block)
  • https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha (http block)
  • https://api.github.com/repos/githubnext/agentics/git/ref/tags/
    • Triggering command: /usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

This section details on the original issue you should resolve

<issue_title>[plan] Add scope/constraint guidance to developer.instructions to prevent complex workflow timeouts</issue_title>
<issue_description>## 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."
  1. 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

Comments on the Issue (you are @copilot in this section)

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

@pelikhan
Add scope/constraint guidance to developer.instructions to prevent co…
786edc4 
…mplex workflow timeouts

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot AI changed the title [WIP] Add scope guidance to developer instructions Add scope/constraint guidance to developer.instructions to prevent complex workflow timeouts Mar 4, 2026
@pelikhan pelikhan marked this pull request as ready for review March 4, 2026 09:04
Copilot AI review requested due to automatic review settings March 4, 2026 09:04
@pelikhan pelikhan merged commit 6643aa1 into main Mar 4, 2026
@pelikhan pelikhan deleted the copilot/add-scope-guidance-to-instructions branch March 4, 2026 09:05
Copilot AI reviewed Mar 4, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds documentation guidance to help authors of complex agentic workflow prompts provide concrete constraints upfront, reducing ambiguity and avoiding workflow timeouts.

Changes:

  • Added a new “Scope Hints for Complex Workflows” section with rule-of-thumb guidance and a workflow-type constraints table.
  • Added constrained vs. unconstrained prompt examples to illustrate the difference in specificity.
  • Updated the Table of Contents to include the new section.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

This was referenced Mar 4, 2026
Open
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

+1 more reviewer

@pelikhan pelikhan pelikhan approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@pelikhan pelikhan

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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

3 participants

@pelikhan