From Issue to Pull Request with AI

The issue is the specification. Everything downstream is bounded by it.

That statement is not new — it was true when the issue went to a person. Delegation makes it consequential, because the person could ask a question and the agent cannot. A vague issue assigned to a teammate produces a conversation. The same issue assigned to an agent produces a pull request that answers a question nobody asked.

Before you start

• AI coding agents explained — what makes a task delegable
• The Copilot cloud agent — the assignment mechanism
• Issues — the general practice

The components

Five parts. A delegable issue has all of them; a poor one is usually missing three.

1. Observable behaviour. What is happening, specifically enough to recognise when it stops.

2. The cause, if known. Withholding it to see whether the agent finds it wastes a session and often produces a fix in the wrong layer.

3. The intended approach, with a pattern to follow. A pointer to working code in the same repository is worth more than a paragraph of description.

4. How it will be verified. This is what gives the loop a correction signal. Without it the session is generating rather than converging.

5. What is out of scope. The single most effective line against scope drift.

Weak:

Users are complaining that data looks out of date sometimes.
Please fix.

Delegable:

## Behaviour

GET /api/users/:id returns stale data for up to 60 seconds after a
successful PATCH to the same user.

Reproduce:
1. PATCH /api/users/42 with {"name": "New"}
2. Immediately GET /api/users/42
3. The response contains the previous name

## Cause

Confirmed: the cache in src/cache/user-cache.ts is populated on read and
never invalidated by the update path in src/services/user-service.ts.

## Fix

Invalidate the cache entry in updateUser() after a successful write.
Follow the pattern in src/services/order-service.ts:changeStatus(), which
does the same thing for orders.

## Verify

Add a test to src/services/user-service.test.ts asserting that a read
immediately after an update returns the new value. The fixture in
test/fixtures/users.ts has what you need.

## Out of scope

Cache TTL configuration, other services' caches, the cache implementation
itself.

That takes five minutes. It is five minutes that would otherwise be spent reviewing a confused pull request, at a worse exchange rate.

The economics

Worth being explicit, because the instinct is that delegation should save the specification time.

Time to write a precise issue: five to fifteen minutes for something non-trivial.

Time to review a pull request from a precise issue: five to ten minutes.

Time to review a pull request from a vague issue: twenty to forty, plus the rounds of feedback, plus the possibility of closing it and starting again.

Time to just do the work: varies, and is the number to compare against.

The conclusion is uncomfortable and correct: delegation does not reduce the total work, it moves it. The specification and the review are yours either way. What you gain is that they happen at times you choose, while the implementation happens while you are doing something else.

That is genuinely valuable for a queue of well-understood tasks. It is worth nothing for a single task in front of you that you could finish in twenty minutes, and recognising the difference is most of the skill.

What not to delegate

Some issues should never be assigned to an agent regardless of how well they are written.

Anything needing a conversation to specify. If writing the issue requires deciding something, the deciding is the work.

Architecturally consequential changes. The decision needs context that lives in people.

Anything where you would not accept a stranger’s implementation. Authentication, payments, anything where a subtle error is expensive.

Work you were about to learn from. Delegating the task that would have taught you the subsystem is a trade, and one worth making deliberately rather than by default.

Anything unverifiable. No test, no type check, behaviour only visible in production.

The honest test: could you write this issue for a contractor who starts tomorrow and has no access to your team? If yes, delegate it. If the answer involves “well, they’d need to ask about…”, that is the part that is not delegable.

Turning a user report into a delegable issue

Most issues do not arrive delegable. They arrive as a user report, which is a different document with a different author.

Title: Profile page sometimes shows the old name

Reported by support. Customer changed their name in settings, the change
saved, but the profile page kept showing the old name for a while. They
refreshed a few times and eventually it updated. Happened to two customers
this week.

That is a good bug report. It is not a task, because it contains no cause, no approach and no verification — and the person who filed it was not in a position to supply any of them.

The intermediate step is engineering work. Somebody has to reproduce it, locate the cause, and decide the approach. That is the part that cannot be delegated, and skipping it is the commonest reason a delegated task goes wrong: the agent is handed a symptom and asked to produce a diagnosis, which is the one thing in this workflow it is worst at.

The workflow that works:

1. Triage the report. Confirm it is real and reproducible. This can be assisted — an agent reading the report and the relevant code can produce a shortlist of candidate causes — but the confirmation is yours.

2. Reproduce it. Write the failing test if you can. A reproducing test converts the whole task from ambiguous to verifiable in one step, and it is the single most valuable thing you can add.

3. Locate the cause. This is the diagnosis, and it is the highest-judgement part.

4. Decide the approach. Which layer, which pattern, what not to change.

5. Write the delegable issue with the five components, linking the original report.

6. Assign it.

Keep the two issues separate, linked. The user report stays as filed — it is the record of what somebody experienced. The delegable task references it. Rewriting the original report into a specification loses the reporter’s own words, which matter when the diagnosis turns out to be wrong.

Where AI helps in that sequence: steps one and three, as analysis. An agent reading the report alongside the code can suggest where to look, and that suggestion is a starting point for your investigation rather than a conclusion. The history analysis techniques apply directly.

Issue templates for delegation

Templates make the five components the default rather than something you remember.

name: Delegable task
description: A task specified precisely enough to assign to an agent
body:
  - type: textarea
    id: behaviour
    attributes:
      label: Observable behaviour
      description: What happens now, and how to reproduce it
    validations:
      required: true
  - type: textarea
    id: cause
    attributes:
      label: Cause
      description: If you know it, say so. If you do not, say that too.
    validations:
      required: true
  - type: textarea
    id: approach
    attributes:
      label: Intended approach
      description: What should change, and an existing pattern to follow
    validations:
      required: true
  - type: textarea
    id: verify
    attributes:
      label: How to verify
      description: The test that should exist when this is done
    validations:
      required: true
  - type: textarea
    id: scope
    attributes:
      label: Out of scope
      description: What should not change
    validations:
      required: true

Every field required. The template’s value is that it will not let you skip the parts you were going to skip.

“If you do not know the cause, say that too.” An issue stating “cause unknown, start by reproducing” is a legitimate and useful specification. An issue silently omitting the cause is ambiguous.

Keep it separate from your general bug template. A bug report from a user should be easy to file. A delegable task is a different document with a different author and a different purpose, and merging the two makes bug reporting harder for no gain.

Assigning and monitoring

1. Write the issue with all five components.

2. Assign it to the agent. The issue body is the entire brief.

3. Check the session started cleanly. Setup failures are the commonest silent problem, and they leave the session with no verification signal.

4. Leave it alone. Watching an asynchronous session defeats the purpose.

5. Read the pull request using the order in reviewing agent pull requests — file list, .github/, dependencies, test diff, then the code.

6. Comment specifically, or close. Bounded corrections work. Three rounds on the same misunderstanding means the issue was wrong.

7. Confirm the issue closes when the pull request merges, so the backlog reflects reality.

Batching

Several issues at once changes the constraint.

The limit is your review capacity, not the agent’s throughput. Five pull requests is five careful reviews of unfamiliar changes, which is slower per change than reviewing a teammate’s work.

Batch by area. Five issues in the same subsystem review much faster than five scattered ones, because you keep the context between them.

Do not batch until one has worked. Learn what good output looks like in this repository before committing to reviewing five at once.

Stagger the assignment. Five pull requests arriving simultaneously is a queue. Assigning them over a day means they arrive as you have time.

Label them. An agent label makes the population visible and makes it possible to ask later how the delegation is actually going.

Task types and how to specify each

The five components apply everywhere; what fills them varies by task shape.

Bug fix. The strongest case. Behaviour is the reproduction, cause is the diagnosis, verification is a test that fails without the fix. If you have a failing test, this is close to ideal delegation.

Adding a feature that follows a pattern. Behaviour becomes “what it should do”; the pattern pointer does most of the work. “Add pagination to /users, matching /orders exactly, including the response envelope and the Link header” is a strong brief because the target is unambiguous.

Mechanical migration across many files. Behaviour is the transformation rule. Verification is that everything still compiles and the tests pass. Out-of-scope matters most here, because a sweep across forty files is exactly where unrelated improvements creep in. State that the change should be only the transformation.

Test coverage for existing behaviour. The trap is that tests written from the implementation describe it rather than specify it. Say what the behaviour should be, not “add tests for this module” — and where you know the edge cases, list them.

Documentation from code. Works when the source of truth is in the repository. Fails when the documentation needs to explain why, because why is not in the code.

Dependency upgrade. Behaviour is the target version, verification is the test suite, and out-of-scope is “do not change application code to accommodate the new version without saying so”. That last clause matters: an upgrade that quietly rewrites call sites is a much bigger change than an upgrade.

Refactor. The hardest to specify well, because the desired end state is a judgement about structure. Delegable when you can name the target precisely — “extract the retry logic from these three files into src/http/retry.ts and update the call sites” — and not delegable when the brief is “clean this up”.

The generalisation: the more precisely the finished state can be described without describing the work, the better the task delegates. That is why bug fixes with reproducing tests are the best case and open-ended refactors are the worst.

Closing the loop

The part teams skip, and where the improvement compounds.

When a pull request needed substantial rework, ask why. The answer is almost always in the issue — a missing component, an assumption that was not stated, a scope boundary that was not drawn.

Fix the template, not the individual issue. If three issues in a row produced scope drift, the template needs a better out-of-scope prompt.

Fix AGENTS.md when the problem was context. A convention violated repeatedly is a convention that is not written where the agent reads it. See repository agent configuration.

Fix the environment when the problem was verification. A session with failing setup produces unverified changes every time, and it is a one-off fix with a permanent payoff.

Track the rework rate. Of the last twenty delegated issues, how many merged without substantial human changes? That number is a measurement of your issue writing, not of the agent, and it improves when you treat it that way.

Tip

The single highest-return habit: when an agent pull request disappoints, spend two minutes asking what in the issue would have prevented it. The fix applies to every future task rather than to this one, and it is the difference between delegation that gets better and delegation that stays frustrating.

When the agent asks a question

Sometimes a session reports that it could not proceed, or produces a pull request with an explicit uncertainty noted.

Treat that as the system working. An agent that says “the issue does not specify what should happen when the user is already deleted” has found a genuine gap in the specification. That is more useful than a pull request that silently picked one.

Answer in the issue, not just in a comment. The issue is the specification, and the next person to read it should see the resolved version.

A pattern of the same question means a pattern in your issues. If several sessions have asked about error handling, your issues consistently omit it.

Splitting work that is too large

A task that will not fit in one session needs splitting, and the split is a design decision worth making deliberately rather than discovering halfway through.

The signals that something is too large: it touches more than one repository, it has more than one verifiable outcome, it requires a decision partway through, or you cannot describe the finished state in a paragraph.

Split by verifiable outcome, not by file. “Add the database column” and “use the column in the API” are two tasks each with its own test. “Change these four files” and “change those three” is one task badly divided, and the second half cannot be reviewed independently.

Order them so each merges on its own. A first pull request that adds an unused function is reviewable, mergeable and harmless. A first pull request that half-implements a feature is neither. This is the same discipline as good pull request scoping, applied before the work starts rather than after.

Cross-repository work is always separate tasks. A session works in one repository. A change spanning a service and its client is two issues, two sessions and two pull requests, with the dependency stated explicitly in both.

Write the dependency down. “Blocked by #412” in the second issue, so that assigning them in the wrong order is visible rather than confusing.

Do not split so far that the overhead dominates. Six issues each taking five minutes to write, for work that would take an hour to do, is not a good trade. The unit worth delegating is roughly “an afternoon of somebody’s work, precisely specified” — smaller than that and the specification cost eats the benefit.

Common mistakes

“See the thread.” There is no thread. The issue body is everything.

Omitting the cause when you know it. Wastes a session and often produces a fix in the wrong layer.

No verification statement. The loop has nothing to converge on.

No out-of-scope line. The most common source of scope drift.

Delegating a decision. If the issue requires deciding something, the deciding is the work.

Batching before one has worked. Five simultaneous reviews of output you cannot yet calibrate.

Not closing the loop. The same problems recur because nothing upstream changed.

Treating the rework rate as a fact about the agent. It is a measurement of your specifications.

What the backlog looks like afterwards

Delegating changes the shape of a backlog, and not always for the better.

The good change: the well-specified tail gets shorter. The tasks everybody agreed should happen and nobody prioritised — the missing test coverage, the deprecated call sites, the documentation nobody wrote — become tractable, because the cost of doing them dropped and the cost of specifying them was always low.

The bad change: the backlog fills with tasks that were delegated because they were unpleasant rather than because they were suitable. Unpleasant and hard-to-specify correlate strongly, so this produces a queue of pull requests nobody wants to review either — and an unreviewed agent pull request is worse than an unstarted task, because it looks like progress.

The subtle change: specification quality across the whole backlog improves, because the discipline of writing five components transfers. Issues written for people get better as a side effect, which is a genuine benefit and one nobody predicts.

What to watch: the ratio of open agent pull requests to merged ones. A rising number of open ones is a review-capacity problem presenting as a productivity gain, and the correct response is to delegate less rather than to review faster.

The habit worth keeping: decide what to delegate from the top of the backlog, not the bottom. The tasks worth doing are the tasks worth delegating, and using an agent to work through things that were never going to be prioritised is a way of generating work rather than completing it.

Mental model

The issue is a brief for a contractor who starts immediately, cannot ask questions, and will do exactly what it says.

Every part of the practice follows. State the behaviour because they cannot see your screen. State the cause because you know it and they do not. Point at an existing pattern because it is the cheapest way to convey a convention. State the verification because that is how they know when to stop. State what is out of scope because otherwise they will reasonably improve things you did not want changed.

Write it that way and the pull request is usually right. Write it any other way and the pull request is an answer to a question you did not ask.

What you learned

• A delegable issue has five components: behaviour, cause, approach with a pattern, verification, out-of-scope
• Delegation moves the work rather than removing it — specification and review are yours either way
• Some issues should never be delegated regardless of how well written they are
• Issue templates with every field required make the components the default
• Review capacity, not agent throughput, is the limit on batching
• The rework rate measures your issue writing; closing the loop is where it improves
• An agent asking a question has found a real gap — answer it in the issue

Exercise

Use a disposable repository with agent assignment available.

1. Write a vague issue — two sentences, no cause, no verification. Assign it. Note the review time and the rework needed.

2. Write the same task with all five components. Assign it. Compare.

3. Create an issue template with the five fields, all required. Use it for a third task.

4. Deliberately omit the out-of-scope field on a fourth. Predict: does scope drift appear?

5. Write an issue with an ambiguity you know about. Predict: does the session ask, or pick one?

6. For any pull request that needed rework, identify the line in the issue that would have prevented it. Add it to the template.

7. Delete the repository.

Related lessons

The Copilot cloud agentWhat happens after the assignment.

Reviewing agent pull requestsReading what comes back.

Repository agent configurationThe context an issue should not have to repeat.

GitHub IssuesTemplates, labels and the general practice.