GitHub Copilot planning: the prompt chain we actually run

On this page#

• What changes when an agent does the planning
• The prompt chain
• The gate
• What it gets wrong
• Rollback
• FAQ

What changes when an agent does the planning#

GitHub Copilot planning moves the bottleneck from writing code to validating intent. The agent can inspect files, infer dependencies, and produce a plausible sequence quickly; the expensive failure is approving a plan that misunderstands an invariant, crosses an architectural boundary, or makes rollback impossible.

An agent is useful here because it can compress repository exploration into a reviewable artifact. It is dangerous for exactly the same reason: confident compression hides uncertainty.

A large language model generates likely continuations from context; it does not independently know which repository assumptions are contractual. More context improves its working picture, but context is not proof.

The planning workflow therefore has one purpose: force the agent to expose its interpretation before it edits anything.

| Without a planning gate | With a planning gate | |---|---| | Discovery happens while code is changing | Discovery produces a separate artifact | | Wrong assumptions become diff noise | Wrong assumptions can be rejected cheaply | | Review starts with implementation details | Review starts with invariants and scope | | Rollback means untangling mixed edits | Rollback usually means discarding one bounded change |

This is not a request for a prettier checklist. It is a control system for agent work.

GitHub Copilot’s documentation explains the product’s supported workflows and capabilities. The missing operational detail is how to make a repository-specific plan safe enough to authorize. That requires a prompt chain, not one giant prompt.

Photo by Christina Morillo on Pexels.

The prompt chain#

The chain separates discovery, constraint extraction, planning, challenge, and execution. Each stage has a narrower job and produces evidence for the next one. Combining them encourages the agent to defend its first interpretation instead of revisiting it when repository facts disagree.

1. Establish the change boundary#

Start by prohibiting edits and asking for a map of the affected system. This makes uncertainty visible before the agent becomes invested in an implementation.

Do not modify files.

For this task: [TASK]

Inspect the repository and return:
1. the likely entry points;
2. the execution path through the relevant components;
3. existing tests that constrain the behavior;
4. configuration, persistence, API, and compatibility boundaries;
5. files that appear relevant, with one sentence of evidence for each.

Separate confirmed facts from hypotheses. For every hypothesis, state what
repository evidence would confirm or reject it.

“Do not modify files” is not decorative. Without it, an agent may treat exploration as permission to repair nearby code. Requiring evidence per file also blocks the familiar failure where a plan names plausible directories without establishing that they participate in the behavior.

The same structure works across tools. Claude Code’s official documentation describes its agentic coding interface, but tool choice does not remove the need to distinguish observed repository facts from generated hypotheses.

2. Extract invariants explicitly#

Now ask what must remain true. An invariant is a condition the system must preserve across the change, such as idempotency, authorization, data compatibility, or ordering.

Using only the repository evidence already identified, list the invariants
this change must preserve.

Group them under:
- externally visible behavior;
- data and state transitions;
- security and permissions;
- compatibility;
- operational behavior;
- tests and validation.

For each invariant, cite the file, test, schema, or configuration that supports
it. Mark any requested behavior that conflicts with an existing invariant.
Do not propose implementation yet.

This stage prevents implementation convenience from silently redefining correctness. If the agent cannot support an invariant with repository evidence, it should label the item unresolved—not upgrade a guess into a requirement.

For unfamiliar teams, the free PairFoundry foundations track is the better next step before adopting the full chain. A planning gate only works when reviewers can tell an invariant from a design preference.

3. Produce the smallest viable plan#

Only after the boundary and invariants are visible should the agent design the change. The plan must be ordered, testable, and explicit about what it will not touch.

Create the smallest implementation plan that satisfies the task and preserves
the confirmed invariants.

For each step include:
- files or symbols to change;
- the behavior changed;
- why this step is necessary;
- validation to run immediately afterward;
- rollback boundary.

Then list:
- files deliberately left unchanged;
- migrations or compatibility work;
- unresolved decisions that require human approval.

Do not write code.

“As small as possible” does not mean fewest files. It means the smallest coherent change whose behavior can be validated and reversed. A one-file patch that bypasses an established abstraction is larger in architectural impact than a coordinated three-file change.

For adjacent agent workflows, the PairFoundry workflow library provides the category context; the planning chain here is specifically about authorization before implementation.

4. Attack the plan#

A plan should survive an adversarial pass before a human sees it. Ask the agent to search for counterevidence, not merely restate its own proposal.

Challenge the plan as a skeptical maintainer.

Look for:
- an existing abstraction the plan bypasses;
- callers or consumers it missed;
- tests that contradict its assumptions;
- partial-failure states;
- concurrency, retry, or idempotency problems;
- irreversible data changes;
- scope that is not required by the task.

Revise the plan where repository evidence justifies it. Preserve a short
rejected-alternatives section explaining why each alternative was rejected.
Do not write code.

This is where a plausible plan becomes reviewable. The prompt deliberately names failure classes because an unconstrained “review your plan” request usually produces reassurance rather than criticism.

The gate#

The human gate is approval of the invariants, change boundary, and rollback path—not approval of polished prose. Stop before implementation and reject the plan if a reviewer cannot point to evidence for its critical assumptions or describe how a partial failure will be contained.

The reviewer should answer five questions:

1. Does the execution path match the repository?
2. Are the protected invariants complete?
3. Does every planned edit serve the requested behavior?
4. Can validation detect both regression and incomplete implementation?
5. Can each risky step be reversed without preserving half-migrated state?

Do not approve “the agent will update tests” as a validation strategy. The plan must name which behavior is tested and where the relevant tests live.

This is also the right point to use Review and Repair when the plan or resulting patch needs a structured second pass. The broader PairFoundry packs overview is useful when the problem is not planning alone but the surrounding implementation or debugging workflow.

Photo by Digital Buggu on Pexels.

What it gets wrong#

The most dangerous plans are internally coherent and repository-inaccurate. They read well because the model fills gaps with conventional architecture, naming, and sequencing; detect them by checking whether every important claim is anchored to actual code, tests, configuration, or schemas.

Common failure modes include:

• Invented architecture: The plan assumes a service, layer, or ownership boundary because the names suggest one. Reject claims without a concrete file or symbol.
• Happy-path tracing: It follows the primary call path but misses retries, background work, feature flags, or alternate entry points. Search the plan for state transitions with no failure branch.
• Test-shaped correctness: It proposes updating existing tests without asking whether those tests encode the invariant or merely mirror current implementation.
• Incidental refactoring: It bundles cleanup into the requested change. If an edit is unnecessary for acceptance, remove it from the plan.
• Fake reversibility: It calls a database or schema change reversible without describing compatibility during deployment or partial completion.
• Context saturation: A large repository dump causes important constraints to disappear inside irrelevant text. Prefer targeted discovery followed by explicit evidence.

GitHub Copilot documentation is authoritative for product behavior. It cannot identify the unwritten contract in your repository; that responsibility remains with the maintainer approving the plan.

Rollback#

A clean rollback starts before code is written: isolate the task, record the approved plan, keep unrelated cleanup out, and define reversal per step. If implementation diverges from the plan, stop and re-plan instead of rationalizing the new direction after the diff has expanded.

Use this execution prompt only after the gate:

Implement only the approved plan, one step at a time.

After each step:
1. summarize the exact change;
2. run the specified validation;
3. report unexpected repository facts;
4. stop if an invariant fails or the plan no longer matches the code.

Do not add unrelated cleanup. Do not continue past a failed validation.

If a step fails, revert only that bounded step and retain the evidence that invalidated the plan. Then return to discovery with the newly observed fact.

For persistent or shared state, code rollback is insufficient. Restore compatibility first, confirm readers and writers agree on the state shape, and only then remove the failed path. A rollback that leaves ambiguous data behind is not a rollback.

Photo by ThisIsEngineering on Pexels.

Related reading#

• Python MCP server, with the guardrails that keep it honest
• SQL MCP server — where the agent helps and where it quietly hurts

FAQ#

When should I skip this prompt chain?#

Skip it for isolated, mechanically verifiable edits with no meaningful architectural or state boundary. Do not skip it merely because the diff looks small: authorization changes, migrations, concurrency fixes, and public API behavior deserve a gate even when they touch few lines.

How is this different from asking GitHub Copilot to make a plan?#

A single planning request produces one interpretation. This chain forces separate discovery, invariant extraction, design, and adversarial review, making unsupported assumptions easier to spot before implementation begins.

What is the biggest team collaboration failure?#

Treating agent output as shared understanding. The plan must record repository evidence, unresolved decisions, excluded scope, and rollback boundaries so another engineer can challenge it without reconstructing the entire conversation.

What should I do when implementation reveals that the plan is wrong?#

Stop at the first contradiction, preserve the evidence, reverse the current bounded step, and regenerate the affected portion of the plan. Continuing after the repository disproves an assumption converts a planning error into an architectural one.

When should an agent not be allowed to implement its own plan?#

Do not authorize autonomous implementation when the reviewer cannot verify the invariants, when state changes are hard to reverse, or when the plan depends on undocumented production behavior. In those cases, use the agent for discovery and alternatives, then keep execution under direct human control.