Refining a plan

Refine is the tier where Bridge stops being read-only and starts writing back to your plan files. The mechanism is the chat-with-diffs flow — every change the AI makes shows up as an inline diff you approve before it persists.

This guide walks through the whole workflow.

Prerequisites

A generated Build Plan in the Plan tab.
The Refine tier (or Refine LTD).
A working BYOAPI key.

The flow

1. Open a chat scoped to the plan

From the Plan tab, tap the chat icon on any plan artifact. A new chat opens with the plan in its reference set. You'll see the plan name in the chat header.

You can also add a plan reference to an existing chat by tapping + in the chat header and picking the plan from the picker.

2. Ask for a change

Use plain language. Some examples that work well:

"The data model has three entities but only two of them are used in the user flow. Drop the unused one."
"Add an authentication step to the user flow. Make it lightweight — magic link, no password."
"Tighten the scope: this should be a CLI tool, not a web app."
"Add an acceptance criterion that the prototype works offline."

The more specific your ask, the more focused the diff. Vague asks ("make it better") produce vague diffs.

3. Review the diff

The AI responds with one or more inline diffs in the chat. Each diff is a unified-diff block annotated with the target file (05_tasks.md, 03_architecture.md, etc.) and a one-sentence rationale.

You see exactly what changes. No surprises, no out-of-band rewrites.

4. Approve or reject

Each diff has two controls in the chat:

Approve — writes the change through to the plan file immediately. The diff card collapses to a confirmation chip.
Reject — discards the diff. You can ask the AI to try again with different guidance.

You can approve some diffs and reject others. The AI doesn't make all-or-nothing changes.

5. Iterate

Keep going. Approved diffs become part of the plan; the chat history records what you approved and rejected so you (and the AI on its next turn) have full context for follow-up asks.

Two patterns that work well

The targeted edit

"In 05_tasks.md, task T07 references an entity called User but the data model calls it Account. Fix the reference."

This is a small, scoped ask. The AI proposes a one-line diff. You approve. Done.

The constraint propagation

"Add a constraint to scope: no third-party services beyond the AI provider. Propagate the impact through architecture and tasks."

This is a larger ask. The AI proposes diffs across multiple files — 07_scope.md gets the constraint, 03_architecture.md drops or swaps any third-party dependency, 05_tasks.md adjusts task wording. You approve them as a batch or individually.

Two patterns to avoid

Asking the AI to rewrite a whole file

"Rewrite 01_brief.md to be better." This produces a large diff that's hard to evaluate. Better: regenerate the plan from scratch with updated notes.

Iterating without re-reading

If you approve five diffs without re-reading the file in between, you may end up with a plan that drifts from your intent. After every 2–3 diffs, open the affected file in the Plan tab and skim. Trust but verify.

When to NOT use Refine chat

Big rewrites — regenerate the plan from updated notes instead.
Outside the plan — if you want to write code, do that in your editor; Bridge plans, doesn't implement.
Discovery-stage changes — if you're still exploring whether the plan is right, work in the constellation first (more notes, re-cluster, re-expand), then regenerate.

Tier note

Refine and Refine LTD are the only tiers with diff-approval chat. Free, Discover, and Build can read plans via chat references but can't propose edits.

See Chat for the chat fundamentals.
See Sharing a plan for getting the (now-refined) plan to your coding agent.
See Build Plan output files for the file-by-file structure that the diffs are operating on.