Suggestions Tool

Overview

The Suggestions tool is the internal home for ideas about Nucleus itself. Anyone on the team can submit a suggestion, upvote others, and discuss in the comments. Admins (Heads and Executives) move suggestions through a status lifecycle and can promote them straight into a GitHub issue — optionally tagging it so the orchestrator picks it up as an autonomous build.

Features

• AI duplicate detection — While drafting a new suggestion the form embeds the draft (Workers AI, @cf/baai/bge-small-en-v1.5) and shows existing suggestions above a 78% cosine similarity. Users can upvote/view those instead of creating a duplicate, or continue with a new one
• Submit + browse — Any user can post a suggestion and view all suggestions in the list
• Upvotes — One vote per user per suggestion; click again to remove
• Comments — Threaded discussion on each suggestion (delete your own; admins can delete any)
• Status lifecycle — New → Planned → In Progress → Shipped (or Declined)
• Sort + filter — Top (by upvotes) or Newest; filter by status; full-text search
• Promote to GitHub — Admins create a GitHub issue in the nucleus repo with one click; the issue URL and number are stored back on the suggestion
• Promote to orchestrator — Same as above, but the issue is created with the nucleus:ready label so the orchestrator’s groomer picks it up as a build candidate

Permissions

Level	View	Submit / Upvote / Comment	Change status	Promote to GitHub / orchestrator
Executive	Yes	Yes	Yes	Yes
Head	Yes	Yes	Yes	Yes
Manager	Yes	Yes	No	No
Lead	Yes	Yes	No	No
Employee	Yes	Yes	No	No

Status lifecycle

Status	Meaning
new	Fresh submission, not yet triaged
planned	Triaged and accepted, scheduled for future work
in_progress	Being built (likely already a GitHub issue or orchestrator run)
shipped	Live in production
declined	Considered and won’t be built

Notifications

• Status changed — author + every upvoter automatically get notified (in-app + Slack DM) when a suggestion moves to a new status. Actor (the admin making the change) is excluded.
• New suggestion submitted — opt-in per user. Defaults to off. To subscribe, go to Settings → Notifications → New Suggestion Submitted and toggle in-app or Slack on. Suits product owners who want to triage every new idea regardless of role.

Slack integration

The Nucleus Slack bot listens for @-mentions in any channel or DM it’s in. When you mention it (e.g. @nucleus can we add dark mode?), the bot:

1. Looks up your Slack email and matches it to a Nucleus user (users:read.email scope required)
2. Runs the same semantic + lexical similarity check as the in-app submit form
3. Replies in-thread with the top matches (if any) and a Create new suggestion button
4. Suggestions are never auto-created — the user has to click the button to commit

If no Nucleus account is found for the Slack user’s email, the bot replies asking them to sign in to Nucleus first.

Under the hood: Slack signs every request with the workspace signing secret; the worker verifies HMAC-SHA256 against x-slack-signature, rejects anything older than 5 minutes or unsigned, ACKs within 3 seconds, and runs the actual work via executionCtx.waitUntil(...).

Promotion flow

When an admin clicks Create GitHub issue, the worker:

1. Reads the GitHub PAT and org from the existing connections table (provider github)
2. Creates an issue in the <org>/nucleus repo with the suggestion title and description
3. Appends a footer to the issue body linking back to the Nucleus suggestion, the submitter, and the upvote count
4. Stores github_issue_url and github_issue_number on the suggestion row

Queue orchestrator does the same plus adds the nucleus:ready label, which the orchestrator’s planner watches at build time. The promotion timestamp is stored in orchestrator_promoted_at.

A suggestion can only be promoted once. Attempting a second promotion returns a 409 and the existing GitHub issue link is shown in the UI.