§ Guides

Collecting wishes.

End-to-end guide: invite stakeholders, triage, and merge.

A practical, end-to-end walkthrough for the most common cross-team workflow in SpecGraph: getting feedback from people outside your immediate project team, triaging what comes back, and folding the keepers into the spec without losing the rest.

This page assumes you're a project owner or admin. If you're the recipient of a stakeholder link, see Stakeholder portal instead.

When to run a wish-collection pass #

The natural moments are:

  • Before locking a phase — last-call review from the affected departments and any external reviewers.
  • After a major change — a vision shift, a new feature batch, a re-architecture decision.
  • At a regulatory checkpoint — auditor sign-off, security review, partner approval.

A pass typically runs 3–10 days. Beyond that, the link expiry mechanic starts working against you (see Stakeholders).

1 · Decide who reviews #

Two audiences, two channels:

  • Workspace members (your team, internal partners) — file wishes from inside the project's wish panel, Submit a wish tab. They already have spec access; nothing to set up.
  • External reviewers (regulators, customers, vendors, partner PMs) — get a private 14-day stakeholder portal. One link per person, never shared.

Mixing is fine. The wish triage UI labels each row with its origin so you always know who said what.

2 · Invite the external reviewers #

Open the project's Share panel from the right rail. For each reviewer:

  1. If they're a frequent contributor, pick them from the address book combo — fills email, name, organization, and department in one click.
  2. Otherwise type the four fields manually.
  3. Click Send invite. A toast confirms the email was queued; the row appears in the list with a pending badge until the recipient opens the link.

If you'll invite the same group again on the next project, take 30 seconds to add them to the address book now.

If the email fails (rate limits, bad address), the row shows a red "send failed" badge with the underlying error. Hit Resend once you've fixed the address; Copy lets you send the link through Slack or wherever instead.

3 · Tell reviewers what you want #

The portal is self-explanatory but a one-line ask helps. A pattern that works:

"I'm closing the architecture phase Friday. The portal link below shows the current draft. Please file wishes against any section using the File a wish button — flagging concerns is more useful than ✅. Priority blocking if it would stop you from approving."

Be explicit about the deadline and what blocking means in this context. Reviewers default to important; they only escalate when nudged.

4 · Watch the inbox fill #

Open the Wishes panel (right rail). The header shows a pending-count badge that reflects un-triaged wishes across all phases. The Inbox tab splits into:

  • Pending · N — newly filed, awaiting a decision.
  • Handled · M — accepted / deferred / rejected / merged. Stay-around for traceability.

Every row shows:

  • The phase and the submitting department.
  • A Stakeholder badge (with name, email, organization) if it came in through a portal link, or a "from <department>" line for org-member submissions.
  • The priority and current status.
  • Any AI-detected conflict tag from a previous accept.

Sort and scan; you don't have to triage in arrival order.

5 · Triage #

For each pending wish, click one of:

Accept #

Marks the wish as approved. Accepting does not change the spec yet — it just moves the wish from Pending to Handled with status accepted. That decoupling is intentional: it lets you blast through triage in one sitting and apply changes later.

When you click Accept, the dialog runs an AI conflict check against the project's other open wishes (and against the feature list, if you're accepting on the features phase). Within ~5–15 seconds you'll see:

  • A list of overlapping items, each with a one-line reason.
  • A pre-checked Tag this wish as a conflict on accept box.

Leaving the box checked stamps the accepted wish with a conflict chip and the matched IDs, so the merge step later replays a warning. If there are no overlaps, the block stays silent.

Defer #

Parks the wish without rejecting it. Use when the request is on-topic but blocked on an external decision ("we'll know after legal weighs in"). Stays visible in Handled; doesn't count as pending.

Reject #

Closes the wish. The reason field is required — be specific, because stakeholder submitters see your reason in their portal under "My wishes". A good reject reason explains why and points at what would change the answer:

"Out of scope for v1 — we want to ship the single-tenant flow first. Refile this for the v2 multi-tenant epic when it spins up."

6 · Merge the keepers #

Accepted wishes whose phase is vision, features, brief, design, architecture, quality, or security show a Merge into section button. Click it to open the merge dialog:

  1. The dialog snapshots the current section and asks the AI for a surgical edit that addresses only this wish.
  2. ~10 seconds later you get a field-level diff: changed strings render before/after, arrays show +/− lines, object arrays group adds/removes/modifications.
  3. Apply changes writes the proposal to the section and marks the wish merged. Discard leaves the wish accepted so you can hand-edit the section instead.

If the AI can't find a place to land the wish ("No changes proposed"), the section probably needs a manual edit — open the section view directly and change what's needed.

If the wish was tagged as a conflict at accept-time, the merge dialog shows an amber warning at the top so you don't merge the same idea twice. The warning doesn't block the merge — it just makes sure you saw it.

Merge runs against the snapshot taken when you opened the dialog, not whatever's in the database when you confirm. A teammate editing in parallel won't get silently overwritten.

7 · Close out #

Once the inbox is empty (or only deferreds remain), let reviewers know what landed. A short close-out note in the same channel they got the invite from is enough:

"Merged 6 wishes (2 from you), deferred 3 pending the legal call, rejected 1. The architecture phase is now locked. Thanks for the careful read."

The Handled list and the audit log keep the per-wish trail; you don't have to summarise it line by line.

If a reviewer's done for good, Revoke their stakeholder access from the Share panel. Their existing wishes stay in your queue, marked Stakeholder · revoked on the triage row, so the trail is preserved even after the link is dead.

Anti-patterns #

  • Mass-rejecting without reasons. Stakeholders see the reason. A blank rejection burns the relationship.
  • Accepting without merging. Accepted-but-not-merged wishes pile up and the spec drifts from "what was approved." Block out time to run the merge step.
  • Treating wishes as todos for the team. They're suggestions. If something must happen, make it a feature in P-02 — don't leave it as a pending wish.
  • Using a stakeholder link for someone who'll touch many projects. Make them a workspace member instead — see Team & invites for the right role.