A support escalation lands: three customers hit the same payment failure this week, one was charged twice, and nobody knows whether the duplicate is created at your end or the processor’s. You have a paragraph of prose and two refunds already issued. The instinct is to open a session and ask Bright to “look into the payment bug”. Resist it. An agent given a vague brief produces confident scope you did not ask for, and you spend longer unpicking it than you saved.

​
Write the issue before you involve an agent

The issue is the contract. Planning, handoff, and the agent’s run all inherit its quality. Capture four things, and separate what you know from what you are guessing:
The unknowns section is the highest-value part. An agent fills any gap you leave with something plausible. Naming the open questions converts them into work items.

​
Set the properties that change behavior

The property rail carries eight properties: Status, Priority, Effort, Assignee, Project, Due date, Labels, and Visibility. Three change what happens next:
  • Project decides where the work is grouped in the Plan section.
  • Priority is how you and your team order the queue.
  • Visibility controls who sees a customer-affecting defect. Set it to Private if the description quotes customers.
Set Effort anyway so the team can size the queue at a glance. Status starts at Triage and ends at Done or Cancelled; Issues has the full set.

​
Decide whether this needs a plan

An issue with a clear next action does not need planning. This one does not have one: the first real step is a diagnosis, and the shape of the work depends on what the diagnosis finds. Press Plan on the issue. Bright builds a brief from the issue itself (title, status, priority, due date, description, and any linked resources), opens the issue’s chat, and submits it. Build does the same for work that is already scoped. Copy to Prompt hands you the brief if you would rather drive the session yourself. If the work is big enough to split, sub-issues turn the plan into trackable pieces. Each one is a real issue with its own properties and its own Plan and Build actions, so you can review and dispatch them separately. Sub-issues live in the parent’s Sub-issues section.
Before you treat planning as done, reopen the issue and confirm the plan and its sub-issues exist. The check costs one click.

​
Review every sub-issue before it runs

Read each proposed sub-issue instead of clicking through. An under-specified parent invites sub-issues that cover setup, docs, and architecture nobody asked for. Approve the ones that follow from the evidence. Deny the rest and say why in the chat, so the next pass starts with your reason in context.

​
Keep the diagnosis, not just the fix

When the investigation answers your unknowns (the retry does reuse the idempotency key), the finding is worth more than the patch. Ask the agent to write it into a document and link it from the issue. The fix ships and disappears into a diff; the document is what keeps the same class of bug from coming back.

​
What good looks like

  • The issue states its unknowns, and each became a sub-issue or a documented answer.
  • Every approved sub-issue traces to a line in the original report.
  • The diagnosis lives in a document linked from the issue, not only in a closed session.