How Release Intelligence works

Release Intelligence is a workspace-centric hub for a single question: what shipped, in which environment, with what risk, and how we told customers and support.

Each release is a record with title, dates, owner, team, environment (development, staging, or production), status, type (feature, bugfix, and so on), customer impact, QA notes, deployment and rollback context, linked flags, PRs, screenshots, optional AI-generated briefs, and linked issues when work was tracked in the project-management layer.

Release Intelligence combines a Linear-style execution layer (issues, projects, cycles per squad) with a release and communication hub (changelog, digests, AI copy). Squads, permissions, and GitHub integrations are shared across both.

The most common onboarding question: do I start with an initiative, a project, or an issue? Here is the short answer — the full guide lives in docs/linear-workflow-guide.md.

The stack

Initiative     → org strategy (optional)
  └── Project  → squad product area (recommended before many issues)
        └── Issue   → daily work (required for tracked execution)
              └── Release → shipment + changelog (when you ship)

Quarter plan   → leadership commitments this quarter (links releases, not issues)

What to create first

• Small squad, keep it simple — Project → Cycle → Issues → Release when done. Skip initiatives until you need multi-squad strategy.
• Planning a quarter (PM / lead) — Initiatives → Projects (link to initiatives) → Quarter plan commitments → Lock plan → Cycles → Issues.
• Engineer on Monday — Open My issues or squad Issues; you rarely create initiatives or projects yourself.
• Shipping this week — Mark issues done → Create release from issues → QA, changelog, digest.

Where to go

• /app/my-issues — your assigned work
• /app/t/{squad}/issues — squad backlog and board
• /app/initiatives — workspace strategy
• /app/t/{squad}/projects — product areas
• /app/quarter-plan — planned vs shipped this quarter
• /app/planning — timeline across initiatives, projects, and quarter items
• /app/releases — ship and communicate
• ⌘K — search and jump anywhere

Initiative vs project: initiatives are workspace-wide strategy; projects are squad-scoped and hold issues. Link a project to an initiative when the work rolls up to a bigger bet. Quarter plan vs initiative: initiatives span time; quarter plan records what you committed to ship in a specific calendar quarter (via linked releases).

Use Issues, Projects, and Cycles in the app sidebar for squad-scoped planning and delivery — similar to Linear, but inside the same workspace as your releases.

Issues

Each issue has a readable key SQUAD-42 (squad slug + number), status (backlog through done), priority, assignee, project, cycle, and optional acceptance criteria. Open a squad from the team switcher: /app/t/{squad}/issues. Switch between list (inline edits, multi-select) and board (kanban). Blocker badges flag stale work, missing assignees, and overdue dates.

Projects

Projects group issues by product area or initiative (e.g. onboarding, billing). Each project belongs to one squad. /app/projects redirects to your default squad's project list.

Cycles

Cycles are squad iterations with start/end dates and an optional goal. Use Suggest plan to propose backlog items (AI when OpenAI or Anthropic is connected; otherwise priority-based fallback). View cycle scope from View issues in this cycle or the cycle filter on the issue list.

Linear-like habits in Release Intelligence

• ⌘K — command menu: search issues, jump to pages, create issue.
• C — quick create issue (when not typing in a field).
• Team switcher — change squad on issues/cycles/projects routes; URLs stay shareable per squad.
• GitHub PRs on issues — import manually on the issue Engineering tab; webhooks can auto-link when the PR title or branch matches an issue key or title.
• AI draft issue — paste rough notes in the create modal to structure title, criteria, and labels (requires AI integration).

For a full reference (API routes, migrations, webhook behavior), see docs/project-management.md in the repository. Apply migrations 0043 and 0044 before production use.

Linear-style tools excel at getting work done. Release Intelligence adds what happens after merge: customer-facing narrative, QA evidence, flags, changelog, and digests. The bridge is explicit — you don't maintain two disconnected systems.

1. Plan and execute in cycles: move issues from backlog → done; link GitHub PRs on each issue.
2. Create a release from done issues — from the issue list (multi-select) or issue detail. This creates a release record and links those issues.
3. Enrich the release as today: environment, status, flags, screenshots, QA notes, PRs at the release level if needed.
4. Generate AI release intelligence — linked issues are included in context so summaries reflect actual shipped work items, not only free-text fields.
5. Publish — public changelog, subscriber digest, Slack where configured.

On the release Engineering tab, linked issues show identifiers and status. You can add or remove links without re-creating the release. Existing GitHub webhook behavior for release PRs is unchanged; the same events can also update issue PRs and suggest new issue links when none exist.

Quarter plan and the dashboard still measure releases as the commitment/shipment unit for leadership views; issues feed those releases rather than replacing them.

Issue analytics live in two places: Dashboard → Execution (org-wide squad comparison) and Insights per squad (/app/t/{squad}/insights).

Release graphs (Overview, Squads, Delivery tabs) still measure ships, DORA-style delivery, and quarter plan. Execution graphs measure issue flow:

• Throughput — created vs completed over time
• Status mix — backlog through done
• By assignee — open workload or completions in period
• Cycle burndown — remaining scope vs ideal line for the active cycle
• Org rollup — open, completed, or blocker counts compared across squads

Filter squad insights by period (7 days, month, quarter) and by assignee. Use the member toggle on the assignee chart to switch between open workload and completed work.

The AI assistant (sparkles icon in the topbar, or ⌘⇧A) answers questions using live workspace data — not only release-level AI on a single record.

It can:

• Search and list recent issues (respects the active squad when you are on a squad route).
• List blockers among active issues (unassigned, stale in progress, overdue).
• Summarize the latest release and linked issue count.

With OpenAI or Anthropic connected under Integrations, answers are written in natural language from tool results. Without a provider, you still get structured fallback text from the same data. Try prompts like "What is blocked?", "Recent issues", or "Latest release".

This is separate from AI release intelligence on a release detail page (executive summary, comms tabs) and from cycle suggest plan on the Cycles page — all share the same integration credentials when configured.

You add data by creating and editing releases from Releases in the app. Status and environment drive what appears on the dashboard and in promotion-oriented lists.

Typical statuses include Draft, Scheduled, In QA, Monitoring, Released, and Rolled Back. Your team chooses the status that matches your process; the product uses those values to group work on the dashboard.

Rich text is supported on narrative fields so release descriptions and impact notes stay readable when pasted from docs or tickets.

Period filter

The top metrics, charts, and Recent releases list respect the dashboard period (week, month, quarter, or custom range). Shipped production releases are counted in the month or quarter they actually shipped (from status history); in-flight work still uses the planned release date.

Recent releases

Shows production-environment releases in the selected period, newest first. Draft and development work stays in Upcoming releases until you promote the record to Production.

Upcoming releases

This list is not limited by the period filter. It shows the next few releases whose status is one of:

• Draft — captured but not yet committed to a launch window.
• Scheduled — on the calendar for a planned ship or review.
• In QA — actively under validation.

How to populate it: create releases from Create release (or edit existing ones) and set status to Draft, Scheduled, or In QA. When a release moves to Monitoring, Released, or Rolled Back, it leaves this list by design.

Staging → production

This queue lists releases whose primary environment is Staging and whose status is In QA, Monitoring, Released, or Scheduled — i.e. work that is still anchored on staging before you promote the same release record to production. When you are ready, update the release to Production (and adjust status) and it drops out of this queue.

Releases by environment

Three columns summarize releases in the selected period for Production, Staging, and Development, so you can compare volume at a glance.

Activity log

Workspace actions (membership, release edits, integrations, and similar) live under Logs in the app sidebar.

Quarter plan (quarter period only)

When the dashboard period is set to Quarter, a Quarter plan card compares commitments to what actually shipped. Manage the full list from Quarter plan in the app sidebar.

A quarter plan is a commitment layer on top of releases: what you agreed to deliver in a calendar quarter, separate from day-to-day pipeline status.

Plan items are short commitments (title, optional squad and release type). Link one or more releases to each item from a searchable picker limited to releases dated in that quarter.

Lock plan when the quarter’s commitments are final. Items added after the lock remain visible but do not increase the Planned count — so mid-quarter additions do not inflate what you committed at the start.

Summary metrics mean:

• Planned — items that counted toward the commitment before lock (or all items if the plan is not locked yet).
• Shipped — a linked release is Production with status Released or Monitoring, and it actually shipped in the quarter (from status history, not the planned target date).
• In progress — linked work exists but has not met the shipped bar yet, or the item status is set to in progress.
• Slipped — the quarter has ended, the item is not descoped, and nothing linked has shipped.
• Unplanned wins — production releases that shipped in the quarter with no plan link (useful for exec reviews).

The quarter plan page groups commitments into tabs (All, Committed, In progress, Shipped, Slipped, Descoped, and Unplanned wins) with counts and search, so you can focus on one execution state at a time. Summary cards at the top jump to the matching tab.

Item statuses you can set manually are committed, in progress, and descoped. Shipped and slipped are derived from linked releases and the calendar quarter.

On a release detail page, AI release intelligence can draft executive summaries, customer impact language, rollout risk, QA checklists, Slack and changelog copy, and overlap signals from linked context (release fields, PRs, flags, linked issues, and so on), when your workspace has the OpenAI integration configured.

The intended workflow is:

1. Generate a draft from current release context.
2. Review tabs (Brief, Rollout, Comms, Signals).
3. Approve when copy is ready for downstream use.
4. Share — for example post to Slack or queue a subscriber digest where Resend and changelog settings allow.

Approved copy helps keep customer communications and internal announcements aligned with the same release record.

On Create release, expand Import from chat to paste a Claude or ChatGPT thread. Your workspace's connected OpenAI or Anthropic integration parses the transcript and prefills the form — nothing is saved until you click Create release.

Use Insert sample prompt to try a realistic example that fills every field (title, squad, dates, QA, rollback, known issues). The sample uses your first workspace squad so matching works out of the box.

Requirements: a real workspace (not sample-data-only mode), editor role or above, and an enabled AI provider under Integrations. Transcripts are limited to 24,000 characters.

Workspace API keys let ChatGPT Actions, scripts, and Claude MCP create and search releases outside the web UI. Owners and admins generate keys under Settings → API keys. Keys look like ri_live_… and are shown only once at creation.

Authenticate with Authorization: Bearer ri_live_…:

• GET /api/v1/releases — search releases
• POST /api/v1/releases — create a draft release
• GET /api/v1/squads — list squads for slug lookup
• GET /api/openapi — OpenAPI spec for ChatGPT Actions

For Claude Desktop, run npm run mcp:release-intelligence with RELEASE_INTELLIGENCE_API_URL and RELEASE_INTELLIGENCE_API_KEY. Tools include list_squads, list_releases, and create_release.

Apply migration 0040_organization_api_keys.sql and set SUPABASE_SERVICE_ROLE_KEY in production before using the API.

Integrations connect external systems to each workspace: for example Jira for keys and sync, GitHub for PR metadata and webhooks (releases and issues), flag providers, LinearB-style delivery snapshots, Slack, Resend for email, and OpenAI or Anthropic for intelligence drafts, issue drafting, cycle planning, and the workspace assistant. Each integration has its own configuration and health signals in Integrations (/app/integrations).

GitHub can be scoped to multiple enabled repositories and a default repo so PR import accepts full URLs,owner/repo#123, or #123 when a default is set.

When a release is public, it can surface on the workspace changelog and embeddable widget. Subscriber digests depend on Resend and approved AI copy where your workflow requires it — see in-app settings for the exact gates.