Flow Analyzer — roles, workspaces, and Jira (SaaS direction)

This page is the human-facing companion to the multi-tenant backlog in §12 of tasks/tasks-FlowAnalyzer-PRD.md. It explains who does what, how shared Jira works, how the workspace selector relates to data in SaaS mode, and where to read about credentials and security. Deployments that have not turned on organization mode may still behave like a single-tenant demo (empty / seed / operator-controlled live); those differences are called out below.

Quick links: Marketing home (product overview and sign-in) · Product tour (screenshots of key screens, including Start here, Reporting gap, Improvement actions, Priority matrix, and Results report) · Glossary (dwell, cycle time, lead time, and other flow terms — Slovník in Slovak UI) · Main app (Start here — the Brief — is your home after you sign in)

Administrator guides

Focused manuals for setup roles (English):

In-app help

After you sign in, open Help & guide in the top header (question-mark icon). The sheet shows product orientation for everyone, organization-administrator topics when your role allows, member notes when applicable, a Flow metrics glossary section with a link to the full [Glossary](/glossary) page and quick FAQ (including dwell), and a Sources & hosting area with separate expandable sections for Jira Cloud, Jira Data Center, ClickUp, Asana, Linear, Trello, and general hosting guidance. It complements the manuals above; use it when you are already inside the app.

For definitions of dwell, cycle time, lead time, WIP, and related labels, see the [Flow Analyzer glossary](./flow-analyzer-glossary.md) (public page at /glossary, titled Slovník when the UI is in Slovak).

What's new: the megaphone button in the top header opens the latest product news (release bullets). Dismiss it to hide the highlight until the next publish. For the full history, open View change log in that panel or go to [Change log](/flow-analyzer/changelog).

Home page, sign-in, and registration

Who this is for: anyone opening Flow Analyzer in the browser for the first time, or returning after a break.

What you see first

When your organization uses signed-in access (multi-tenant mode on the server), the [marketing home](/) is a short product overview: what FlowAnalyzer does (Jira-backed flow analytics, the Brief, findings, improvement actions and priorities, results reports, and optional evaluation notes), who it is for, sample screenshots of main screens, and buttons to Sign in or Create organization. For a full walkthrough before you sign up, open the [product tour](/product-tour).

• If you already have an account, choose Sign in, enter your email and password. If your organization already has at least one workspace, you land in the [main app](/flow-analyzer); otherwise you are sent to [Organization and workspaces](/org-settings) to create one (demo seed is optional and added only when you choose it).
• If your deployment allows self-serve signup, choose Create organization. You will be asked for a display name, organization name, email, and a strong password. You must accept the Terms of Service and Privacy Policy; the form explains that your organization is the data controller for workforce and work-tracker data you upload. After the organization is created, sign in with the same email and password. No workspace is created for you automatically—open [Organization and workspaces](/org-settings) to add a workspace: optional demo (seed) for exploration, or a live Jira-backed workspace after you connect Jira.

When “Create organization” is not shown

Some teams run Flow Analyzer without self-serve registration (for example internal pilots). The [marketing home](/) then explains that your administrator must enable organization mode or invite you. Use the Sign in link if you already received credentials, or ask your admin for access.

Signing out

Use Sign out or Logout (wording may vary slightly by screen) when you are done on a shared computer. After sign-out, opening the [main app](/flow-analyzer) will send you back to Sign in until you authenticate again (or open the [marketing home](/) to read the overview).

Jira embed panels (simplified view)

If you open Flow Analyzer inside Jira as a small panel or iframe, you may see a trimmed view (for example an initiative-focused screen) without going through the [marketing home](/). That path exists so Jira can embed the tool conveniently; the full product (sidebar, configuration, organization settings, and so on) is still reached from the normal browser URL your admin shares—open [Marketing home](/) or [Main app](/flow-analyzer) and Sign in there.

Operators configuring hosts, environment flags, and public routes can cross-check Local development and the Operator runbook.

Display language (English and Slovak)

Who this is for: anyone who prefers Slovak UI copy or wants to switch back to English.

Where to find it: use the Language control in the top app header (next to Notes, Improvement actions, and your account menu) after you sign in. The same control also appears in the sidebar footer when the sidebar is expanded. On the [marketing home](/) and other public pages, it appears in the top navigation.

What it does: choose English or Slovenčina. The app remembers your choice in the browser and reloads labels, buttons, and help text on the current page. You do not need to sign out or change organization settings.

What is translated: navigation, dashboards, configuration screens, error messages that the app understands, and most in-product help. Public marketing pages (/, /features, /pricing, /about, /product-tour, and related legal/marketing chrome) also follow your language for headlines, capability titles, persona role lines, and section copy. Core analysis screens — Discipline, Findings, Landscape, Initiative PM, and Sankey (resource flow) — are included in Slovak coverage for tabs, columns, view labels, triage/export chrome, Flow Story markers, and related shared labels (standard acronyms such as DoD, SP, BV, RAG, and CFD stay in English; portfolio grouping uses Tribe / tribes in Slovak copy (English loanword, same as English UI)). Organization and workspaces (/org-settings) chrome — connection and workspace controls, import wizard field labels, SCIM, license plan titles, and integration table labels — is included in Slovak coverage (product and brand names such as Jira Cloud, GitHub, Slack, and Webhook URL stay in English). Configuration section labels and SectionGuidance follow Slovak when you choose Slovenčina (workflow terms and brand tokens such as SLA / Scrum / SAFe stay as documented in the localization reference). Rule names and finding text follow the same language layer as analysis output (Slovak catalogue is generated for the rule engine). On the Rules catalogue detail panel, the Príklady v praxi section shows three curated Slovak coaching situations for each rule (concrete Jira / delivery stories, not generic formula stubs). The JQL Query Builder (opened from Organization and workspaces when editing a workspace JQL scope, or from the Jira connection wizard) also follows your language for dialog title, Simple / Advanced / Import tabs, Cancel / Apply, visual-builder labels, syntax-help headings, import empty states, and query preview — Jira field names, operators, and example snippets stay in Jira’s English vocabulary.

What stays English on marketing pages (intentional): product and competitor names (for example FlowAnalyzer, Jira Cloud, ClickUp, ActionableAgile / Nave), contact emails, cookie and tracker identifiers, browser labels, numeric or timing proof stats, plan/status tokens such as Enterprise and Roadmap, the role title Scrum Master, and punctuation-only leaves. Shared product terms such as Truth Gap and Initiative PM use the same Slovak wording as in the signed-in app (Medzera v reportovaní, PM iniciatívy). Portfolio vocabulary on marketing pages uses Tribe / tribes where Slovak copy is translated (English loanword). See Web UI localization for the full marketing allowlist.

Programme note (Slovak completeness): Flow Analyzer is finishing remaining English-identical Slovak message values and hardcoded chrome through a tracked programme (epic #14). Surfaces already shipped in that programme include org-settings chrome, configuration guidance, keyboard shortcuts help, workspace switcher / admin sidebar, and related bug fixes. Further analysis, workspaces-landing, and marketing copy land via child updates; product names stay English per the allowlist in the localization reference.

What is not changed: your Jira issue text, workspace data, and credentials stay exactly as stored in Jira or your organization. Switching language only affects how Flow Analyzer presents the product around that data.

If the control is missing, your deployment may be on an older build; ask your administrator to upgrade. Operators: see Web UI localization.

Who you are in the product (v1)

v1 role model: every person in a company is an organization administrator (org_admin). There is no separate “analyst” seat with reduced powers yet.

People and invitations

Who this is for: anyone adding teammates to the same organization.

Where to find it: open [Organization and workspaces](/org-settings) and scroll to People & invitations.

What you can do there: see Members already in the company, Pending invitations, and how many seats are in use. Enter an email and choose Send invitation. The app shows a one-time token once on your screen—copy it and share it through a channel you trust (the app does not email the token for you unless operators add separate email delivery). The person you invited should create an account or sign in with that exact email, then open [Accept invitation](/accept-invite), paste the token, and confirm. If the token expires, use Resend on the pending row to get a new one. Revoke cancels a pending invite so the old token no longer works.

Why it matters: seats are enforced when someone accepts an invite; pending rows do not consume a seat until then. Separately, copy and support should not promise “private” Jira tokens per person — see Shared Jira.

Shared Jira within your organization

When your org connects Atlassian Jira Cloud or Jira Data Center, the connection is stored once under the company. All members of that company can use workspaces that point at that connection.

• No duplicate credentials per user — access is “member of company that owns the connection,” not a personal PAT copy.
• Onboarding: anyone who can sign in to the org should understand that adding or rotating Jira credentials affects everyone.
• Leaving the company: removing membership removes access to all workspaces and connections for that org in one step.

Full policy: Org-wide Jira sharing. Data shape: SaaS data model.

Workspace selector and your data

The sidebar workspace selector (below the FlowAnalyzer title) chooses the active workspace for your session. That tells the app which snapshot and config to load for dashboards, findings, exports, and analysis runs.

Workspaces catalog: open Workspaces from the sidebar (directly under Home) or choose Workspaces at the bottom of the workspace selector dropdown. This opens [Workspaces](/flow-analyzer/workspaces)—a catalog of every workspace in your organization, grouped by type (live Jira, live ClickUp, live Asana, live Linear, live Trello, demo, import). Use search and filters to find a workspace, open it as your active session, or use the settings icon on a card for details, archive, delete, and import. Add new workspaces from the placeholder card in each group.

Organization settings: for source connections (Jira, ClickUp, Asana, Linear, and Trello), people and invitations, and the full workspaces table, open [Organization and workspaces](/org-settings) (linked from the Workspaces page footer hint and from org administration flows). The License & billing panel shows your plan tier, usage against freemium caps, and Stripe checkout when enabled. Locked sidebar items and in-app Upgrade prompts explain which tier unlocks each capability. You may be prompted for a short product satisfaction survey after key milestones; use Support APIs from in-app flows to message platform operators when your deployment enables them.

When you hit a freemium cap or open a Coach-only screen on Freemium, use the upgrade sheet or Organization settings → License & billing to start checkout or contact sales.

Organization switcher (12.21): if you belong to more than one company, switching org reloads the workspace list for that company so you never mix tenants.

When SaaS mode is on and you are signed in, demo vs live follows the workspace you select. The older in-app Switch data source cookie control is not available in that mode so tenant data cannot be mixed with a browser-wide override.

If you open or script raw API URLs (for example bookmarking `/api/export?…` or calling `/api/analysis/jobs` from curl with your browser session cookies), append `&workspaceId=<id>` for the same workspace the header selector shows; the server rejects mismatched or missing ids so data never crosses workspaces. In-app pages add this for you. Automation without a browser session uses the headless bearer contract in headless-analyze-api.md.

When SaaS is off, operators may still use environment variables plus optional cookie source switching; see Operator runbook.

Freshness for live Jira (webhooks and backup poll)

For live workspaces, your deployment can receive push updates from Jira using a webhook (HTTPS URL scoped to the workspace, plus a signing secret Jira includes on each delivery). You can store that secret per Jira connection when you add or edit the connection in Organization settings, or rely on a single secret configured on the server by your operators. When webhooks are configured correctly, issue changes can reach Flow Analyzer quickly.

Your operators also run a scheduled check (at least about once an hour) as a safety net if a webhook delivery fails or is misconfigured. That job is invisible in the product UI in early slices; it shows up in operator logs and job history like other background work. On Organization settings, the Jira connections table shows Last webhook so you can confirm Jira is reaching the app.

Details for setup: Jira webhooks and data freshness and Operator runbook.

Jira Data Center note: webhooks are most reliable when Flow Analyzer runs on-prem beside your Jira server. If you use hosted Flow Analyzer and Jira sits on a private network, expect scheduled polling as the primary freshness path unless your network team exposes Jira to Flow Analyzer's egress IPs.

Connect Jira Data Center (live workspaces)

Who this is for: analysts and org admins whose organization runs self-hosted Jira (Data Center 9.12+ recommended; 8.14+ supported in best-effort mode).

Why: You get the same Brief, findings, configuration wizard, and rule catalogue as Jira Cloud customers — without migrating to Atlassian Cloud.

Where to find it:

1. [Organization and workspaces](/org-settings) → Source connections → Add connection → Jira Data Center.
2. Create a `jira_live` workspace from [Workspaces](/flow-analyzer/workspaces) and link the DC connection (same workspace type as Cloud-backed Jira).
3. Set project scope or JQL, then open Configuration and Configure from source for issue types and workflow mapping.

What you enter:

• Base URL — the full URL your team uses in the browser, including a context path when Jira is not at the site root (for example https://jira.internal.company/jira).
• Personal Access Token (recommended) — created in Jira for a service account; no password leaves your control path when you use a PAT.
• Basic auth — available with a clear discouraged warning; use only when PATs are not an option.

When validation fails: if Flow Analyzer cannot reach your server, the error explains reachability options (run Flow Analyzer on-prem on your LAN, expose Jira to Flow Analyzer egress IPs for SaaS, or a private link arranged with your vendor). This is expected for firewalled Jira — it is not a bug in your PAT. Your platform administrator handles network and TLS; you handle the connection form.

Shared credentials: like Cloud, one DC connection per organization is shared by every member who can open workspaces that use it.

Connect ClickUp (live workspaces)

Who this is for: delivery leads and org admins who run delivery in ClickUp and want the same flow-health analysis, findings, and Resource Sankey views as Jira-backed workspaces—without exporting CSVs or building ad hoc reports.

Why: ClickUp holds tasks, status history, time entries, and sprint-style lists. Flow Analyzer normalizes that data into the shared rule engine so you can spot bottlenecks, allocation risk, and discipline gaps in one place.

Where to find it:

1. Organization settings (/org-settings) → Source connections → add a ClickUp connection (OAuth or personal API token).
2. Connect ClickUp wizard (/flow-analyzer/connect-clickup) — pick the connection, choose Team → Space → Folder → List scope, confirm status categories, confirm which lists are sprint iterations, preview rule coverage, then create a `clickup_live` workspace.

How it works:

• Scope: you select lists in the hierarchy tree; only tasks in those lists are ingested.
• Status mapping: ClickUp status types (open, custom, done, closed) are auto-mapped to todo / in progress / done; adjust per list in the wizard if needed.
• Sprints: lists whose folder name looks like a sprint or that have start/due dates are candidates; only lists you confirm in the wizard count as iterations for sprint-dependent rules.
• Freshness: ClickUp webhooks mark changed tasks dirty; the app re-fetches task data via the API (webhook bodies are not trusted as the snapshot). A scheduled poll runs as a safety net (same operator cron as Jira live workspaces).
• After connect: open the new workspace from Workspaces, run analysis from the dashboard, and open Resource Sankey when time entries are present.

Shared credentials: like Jira, a ClickUp connection is stored once per organization and shared by all members who can access workspaces using that connection.

Connect Asana (live workspaces)

Who this is for: delivery leads and org admins who run delivery in Asana and want the same flow-health analysis, findings, and coaching views as Jira- or ClickUp-backed workspaces.

Why: Asana holds tasks, section moves, dependencies, and optional custom fields. Flow Analyzer derives status history and normalizes tasks into the shared rule engine.

Where to find it:

1. Organization settings (/org-settings) → Source connections → add an Asana connection (OAuth or personal access token).
2. Connect Asana wizard (/flow-analyzer/connect-asana) — pick the connection, select projects, choose section or enum-field status mode, map section categories, preview rule coverage, then create an `asana_live` workspace.

How it works:

• Scope: only tasks in projects you select are ingested.
• Status mode: board sections (default) derive transitions from column moves; status custom field mode uses a designated enum field (map options in workspace configuration after connect).
• Freshness: Asana webhooks mark changed tasks dirty; the app re-fetches via the API after handshake and signature verification.
• After connect: open the workspace from Workspaces, run analysis, and review findings like any live source.

Shared credentials: one Asana connection per organization, shared by all members with access to workspaces that use it.

Connect Linear (live workspaces)

Who this is for: delivery leads and org admins who run delivery in Linear and want the same flow-health analysis, findings, and coaching views as Jira-, ClickUp-, or Asana-backed workspaces.

Why: Linear tracks issues, workflow states, and state transitions. Flow Analyzer derives status history from issue history and normalizes issues into the shared rule engine.

Where to find it:

1. Organization settings (/org-settings) → Source connections → add a Linear connection (OAuth or personal API key).
2. Connect Linear wizard (/flow-analyzer/connect-linear) — pick the connection, select teams and optional projects, map workflow states to analysis categories, preview rule coverage, then create a `linear_live` workspace.

How it works:

• Scope: issues in the teams (and projects, if narrowed) you select are ingested.
• Status mode: workflow states map to to-do / in-progress / done categories; transitions come from Linear issue history.
• Freshness: Linear webhooks mark changed issues dirty; the app re-fetches via the GraphQL API after signature verification.
• After connect: open the workspace from Workspaces, run analysis, and review findings like any live source.

Shared credentials: one Linear connection per organization, shared by all members with access to workspaces that use it.

Connect Trello (live workspaces)

Who this is for: delivery leads and org admins who coordinate work on Trello boards and want flow-health analysis on cards and list moves.

Why: Trello tracks cards on boards and lists. Flow Analyzer treats each list as a workflow column and derives status history from card actions (especially moves between lists).

Where to find it:

1. Organization settings (/org-settings) → Source connections → add a Trello connection (API token).
2. Connect Trello wizard (/flow-analyzer/connect-trello) — pick the connection, select boards, map lists to to-do / in-progress / done categories, preview rule coverage, then create a `trello_live` workspace.

How it works:

• Scope: only cards on boards you select are ingested.
• Status: list name and your category map drive workflow status; moving a card between lists creates transition history.
• Freshness: Trello webhooks notify the app when cards change; ingest re-fetches affected cards.
• Operator note: your platform admin must set `TRELLO_API_KEY` on the deployment before connections can validate.

Connect ScrumDesk Start (live workspaces)

Who this is for: delivery leads and org admins who run delivery in ScrumDesk Start (cloud) and want flow-health analysis on backlog items.

Why: ScrumDesk exposes backlog items, workflow steps, native status history, worklogs, and sprint metadata over the cloud REST API. Flow Analyzer maps workflow steps to analysis categories and ingests project-scoped backlog items.

Where to find it:

1. Organization settings (/org-settings) → Source connections → add a ScrumDesk connection (integration or personal API token).
2. Connect ScrumDesk wizard (/flow-analyzer/connect-scrumdesk) — pick the connection, select projects, map workflow steps to to-do / in-progress / done categories, preview rule coverage, then create a `scrumdesk_live` workspace.

How it works:

• Scope: only backlog items in projects you select are ingested.
• Status: workflow step and your category map drive workflow status; native history_changes supply transition history.
• Freshness: manual or scheduled re-ingest until outbound webhooks are available from ScrumDesk cloud.
• Note: this connector targets ScrumDesk Start cloud only (api.scrumdesk.com), not the legacy Windows OData API. Request integration tokens from support@scrumdesk.com when needed.

Results report and scheduled delivery

• One-off download: open Results report from the sidebar Overview section for JSON (dashboard + charts) or Markdown (summary and sample findings), scoped to the active workspace when SaaS is on. The HTML report includes an executive summary, Reporting gap (when applicable), Flow focus items (ranked work items with the highest cycle/lead-time impact), Priority matrix (Eisenhower quadrants for findings with linked Jira issues — same ranking as the Priority matrix screen), key metrics, charts (including control chart with rolling average and UCL/LCL), a Hierarchy table, and a Recommendations section with this week’s constraint focus and all ceremony pack types (tribe sync, retro, PI prep, leadership briefing)—the same content as Recommendations in the sidebar. In Hierarchy, Flow quality is the same 0–100 Flow quality index (Index kvality toku) as issue detail; Problem rank is the worst-first order of that score among rows with delivery problems. Default sort is hierarchy order — the legend under the table says so. JSON export includes the same priority matrix items when findings have linked issues. On the HTML preview toolbar, use Share to send the formatted HTML report to a single email address (requires SMTP on the deployment — same settings as scheduled report email).
• Scheduled summaries: on the same Results report page, add and manage schedules (webhook or email) for the active workspace. Each schedule uses Markdown or JSON for the optional signed full export link in the message (PDF is not offered for schedules until PDF export exists in the product). Set Digest mode to Weekly delta (import compare) when you want a short Slack or email summary of what changed between the two newest import snapshots instead of the full dashboard summary. Pick a timezone so daily/weekly/monthly runs follow local calendar boundaries (not a fixed hour count). Use Refresh to reload the list (for example after a cron run). Webhook runs post a short HTTPS message (Slack-compatible). Email schedules send a plain-text summary when the deployment has SMTP configured (see Automated report delivery); recipients are comma-separated addresses. Operators still enable the secured cron runner (same doc, runbook). Test send on a schedule row checks the webhook or email destination once without updating last run. Send code delivers a short-lived verification code only to that destination; enter it next to the row and choose Confirm so the Ownership column shows verified. If your operators enable strict mode for automated delivery, scheduled runs wait until ownership is verified for each schedule. You can type any valid IANA zone; the field suggests common regions.

Resource Sankey and investigation export

Open Resource Sankey from the sidebar (/flow-analyzer/resources) to see how people connect to epics and components in the active workspace, with precious resource scores and bottleneck hints on the chart.

• Findings: when the workspace has a roster (config.org) and a snapshot, ORG- org-capacity rules run with the rest of analysis and appear on Findings (over-allocation, undeclared sharing, squad/PI overcommit, hours vs FTE, discovered or inactive people, and related signals). Field mapping uses workspace config (team field, PI field, story points)—not a single customer’s custom field ids.
• Investigation panel: below the chart on Resource Sankey, browse Issues, People, and Flows tabs (sortable tables). Click an issue key to open the issue detail panel. Download CSV is on the same panel when you need a spreadsheet export.
• Discipline investigation: on the same screen, below the resource investigation panel, review Gate bypass, Coverage, Epic DoD, PI delivery, Operational buckets, Multi-project, and Lean waste tabs. Each tab opens with a short explanation of what it checks: Gate bypass lists issues that jumped statuses while skipping mandatory workflow stages; Coverage shows covered-by requirement links and flags gaps when a requirement is Done but covering work is still open; Epic DoD is a heatmap of checklist completion per epic by DoD stage; PI delivery compares committed versus delivered story points by Program Increment; Operational buckets lists catch-all operational trackers with child heap and growth metrics; Multi-project groups portfolio checks when a parent initiative spans delivery projects—cross-project gate bypass by parent and delivery project, cross-project blocker aging and blocker chain integrity (including late links), parent–child coherence when a parent initiative regresses while delivery children stay active, DoD evidence gaps for checked checklist items without supporting body text, PI label stack on active parents, description versus decomposition gaps, clone continuation pairs, clone PI rollover without scope change, and remote link churn without integrated content updates; Lean waste groups snapshot signals into coaching lenses (waiting, task switching, partially done work, extra processes, motion, extra features, defects) with related rule ids and sample issue keys, and lets you narrow samples to parent initiatives or delivery work. Matching issue keys are outlined on the Sankey chart (stage skips, coverage gaps, weak DoD stages, and multi-project portfolio risk). The same investigation panel is also available under Discipline → Investigation and as a collapsible section on Findings.

Seed-demo workspaces may show the chart layout without RA findings until the snapshot includes worklog history (live Jira or a Jira export import with worklog data).

Org structure (roster, FTE, sharing)

Open Org structure under Advanced analytics → Portfolio (/flow-analyzer/org-structure).

• Who it is for: delivery auditors, tribe leads, and consultants who need to see who belongs where, how capacity is allocated, and who is genuinely shared versus only incidentally assigned across teams.
• Why it exists: roster and FTE already live in workspace configuration, but without a dedicated auditor screen they stay hidden. This screen turns that roster into a chart, tree, and filterable table grounded in your imported or live snapshot—never invented demo people.
• What you see: Tribe → Squad → people as an org chart (default) or expandable tree; a people table (name, employment, role, FTE, primary squad, account, sharing, active); auditor filter chips (Shared only, Outside primary team, Overloaded, Underloaded, Discovered only, and more) that stay in sync with the chart and can be shared via the page URL. Hover a chip for what it includes — several chips combine (a person must match all of them). Import from snapshot when the roster is empty.
• Person side sheet: edit role, employment (internal, vendor, contractor, intern, or other), FTE allocations, sharing scope (squad / tribe / organization), and active flag; review tasks, flow metrics (WIP, cycle/lead time), and linked findings/patterns. Inactive people remain visible (faded) but drop out of capacity totals. Removing a person, squad, or tribe asks for confirmation first.
• Privacy & workforce data: On first visit, org admins choose how people are shown — real names, generated codes, or structure only (tribes/squads/FTE without importing legal names). Storing real names requires an org-admin authority acknowledgment (not per-employee consent). Your organization remains the data controller for roster and workforce data; Flow Analyzer is the processor under your contract. Inform affected staff per your own employment and privacy policies. See Privacy Policy and the operator GDPR workforce plan.
• Example: An architect shows as dedicated to one squad but most active work sits in another tribe—use Outside primary team (not shared) to surface the mismatch and decide whether to formalize sharing or rebalance assignments. Matching ORG- findings also appear on Findings after a rules run.
• Squad sprint capacity: set Sprint capacity (SP) on each squad row. This feeds DV-12 overcommit checks, the Initiative PM → Takt vs delivery rate roster capacity band, and DV-16 staleness when velocity shifts without a roster refresh.
• Epic tribe field (live Jira): configure under Organization and workspaces → workspace details → Jira project → organization units so live ingest stamps _flowAnalyzerEpicMeta.tribe on Epic issues — required for tribe run filters and cross-tribe comparison outside seed mode. See org capacity product doc.
• Capacity change history: each roster save is versioned in workspace configuration. Analysis runs diff squad SP and FTE allocations between saves to drive CFD-10 and DV-16 — you do not need to bump effective_from alone when you change capacity figures.
• Capacity truth panel: when the roster and snapshot both exist, Org structure shows a tribe-level table comparing committed FTE (roster) with actual worklog hours over a 14-day window, observed load %, gap FTE, shared-people count, and a precious-at-risk count joined from Resource Sankey / RA-10 signals — process-level evidence for PMO readouts, not individual performance scores. Open Resource flow (Sankey) from each tribe row (or Org capacity truth from the Sankey toolbar) when justifying hiring or redistribution to sponsors.

Dashboard — Cross-tribe comparison and root cause hypotheses

Open Dashboard (/flow-analyzer/dashboard) when the snapshot contains two or more tribes.

• Who it is for: executives, tribe leads, and PMO comparing delivery health across value streams on one screen (FR-10).
• Cross-tribe table: sortable columns for open issues, WIP vs limit, average cycle time, and critical findings. When Org structure roster is configured, additional columns show configured FTE, observed load %, shared people, and suggested FTE Δ (allocation advisor preview). On Org structure → People, use Apply allocation advisor to write selected FTE / sharing-scope changes to the roster (with confirmation).
• Root cause hypotheses (FR-11): when at least two findings correlate, a block groups them by shared issue, shared rule family, or shared roster person (shared_person for ORG / RA findings on the same person). Each group links to Findings or Root cause causal loop map for deeper exploration.
• Ceremony packs: leadership and PI prep exports include cross-tribe org-capacity bullets when roster data exists.
• Multi-initiative workspaces: when the snapshot lists two or more initiatives and you are not narrowing the portfolio read scope to one tribe/team/sprint slice, the cross-tribe table rolls up open WIP, cycle time, and critical findings across all initiatives. Org-capacity columns (FTE, observed load, shared people, suggested FTE Δ) still come from the workspace roster once — not summed per initiative.

Product reference: `cross-tribe-and-root-cause-fr-10-fr-11.md`, `org-capacity-and-shared-resources.md`.

Map

Open Map from the sidebar (/flow-analyzer/landscape) to see how backlog and findings are distributed across hierarchy, tribes, assignees, components, and rule dimensions.

• Who it is for: tribe leads, Scrum Masters, and delivery managers who want a fast visual read on where scope and rule pressure concentrate before a refinement or portfolio review.
• Views: choose a Backlog layout (initiative hierarchy, tribes, assignees, components, issue types, PI) or a Findings / hybrid layout after a rules run.
• Controls: filter by tribe when your snapshot carries tribal labels; set tile size to issue count, story points, or finding weight; set color to status, severity, rule family, and other attributes.
• Interaction: click a group tile to drill down (breadcrumbs show where you are); click a leaf tile to open the issue detail panel. The side legend and breakdown table summarize the selected level.

Findings views show a clear empty state when no rules run exists yet for the workspace.

Simulation board (findings-grounded what-if)

Open Simulation board at `/flow-analyzer/simulation` (deep link from Findings or root-cause workflows with ?initiativeId=).

• Who it is for: Scrum Masters and tribe leads running retro or refinement who want to test “what if we fix WD-01 / WIP / quality escapes?” before changing process.
• Prerequisites: a persisted workspace snapshot with stage residence and weekly throughput samples, plus active findings that unlock levers (for example WD-01: Missing acceptance criteria → DoR AC coverage slider with base derived from missing_ac_issue_count / open_issue_count).
• Levers: up to three sliders generated from findings — not free-form constants. Disabled levers show an explicit reason when snapshot data is insufficient (no fabricated numbers).
• Live simulate: drag a slider and metrics recompute within ~200 ms (debounced); in-flight runs cancel. Reset all levers returns bases and the scenario column matches baseline.
• Metrics panel: sortable table with Baseline vs Scenario for cycle time P50/P85, throughput, waiting share, WIP, suppressed finding count, and optional scenario finish weeks when open scope and throughput history exist. Dashboard forecast (canonical P50/P85) is labeled separately — scenario output is an illustrative counterfactual and does not overwrite the initiative dashboard strip.
• Out of scope: no write-back to Jira, ClickUp, or other trackers; no replacement of the main Monte Carlo forecast engine.

Product reference: `findings-grounded-what-if-simulation.md`, `flow-optimizer-scenarios.md`.

Flow improvement loop (compare, triage, coaching)

Use these when you are analyzing a delivery portfolio (especially after a Jira export import) and need to turn findings into sustained change:

Assist — AI Agents (Writing Quality, Type & Work Definition, Label Hygiene, Dependency / Flow Risk, Optimization Proposals, Root Cause Synthesis, Constraint & Bottleneck, Predictor, Flow Recovery Facilitator, Planning System Integrity)

Assist — AI Agents (Writing Quality, Type & Work Definition, Dependency / Flow Risk, Resource Constraint, Optimization Proposals, Root Cause Synthesis, Predictor, Flow Recovery Facilitator, Planning System Integrity)

Who it is for: Scrum Masters, coaches, consultants, and RTEs who want advisory coaching from the current workspace snapshot — not a second copy of Findings or VSM.

Why it exists: Rule ids such as TM-05 (meeting tracked as Story), WD-01 (missing acceptance criteria), VS-08 (long blocker chain), FL-01 (WIP overload), and BH-01 (ageing backlog) signal hygiene and waste patterns that are easy to miss in a long findings list. Type & Work Definition explains TM/WD gaps per issue. Dependency / Flow Risk turns VS/FI hits into a ceremony readout. Resource Constraint explains precious people and expert bottlenecks from Resource Sankey scores and RA findings. Optimization Proposals turns FL/WD/BH hits into a refinement workshop agenda grouped by theme. Root Cause Synthesis clusters FL/WD/TM/MI hits into 3–5 retro themes with A3 / 5-Whys why-chains, cited rule ids, optional reinforcing/balancing causal loops, and one experiment each — for copy into retro notes, not to replace the deterministic Retrospective pack. Predictor explains the deterministic P50/P85 labels already shown on the dashboard forecast strip plus VL/BC/SG predictability risks — it never recalculates Monte Carlo finish dates. Flow Recovery Facilitator turns the deterministic 4-week flow recovery plan into a weekly check-in script while copying WIP/Done targets and triage keys exactly from that playbook. Planning System Integrity answers whether the planning loop is healthy / strained / broken from scope KPIs (pctSpDone, scopeAdded, throughput) and BC/SG/VL findings — so teams fix overcommitment and scope churn before blaming delivery. It never invents SP or sprint dates and does not recalculate forecasts (that remains Predictor’s job).

Assist — AI Agents (Writing Quality, Type & Work Definition, Dependency / Flow Risk, Optimization Proposals, WIP & Pull Policy Coach, Root Cause Synthesis, Predictor, Flow Recovery Facilitator, Planning System Integrity)

Who it is for: Scrum Masters, coaches, consultants, and RTEs who want advisory coaching from the current workspace snapshot — not a second copy of Findings or VSM.

How it works: Enable AI assist for the workspace (same gate as before — no silent bypass). Agent cards are grouped into Issue & backlog quality, Initiative metrics & charts, and Workshop & ceremony so you can pick the right specialist faster. Select an agent card and run it for selected issues (or the initiative for Dependency / Flow Risk, Optimization Proposals, Root Cause Synthesis, Case Study Writer, and Predictor). On Select issues, use Filter to search or narrow by type, tribe, team, status, and Problem type (broken rule ids that appear on issues in the list), and Group by to cluster the table (you can select a whole group at once). Columns include Problem rank, Flow quality index (same 0–100 score as issue detail), and Findings count for each Jira item. Rules-only mode always works when no language-model provider is configured. If a language-model provider is configured and you opt into AI narrative, prose may be polished and labeled AI-generated; citations stay grounded in dashboard fields and tool findings. Copy suggestions manually — Flow Analyzer never writes back to Jira, ClickUp, or Asana, never auto-changes issue types, never auto-persists improvement actions, never auto-closes findings, never raises, clears, or edits flags or dependency links, and never recalculates forecast dates for Predictor.

Assist — Case Study Writer (retro facilitation narrative)

Who it is for: Scrum Masters and Agile coaches preparing a retrospective or change workshop.

What problem it solves: Raw finding counts trigger blame. Case Study Writer turns correlated flow signals into a third-person story the team can recognize without seeing real names or internal keys — plus Socratic mirror questions so loops are discovered, not declared.

Where in the UI: AI Agents → Workshop & ceremony → Case Study Writer → Write case study (initiative scope; no issue selection required).

How it works: The agent builds two blocks: team Markdown (privacy-scanned before display) and coach annex (real issue keys, finding deep links, and rule citations — for your eyes only). Copy team Markdown into retro prep; keep the coach annex private. Optional AI polish follows the same consent gate as other agents. Pilot on Demo (seed) initiative SEED-INIT-ENRL before live workspaces.

Assist — Backlog readiness workflow

Who it is for: Scrum Masters, product owners, and tribe leads who need one initiative-level readout when WD-01: Missing acceptance criteria fires across many Story/Feature items — not a manual merge of Findings, Flow health, and spreadsheet counts.

Why it exists: Definition quality on the Brief and Dashboard Flow health radar penalizes WD/TM/ES rule families, but the score alone does not give a refinement plan, project grouping, or ceremony hooks. The Backlog Readiness agent turns the persisted snapshot into a copyable portfolio readout plus deep links.

What problem it solves: You see % missing AC (against ac_required_types, default Story/Feature), epidemic thresholds (≥ 5 items or ≥ 20% of scoped AC-required types), top Jira project prefixes, advisory TQ-06 / TQ-07 text-quality counts (until engine #77 ships persisted findings), a refinement plan, and links to filter the issue picker (brokenRule=WD-01) and Findings (WD-01). Backlog structure mini-histograms (age, story points, priority) appear beside the agent when an initiative is selected.

Where in the UI:

Recommended workflow (advisory — you run each step):

1. Backlog Readiness agent — portfolio readout + epidemic flag + refinement plan.
2. Issue picker — filter Problem type WD-01 (or use agent deep link) → select keys for batch work.
3. Requirements Template — batch AC drafts for selected issues (copy/paste; no write-back).
4. Optimization Proposals — refinement workshop agenda (epidemic block when thresholds met).
5. Root Cause Synthesis — retro theme missing_ac_epidemic when epidemic thresholds met.

Flow Analyzer never writes AC back to Jira, ClickUp, or other trackers.

Assist — Workspace configuration coach

Who it is for: Organization administrators and Scrum Masters setting up a new or partially configured workspace — especially when Configure from source feels overwhelming.

Why it exists: Workspace Configuration has many knobs (workflow, DoD gates, tribe mapping, acceptance-criteria fields). The Workspace config coach skill in AI Chat interviews you one question at a time with quick-answer chips, then proposes a human-readable summary before any write.

What problem it solves: You pick a delivery methodology (Scrum, SAFe, Kanban, hybrid, or help-me-choose), answer focused questions grounded in your connector catalog, review affected config.* sections, and — if you are an organization administrator — apply validated changes in one confirm step. Non-admins can finish the interview and open Configuration or copy the recommendation for an admin.

Where in the UI: Floating AI Chat (bottom-right) → skill Workspace config coach → answer chips on each assistant turn (Type my own answer is always last). After the summary, tap Apply to workspace (admins only) and confirm in the dialog. You can also open Configuration any time to verify or fine-tune.

How it works: The coach reads your current workspace envelope, live source catalog (issue types, statuses, fields when connected), and configuration-related findings (for example WD-01: Missing acceptance criteria, ORG-01, FL-). It does not* invent catalog values. Applying runs the same validation as the Configuration screen; nothing is saved without your explicit confirmation.

Example: You connect a Jira portfolio workspace with Epic/Feature hierarchy and PI-style statuses → choose Help me choose → coach recommends SAFe → you confirm → follow-up questions include SAFe DoD funnel stages and optional tribe field mapping → review summary → apply as org admin → reload Configuration to see updated stage order and fields.

Example: Initiative scope has 12 Story items without AC (24% of AC-required types) → Backlog Readiness headlines epidemic, groups AKVI (5) and BENE (4), lists advisory TQ counts, and links to Findings · WD-01. You filter the picker, run Requirements Template on six keys, then copy the OP section 0 block into refinement notes.

SK — workflow pripravenosti backlogu:

Príklad (SK): 12 Story bez AC (24 %) → agent označí epidémiu, zoskupí projekty AKVI / BENE, odporučí filter WD-01 a batch Requirements Template; OP blok 0 a RC téma missing_ac_epidemic pri rovnakých prahoch.

TQ-06 / TQ-07 vs WD-01: WD-01 fires when the AC field is empty on AC-required types. TQ-06 (empty AC text) and TQ-07 (unstructured AC) are designed as engine findings for Definition quality and Findings exports — shipped via #77 when queued. Until then, Backlog Readiness reports advisory text-quality counts from the snapshot; treat them as coaching signals, not persisted rule hits.

Assist — Backlog structure panel (Backlog Readiness)

Who it is for: Product owners, tribe leads, and Scrum Masters who need a quick shape-of-backlog readout before refinement — not only per-issue WD-01 coaching from the Backlog Readiness agent.

What problem it solves: A long findings list can hide whether the backlog is fresh or stale, estimated or unestimated, and priority-skewed. The structure panel shows three mini-histograms from the persisted workspace snapshot so you judge backlog health at a glance.

Where in the UI: AI Agents → Issue & backlog quality → Backlog Readiness → scope column (right). The panel appears only for this agent when an initiative is selected. It does not show for other agents.

How it works: Counts come from open issues whose status is in workflow.initial_statuses (the same open-backlog filter as IA-01: Age Distribution — Backlog Aging Profile). Three histograms:

Data loads from the backlog-structure API using the active workspace persisted snapshot. If no snapshot exists, the panel shows a localized load error — no invented bar heights. Loading state appears while fetching.

SK — Štruktúra backlogu (Backlog Readiness): V AI agentoch → Kvalita issues a backlogu → Backlog Readiness (len pri zvolenej iniciatíve) v stĺpci rozsahu uvidíte tri mini-histogramy z perzistentnej snímky workspace:

• Vek — počty issues v rovnakých vekových intervaloch ako IA-01: Rozloženie veku — profil starnutia backlogu (0–30d … 365+d). Dlhý chvost v 181+d zodpovedá signálom zastaraného backlogu v Nálezoch.
• Story pointy — rozloženie odhadov (neodhadnuté, 1 SP, 2–3 SP, …) — dopĺňa SP súčty v IA-01, nie nové pravidlo.
• Priorita — počty podľa priority v trackeri — kontext pre poradie refinmentu.

Bez perzistentnej snímky panel zobrazí chybu načítania, nie vymyslené výšky stĺpcov.

Assist — AI Chat (floating conversation)

Who it is for: Scrum Masters, coaches, and RTEs who want a quick conversational explanation of findings or flow health without opening a specialist agent card.

Why it exists: Batch agents are excellent for Writing Quality rewrites or ceremony agendas; day-to-day questions (“why is DEMO-104 flagged?”, “what changed this week?”) fit a floating chat better.

What problem it solves: You stay on Findings, Discipline, or any authenticated screen, open the AI bubble, and ask in natural language. Slash commands (/findings, /cfd, /forecast, /brief, /repeat) and quick prompts seed useful context from the workspace snapshot. Repeat on an assistant reply (or /repeat) re-asks the previous question against the current workspace. Copy puts the message on the clipboard. Optional MCP tools can pull findings, dashboard, or flow story evidence. Threads are saved so you can resume later.

Where in the UI: Floating AI button (bottom-right) on Flow Analyzer when you have an active workspace. Organization LLM settings remain under Organization settings → AI Agents. Chat reuses the same enable AI assist consent as Agents.

How it works: Organization AI Agents must be on and a provider configured. Enable AI assist for the workspace, then send a message. Answers stream as markdown, are labeled AI-generated, and never write back to trackers. Turn MCP off in the chat toolbar when you want conversation-only replies without tool lookups. Use the toolbar skill selector for Flow coach (general flow health) or Backlog readiness (WD-01 / missing-AC coaching — recommends Agents or Findings, never auto-runs agents).

Assist — AI Chat grounded Brief, map, and CFD (#109)

Who it is for: Scrum Masters, RTEs, and flow coaches who ask about Brief constraint focus, root cause map loops, CFD stability, forecasts, or acceptance-criteria quality in the floating AI Chat.

Why it exists: Chat used to prefetch a full dashboard dump and expose multiple tool schemas. That made answers noisy and did not scale as more screens shipped.

What problem it solves: With MCP on, chat uses a single `read_workspace` tool (plus an optional skill-gated scenario helper). Prefetch is a compact workspace digest. Slash /brief, /cfd, and /forecast load those views — the same numbers as the Brief / CFD / forecast screens — not a raw dashboard paste. Ask about map loops or “review AC on ISSUE-1” and answers stay snapshot-grounded. When the assistant suggests deeper causal work, tap Open Agents · Root Cause Synthesis to open the Agents hub with initiative scope — chat never silently runs agents.

Where in the UI: Same floating AI chat as above. Skills include Flow coach, Backlog readiness, and CFD interpreter.

Assist — AI Agents (Writing Quality, Type & Work Definition, Label Hygiene, Dependency / Flow Risk, Optimization Proposals, Root Cause Synthesis, Constraint & Bottleneck, Predictor, Flow Recovery Facilitator, Planning System Integrity)

Who it is for: Scrum Masters, coaches, consultants, and RTEs who want advisory coaching from the current workspace snapshot — not a second copy of Findings or VSM.

Why it exists: Rule ids such as TM-05 (meeting tracked as Story), WD-01 (missing acceptance criteria), VS-08 (long blocker chain), FL-01 (WIP overload), and BH-01 (ageing backlog) signal hygiene and waste patterns that are easy to miss in a long findings list. Type & Work Definition explains TM/WD gaps per issue. Label Hygiene audits the whole snapshot's labels for near-duplicates, stale PI_* tags, taxonomy orphans, and cross-links DV-08 / PL-09 / PL-12 / MI-18 — so PMO and consultants stop exporting label lists to spreadsheets. Dependency / Flow Risk turns VS/FI hits into a ceremony readout. Optimization Proposals turns FL/WD/BH hits into a refinement workshop agenda grouped by theme. Root Cause Synthesis clusters FL/WD/TM/MI hits into 3–5 retro themes with A3 / 5-Whys why-chains, cited rule ids, optional reinforcing/balancing causal loops, and one experiment each — for copy into retro notes, not to replace the deterministic Retrospective pack. Constraint & Bottleneck answers "what is the constraint?" with TOC exploit / subordinate / elevate actions grounded in the weekly constraint pack, findings, and interventions — distinct from the optional executive-summary narrator on the pack itself and from Flow Analysis general health. Predictor explains the deterministic P50/P85 labels already shown on the dashboard forecast strip plus VL/BC/SG predictability risks — it never recalculates Monte Carlo finish dates. Flow Recovery Facilitator turns the deterministic 4-week flow recovery plan into a weekly check-in script while copying WIP/Done targets and triage keys exactly from that playbook. Planning System Integrity answers whether the planning loop is healthy / strained / broken from scope KPIs (pctSpDone, scopeAdded, throughput) and BC/SG/VL findings — so teams fix overcommitment and scope churn before blaming delivery. It never invents SP or sprint dates and does not recalculate forecasts (that remains Predictor's job).

What problem it solves: You can coach refinement on one issue at a time with cited rule ids from the snapshot (never invented defects), clean label debt with a catalog and duplicate clusters grounded in real issue keys, walk an RTE sync with VS/FI sample keys, facilitate backlog/refinement with prioritized FL/WD/BH themes and copyable agenda blocks, run a weekly TOC where-to-focus session from the constraint pack, run a tribe recovery check-in from the same numbers the dashboard already shows, or run a PI-prep integrity audit with ceremony fixes — then manually create improvement actions if you choose.

How it works: Enable AI assist for the workspace (same gate as before — no silent bypass). Agent cards are grouped into Issue & backlog quality, Initiative metrics & charts, and Workshop & ceremony so you can pick the right specialist faster. Select an agent card and run it for selected issues (or the initiative for Label Hygiene, Dependency / Flow Risk, Optimization Proposals, Root Cause Synthesis, Constraint & Bottleneck, Predictor, Flow Recovery Facilitator, and Planning System Integrity). On Select issues, use Filter to search or narrow by type, tribe, team, status, and Problem type (broken rule ids that appear on issues in the list), and Group by to cluster the table (you can select a whole group at once). Columns include Problem rank, Flow quality index (same 0–100 score as issue detail), and Findings count for each Jira item. Rules-only mode always works when no language-model provider is configured. If a language-model provider is configured and you opt into AI narrative, prose may be polished and labeled AI-generated; citations stay grounded in dashboard fields and tool findings. Copy suggestions manually — Flow Analyzer never writes back to Jira, ClickUp, or Asana, never auto-changes issue types, never create/merge/delete tracker labels, never auto-persists improvement actions, never auto-closes findings, never raises, clears, or edits flags or dependency links, never invents SP/sprint dates for Planning System Integrity, never recalculates forecast dates for Predictor, and never regenerates recovery targets for the Facilitator.

How it works: Enable AI assist for the workspace (same gate as before — no silent bypass). Agent cards are grouped into Issue & backlog quality, Initiative metrics & charts, and Workshop & ceremony so you can pick the right specialist faster. Select an agent card and run it for selected issues (or the initiative for Dependency / Flow Risk, Resource Constraint, Optimization Proposals, Root Cause Synthesis, Predictor, Flow Recovery Facilitator, and Planning System Integrity). On Select issues, use Filter to search or narrow by type, tribe, team, status, and Problem type (broken rule ids that appear on issues in the list), and Group by to cluster the table (you can select a whole group at once). Columns include Problem rank, Flow quality index (same 0–100 score as issue detail), and Findings count for each Jira item. Rules-only mode always works when no language-model provider is configured. If a language-model provider is configured and you opt into AI narrative, prose may be polished and labeled AI-generated; citations stay grounded in dashboard fields and tool findings. Copy suggestions manually — Flow Analyzer never writes back to Jira, ClickUp, or Asana, never auto-changes issue types, never auto-persists improvement actions, never auto-closes findings, never raises, clears, or edits flags or dependency links, never invents SP/sprint dates for Planning System Integrity, never recalculates forecast dates for Predictor, and never regenerates recovery targets for the Facilitator.

How it works: Enable AI assist for the workspace (same gate as before — no silent bypass). Agent cards are grouped into Issue & backlog quality, Initiative metrics & charts, and Workshop & ceremony so you can pick the right specialist faster. Select an agent card and run it for selected issues (or the initiative for Dependency / Flow Risk, Optimization Proposals, Root Cause Synthesis, Constraint & Bottleneck, Predictor, Flow Recovery Facilitator, and Planning System Integrity). On Select issues, use Filter to search or narrow by type, tribe, team, status, and Problem type (broken rule ids that appear on issues in the list), and Group by to cluster the table (you can select a whole group at once). Columns include Problem rank, Flow quality index (same 0–100 score as issue detail), and Findings count for each Jira item. Rules-only mode always works when no language-model provider is configured. If a language-model provider is configured and you opt into AI narrative, prose may be polished and labeled AI-generated; citations stay grounded in dashboard fields and tool findings. Copy suggestions manually — Flow Analyzer never writes back to Jira, ClickUp, or Asana, never auto-changes issue types, never auto-persists improvement actions, never auto-closes findings, never raises, clears, or edits flags or dependency links, never invents SP/sprint dates for Planning System Integrity, never recalculates forecast dates for Predictor, and never regenerates recovery targets for the Facilitator.

Assist — AI Chat (floating conversation)

Who it is for: Scrum Masters, coaches, and RTEs who want a quick conversational explanation of findings or flow health without opening a specialist agent card.

Why it exists: Batch agents are excellent for Writing Quality rewrites or ceremony agendas; day-to-day questions (“why is DEMO-104 flagged?”, “what changed this week?”) fit a floating chat better.

What problem it solves: You stay on Findings, Discipline, or any authenticated screen, open the AI bubble, and ask in natural language. Slash commands (/findings, /cfd, /forecast, /brief, /repeat) and quick prompts seed useful context from the workspace snapshot. Repeat on an assistant reply (or /repeat) re-asks the previous question against the current workspace. Copy puts the message on the clipboard. Optional MCP tools can pull findings, dashboard, or flow story evidence. Threads are saved so you can resume later.

Where in the UI: Floating AI button (bottom-right) on Flow Analyzer when you have an active workspace. Organization LLM settings remain under Organization settings → AI Agents. Chat reuses the same enable AI assist consent as Agents.

How it works: Organization AI Agents must be on and a provider configured. Enable AI assist for the workspace, then send a message. Answers stream as markdown, are labeled AI-generated, and never write back to trackers. Turn MCP off in the chat toolbar when you want conversation-only replies without tool lookups. Use the toolbar skill selector for Flow coach (general flow health) or Backlog readiness (WD-01 / missing-AC coaching — recommends Agents or Findings, never auto-runs agents).

Chat skills: Use the toolbar skill selector to choose coaching focus:

• Flow coach (default) — general findings, cycle time, CFD, and flow-health explanations.
• Backlog readiness — WD-01 missing-AC portfolio signals (% without AC, top projects), refinement workflow (Backlog Readiness agent → WD-01 issue filter → Requirements Template → Optimization Proposals / Root Cause epidemic theme), and advisory TQ-06 / TQ-07 AC text scans. Chat recommends AI Agents or Findings but never auto-runs agents or writes AC back to Jira/ClickUp. With an empty snapshot, chat refuses invented issue rows and points you to seed or live setup.

Zručnosti chatu (SK): V paneli nástrojov vyberte zameranie koučingu:

• Kouč toku (predvolené) — všeobecné vysvetlenia nálezov, cycle time, CFD a zdravia toku.
• Pripravenosť backlogu — portfóliový signál WD-01 (chýbajúce AC, top projekty), workflow refinmentu (agent Backlog Readiness → filter WD-01 → Requirements Template → Optimization Proposals / Root Cause epidémia) a poradné skeny TQ-06 / TQ-07. Chat odporučí AI agentov alebo Nálezy, nikdy nespúšťa agentov automaticky ani nezapisuje AC do Jira/ClickUp. Pri prázdnej snímke nevymýšľa riadky issues — odporučí seed alebo live dáta.

TQ-06 / TQ-07 vs WD-01 vs Backlog Readiness agent

EN: Use WD-01 for workflow/DoR gates (“field empty on required types”). Use TQ-06 when you care about text-quality portfolio views that align with Writing Quality. Use TQ-07 when AC exists but is prose-only. The Backlog Readiness agent does not replace Findings — it summarizes and links to them.

SK: WD-01 slúži na workflow/DoR brány (prázdne pole na povinných typoch). TQ-06 pri portfóliovom pohľade na kvalitu textu AC. TQ-07 keď AC existuje, no nie je štruktúrované. Agent Backlog Readiness nezastupuje Nálezy — sumarizuje ich a odkazuje na ne; počty TQ preferuje z uložených nálezov.

Where in the UI: Sidebar Assist → AI Agents. Initiative PM dashboard Finish oldest first — Coach pull policy. Discipline and Ceremony packs → Tribe sync may deep-link the same coach. Initiative PM dashboard — Facilitate this week on the 4-week flow recovery plan panel. Ceremony packs → 4-week flow recovery deep-links the Facilitator. Initiative PM dashboard and portfolio Dashboard — Explain forecast beside the forecast strip and Audit planning integrity near the scope KPIs. Ceremony packs → PI planning prep can deep-link Planning System Integrity. Issue Detail Analyze with agent… preselects Type & Work Definition when the issue has TM/WD findings.

Where in the UI: Sidebar Assist → AI Agents. Initiative PM dashboard — Facilitate this week on the 4-week flow recovery plan panel. Ceremony packs → 4-week flow recovery deep-links the Facilitator. Initiative PM dashboard and portfolio Dashboard — Explain forecast beside the forecast strip and Audit planning integrity near the scope KPIs. Ceremony packs → PI planning prep can deep-link Planning System Integrity. Ceremony packs → This week's constraint — Where to focus (TOC) opens Constraint & Bottleneck for the same initiative (Generate executive summary remains the pack narrator). Issue Detail Analyze with agent… preselects Type & Work Definition when the issue has TM/WD findings.

Example (Type & Work Definition): DEMO-210 has TM-05 → the readout explains why a meeting should not be a Story, suggests Task wording, and links the TM playbook facilitation cue. DEMO-55 with no TM/WD hits shows a healthy-hygiene note without invented defects.

Example (Label Hygiene): The initiative snapshot has team-platform, Team-Platform, and stale PI_2025_Q4 on open DEMO-104. The report lists a distinct catalog with usage counts, a duplicate cluster with match reason case_variant + separator_variant, stale PI rows, and cross-links DV-08 / PL-09 when those findings cite the same keys. Copy the report or open Findings / Discipline — tracker labels are unchanged.

Example (Dependency / Flow Risk): Initiative SEED-PI-1 has VS-08 on SEED-104 → SEED-91. The readout cites VS-08 and those keys, offers Open in VSM, and Findings · VS-08. If there are no VS/FI findings, you see a clean-posture note and still get a VSM link.

Example (WIP & Pull Policy Coach): Finish oldest first shows SEED-104 and SEED-201 as weekly targets; Platform tribe is 8/5 (over). The coach headlines “finish SEED-104, SEED-201 first” and says Do not start new work, citing Platform over limit and FL-01. Tribe WIP numbers match the dashboard bars exactly. When AI assist is off or the language model is unset, rules-only copy still works; the Finish oldest first table itself never changes.

Example (Constraint & Bottleneck): Ceremony packs show Review as this week's constraint with CA-01. From AI Agents (or Where to focus (TOC) on the pack), the coach returns one headline constraint, evidence citing CA-01, and exploit / subordinate / elevate actions from the pack experiments — without inventing finding ids or changing WIP limits.

Example (Optimization Proposals): The same initiative has FL-01 on DEMO-104, WD-06 on DEMO-77, and BH-01 on DEMO-12. The workshop agenda lists three themed blocks (WIP/load, definition, backlog health) with those rule ids and keys. Copy a block or open Improvement actions to create an experiment manually. If only FL findings exist, WD and BH themes are omitted with an explicit scope note — no invented waste patterns.

WD-01 epidemic priority (Optimization Proposals): When WD-01: Missing acceptance criteria affects at least five scoped Story/Feature items (or at least 20% of AC-required types in scope), the agenda adds a section 0 epidemic block (definition-quality-epidemic) before numbered FL/WD/BH themes — DoR gate and batch refinement first, then the usual family blocks (still numbered 1, 2, 3…). Below those thresholds, or when WD-01 is absent, no epidemic section appears and the readout does not invent counts or issue keys.

SK (Optimization Proposals — epidémia WD-01): Pri aspoň piatich položkách bez AC (alebo ≥ 20 % scoped typov s povinnými AC) agenda začína blokom 0. Epidémia chýbajúcich kritérií akceptácie pred číslovanými témami FL/WD/BH; pod prahom alebo bez nálezu WD-01 sa epidémia nezobrazí.

Example (Backlog Readiness): Open Assist → AI Agents, select Backlog Readiness under Issue & backlog quality, and run with no issues selected (initiative scope). The readout shows how many Story/Feature items lack acceptance criteria, the % of scoped AC-required types, an epidemic flag when at least five items or 20% are affected, top project prefixes with sample keys (e.g. AKVI, BENE), a copyable refinement plan, and advisory TQ-06 / TQ-07 text-quality counts. Use Findings · WD-01 to open the WD family filter, or Issue picker · WD-01 to filter the hub table by WD-01: Missing acceptance criteria. Select a cluster → run Requirements Template for batch AC drafts. Pair with Optimization Proposals or Root Cause Synthesis when the epidemic theme appears. Advisory only — Flow Analyzer never writes AC back to Jira, ClickUp, or Asana.

SK (Backlog Readiness — batch AC): V Assist → AI agenti vyberte Pripravenosť backlogu v kategórii Kvalita issues a backlogu a spustite bez výberu položiek. Readout ukáže počet položiek bez AC, percento zo scoped typov s povinnými AC, príznak epidémie (≥ 5 alebo ≥ 20 %), top projekty s ukážkovými kľúčmi, kopírovateľný plán refinementu a poradné počty TQ-06 / TQ-07. Odkaz Nálezy · WD-01 otvorí filter rodiny WD; Výber položiek · WD-01 prefiltuje tabuľku podľa WD-01: Chýbajúce kritériá akceptácie. Vyberte cluster → Requirements Template na batch návrhy AC. Pri epidémii použite Optimization Proposals alebo Root Cause Synthesis. Len poradné — AC sa nezapisujú do trackera.

Example (Root Cause Synthesis): The initiative has FL-07 on twelve in-progress items plus correlated WD-01 / TM-09 on DEMO-77. The agent shows 3–5 retro themes with numbered why-chains, cited FL-07 (never invented rule ids), affected issue counts bounded by the sample keys, and one experiment per theme. Copy retro Markdown for the ceremony. From Ceremony packs → Retrospective, use Synthesize root causes to open the same agent without replacing the deterministic pack.

WD-01 epidemic priority (Root Cause Synthesis): At the same epidemic thresholds, a `wd01:epidemic` theme (missing_ac_epidemic) is injected before pattern-derived themes. It cites only WD-01, includes reinforcing/balancing causal loops, a DoR-gate experiment, and playbook likely-cause text. When WD+TM correlation also supports quality_crisis, both themes may appear with distinct themeId / patternKind. Below threshold or without WD-01, no epidemic theme is added.

SK (Root Cause Synthesis — epidémia WD-01): Pri rovnakých prahoch sa téma `wd01:epidemic` (missing_ac_epidemic) vloží pred vzormi z korelácie; v retro Markdown uvidíte WD-01: Chýbajúce kritériá akceptácie, experiment s DoR bránou a slučky R:/B: v slovenčine. Téma quality_crisis môže súčasne zostať, ak korelácia WD+TM stačí.

A3 Thinking Document (/flow-analyzer/a3)

• Who it is for: Scrum Masters, Agile coaches, tribe leads, and external consultants who need a complete lean A3 worksheet for a retro, PI inspection, or leadership review — not only retro themes from Root Cause Synthesis.
• Why it exists: Root Cause Synthesis clusters 3–5 themes with why-chains, but PI and leadership forums expect the full seven-section A3 layout (background → current → target → root cause → countermeasures → plan → follow-up). The A3 document assembles that layout from Brief, findings, Root Cause Synthesis, and constraint-focus experiments in one persisted page.
• Where to find it: Sidebar Analysis outputs → A3 document (/flow-analyzer/a3). Also: Ceremony packs → Retrospective → Open A3 document, AI Agents → Root Cause Synthesis → Open full A3, and Brief → This week's one thing → Open A3 document.
• How to use it: Select the initiative, review the seven sections (derived analysis renders as formatted rich text — bold scores, bullet findings — not raw markdown), then Edit sections to workshop narrative in a TipTap editor (bold, italic, lists, headings) per section. Copy A3 Markdown still exports a coherent markdown document for Confluence or retro notes (complex HTML formatting may simplify on export). Refresh from analysis merges new derived content after a re-run; coach-authored rich-text overrides are preserved unless you opt in to overwrite per section. When analysis changes after your last refresh, a drift banner appears until you refresh or dismiss. Advisory only — Flow Analyzer never writes back to Jira, ClickUp, or Asana.
• Distinct from: Root Cause Synthesis (retro themes only), Case Study Writer (narrative genre), and Root Cause Map (causal loop canvas).

Root cause map (`/flow-analyzer/root-cause-map`): When you have at least two correlated findings, open Root cause causal loop map from the sidebar under AI Agents, Open causal loop map from the dashboard Root cause hypotheses tab, or View causal loop map after a Root Cause Synthesis run. The page renders an interactive diagram: findings, shared issues, correlation hypotheses, flow patterns, synthesis themes, and optional reinforcing/balancing loop variables.

• Diagnostic mode (default): evidence-linked graph with findings, issues, and loop variables — same trust model as before (#67).
• System dynamics (CLD) mode: facilitation canvas with frameless variables, region story cards, named loop badges (e.g. R1 · WIP spiral), +/− polarity on links, and optional ∥ delay marks when snapshot-backed dwell or blocked time exists (tooltip cites the median source — never invented days). When correlated findings support a classic pattern, an advisory archetype pill (e.g. Limits to Growth, Shifting the Burden) may appear below the loop badge — hover for rationale and cited rules; labels are heuristics, not certified system-dynamics analysis.
• Loop archetypes (advisory): In CLD mode, medium-confidence archetype pills appear under loop badges when Findings back the heuristic (WIP overflow + FL rules → Limits to Growth, quality-crisis balancing loops with WD/TM → Shifting the Burden, and similar). In Diagnostic mode, select a loop in the insight panel to read the archetype there — no canvas pill. Weak or unbacked signals show the loop name only.
• Edit map: add authored variables and causal links, drag layout, and save — persisted per workspace and initiative in Postgres (not browser localStorage).
• Drift: when analysis reruns, a banner appears until you Refresh from findings; authored workshop overlays are preserved.
• Toggle loop types and root-cause highlights in Diagnostic mode; click a node for cited rules and a link to related findings. Ranked root-cause candidates are advisory — the same trust model as synthesis text.

Example (Resource Constraint): Resource Sankey shows Adam K. at precious 0.88 (high) and Lucia P. at 0.76 (medium), with RA-01 and RA-10 in Findings. The briefing lists those scores and bands exactly, cites only those RA ids, and recommends protection actions without inventing people or recalculating RA-10.

Example (Predictor): Dashboard shows P50 14 Mar 2026 and P85 28 Mar 2026 with throughput 4.2 stories/week and VL-01 / BC-03 findings. Predictor copies those labels verbatim, explains spread and scope-added risk, and links Findings · VL/BC/SG. When no stories remain, it explains why no finish date applies instead of inventing one.

Example (Planning System Integrity): The same initiative shows scopeAdded +12 SP, 42.5% SP done, and BC-01 / SG-01 findings. The agent returns integrityAssessment: broken, cites those metrics and rule ids only, recommends refinement gate / commitment cap / mid-sprint scope policy, and deep-links Findings · BC and Findings · SG. Without AI assist consent the run fails closed; without an LLM provider you still get the rules-only assessment.

Example (Flow Recovery Facilitator): The dashboard 4-week plan shows WIP today 13 → target 4, Done target 6, and triage key SEED-104. Week 2 Facilitator cites those exact numbers, focuses on “Hold WIP limit — unblock category B,” lists control signals from the playbook, and escalate-if for zero Done by week 2 — without inventing keys or rewriting process-control severity.

Dashboard also shows a Flow health scorecard, Delivery diagnostic (system-level bottlenecks), Flow focus items (see below), and Top interventions queue so you know where to start.

Dashboard — Flow health and value over time

Open Dashboard (/flow-analyzer/dashboard) after Start here.

• Who it is for: Scrum Masters, tribe leads, product owners, and delivery managers who need to see whether the system is healthy — and whether outcomes (business value) are moving, not only how many stories finish.
• Why it exists: Story throughput answers “how many items per week?” Flow health Value delivery and the BV / week card answer “is value actually reaching Done?” Completing many small children while high-BV epics stay open is output without outcome.
• What problem it solves: A six-axis radar used to measure finding density for pace, stability, load, definition quality, dependencies, and discipline. It did not call out value-specific findings, and the KPI strip showed % BV delivered (a progress stock) without a rate. Teams could look “busy” on stories/week while BV stayed back-loaded or stuck.
• How it works:
• The Flow health radar has seven dimensions. Each starts at 100 and falls when matching findings fire (same severity penalties as the other axes). Definition quality (SK: Kvalita definície) counts WD/TM/ES families — when this axis is weak, open Assist → AI Agents → Backlog Readiness for a portfolio WD-01 readout (see Backlog readiness workflow). Value delivery (SK: Dodávka hodnoty) is penalized by BV-specific rules only: BC-08 (BV back-loaded), BC-09 (zero BV in the PI), BC-10 (BV vs count/SP inconsistency), PR-07, CO-05, IA-05, and EP-05 — not whole PR/CO/IA/EP/BC families. Pace burn-chart rules stay on Predictability; they are not double-counted. The axis is meaningful when a business-value field is mapped in configuration; if that field is missing, those rules skip and the score stays 100.
• % BV delivered remains the stock of epic business value that has reached Done (children completing does not count until the epic is Done).
• BV / week is the flow metric: business value of epics that reached Done in the last 8 weeks, divided by 8 — the same lookback as story throughput.
• Where in the UI: Dashboard KPI strip (story Throughput card, then BV / week, then % BV delivered) and the Flow health / Zdravie toku radar below the KPI cards. Expand a dimension for the calculation and View related findings.
• Example: A team finishes 4 stories/week, so throughput looks healthy. Two child stories under a high-BV epic are Done, but the epic is still Implementing — BV / week stays 0 and Value delivery may show BC-08 or IA-05. When that epic reaches Done (BV 40) in the 8-week window, BV / week becomes 5.0 (40 ÷ 8) and % BV delivered steps up. That is outcome, not item count.

Dashboard — Refinement health KPIs

Open Dashboard (/flow-analyzer/dashboard) and look for the Refinement health strip under the main KPI cards.

• Who it is for: Scrum Masters, product owners, and delivery managers who need three stable checklist numbers for refinement quality — not only scattered rule findings.
• Why it exists: Flow Analyzer already fires WD/CH/FL signals for rework, churn, and missing AC, but teams still had to infer the three consultant checklist KPIs by hand.
• What problem it solves: You can see (1) requirement rework rate, (2) decision latency (median and P85), and (3) sprint entry without acceptance criteria, each with sample size, analysis window, and evidence.
• How it works:
• Requirement rework rate = 100 × (items with a rework signal ÷ eligible delivery items). Default signals are per-issue status regression (FL-03), critical field churn (CH-10), and late or removed acceptance criteria (CH-06 / CH-19). Warning-band CH-10 does not inflate the rate; CH-05 / CH-07 stay off unless enabled in configuration. If nothing is eligible, the KPI shows an empty state — not 0%. Evidence is a sortable table of capped issue keys, signal summaries, and contributing rule ids with deep links to Findings. This KPI is not the Recommendations “quality crisis” rework wording.
• Decision latency uses configured request and decision markers (statuses, optional fields, or a comment-event proxy). Comment bodies are never read. Items with a request but no decision in the window count as open decisions and are not averaged as infinite. Missing marker config hides the KPI and links to Configuration → Workflow. Closed pairs show median and P85 in days; open rows appear separately in the sortable evidence table with request/decision dates and marker labels.
• Sprint entry without AC evaluates acceptance criteria at the first sprint-add timestamp via changelog replay (not only the current snapshot). Optional sprint-start grace hours default to 0 (related to CH-06 / CH-08 timing ideas but does not retune those rules). Drill-down shows a sortable per-sprint table and a capped evidence table (issue, sprint, add time, AC-at-add summary, optional WD-01 / CH-06 cross-links).
• Where in the UI: Dashboard → Refinement health strip; expand explanations on each card; open Findings or Configuration from the hints when needed.
• Example: Twenty eligible stories, four with FL-03 or CH-10 → rework rate 20%. Twelve closed decisions with median 2.0d and P85 5.5d, plus three open decisions listed separately. Eight sprint-adds, three without AC at add time → 37.5%, with Sprint 42 showing 2 of 5.

Sprint entry without acceptance criteria

• Who it is for: Scrum Masters and product owners who need a stable measure of Definition-of-Ready at sprint commitment — not only “missing AC now” (WD-01) or “empty at first active status” (CH-06).
• Configure: Map the acceptance criteria field under Configuration → Workflow. Types that require AC come from ac_required_types (default Story, Feature). Optional sprint-start grace hours (default 0) exclude very early sprint adds from the sample.
• Read the tile: Percentage = 100 × (issues with empty or below-minimum AC at first sprint-add ÷ issues added to sprint in the window). When nothing is eligible, the tile shows —, not 0%. When the AC field is not configured, the KPI is hidden with a link to Configuration.
• Evidence table: Sortable list of issue keys with sprint name, sprint-add timestamp, AC-at-add summary, and optional WD-01 / CH-06 finding links. Items still count when AC was filled after sprint add but before work started.

Decision latency (request → decision)

• Who it is for: Product owners and Scrum Masters who need a stable measure of how long items wait for a decision after a configured “request” signal.
• Configure: Configuration → Workflow → Decision latency markers — pick request statuses/fields and decision statuses/fields (or enable comment-event proxy). Both sides must be set or the KPI stays hidden with a link to Configuration.
• Read the tile: Median and P85 days over closed pairs only; open decisions (request without a later decision in the window) are counted separately and never averaged as infinite. When no closed pairs exist, the tile shows —, not 0d.
• Evidence table: Sortable list of issue keys with request date, decision date (or open), latency, and marker labels used. Comment bodies are never read.

How to read headline vs outcome metrics

> Metric credibility (2026-08): Phases F−1 through F3 shipped under epic #83. Brief, Dashboard, HTML/CSV export, and scheduled reports now share the same RAG, % SP done, % BV delivered, and rule-signal index for a given snapshot. Composite RAG weighs pace, BV delivery, and PI outcomes — Brief Where it burns is no longer SP-only GREEN. Flow health remains a rule-signal density scorecard (by design); compare it with outcome KPIs on the same screen. Full audit: audit-zladenie-metrik-a-vypoctov.md.

> Dôveryhodnosť metrik (2026-08, SK): Fázy F−1 až F3 sú dodané v rámci epic #83. Brief, Dashboard, HTML/CSV export a naplánované reporty zdieľajú rovnaké RAG, % hotových SP, % dodanej BV a index signálov pravidiel pre danú snímku. Kompozitné RAG zohľadňuje tempo, dodávku BV a PI — karta Kde horí už nie je len GREEN podľa SP. Flow health zostáva index signálov pravidiel (zámer); porovnajte ho s outcome KPI na tej istej obrazovke. Audit: audit-zladenie-metrik-a-vypoctov.md.

Who it is for: anyone using Start here or Dashboard for weekly syncs and sponsor readouts.

How to read the surfaces together:

Your Focus Wizard goals (G1–G8): in Guided mode they reorder Brief cards, filter findings, and boost goal-aligned recommendations — they do not change the Flow health overall number or composite RAG. Workspace default focus (F3) applies shared goal affinity on exports when configured.

Dashboard — Flow focus items

Open Dashboard (/flow-analyzer/dashboard) for a portfolio-wide read after Start here (the Brief).

Global portfolio scope (header filters)

When your workspace has more than one tribe or squad in the imported portfolio, use the portfolio scope controls in the app header (second row under the workspace name):

• Period: This quarter (default) or All time — narrows discipline-style metrics and several charts to the current quarter window vs full snapshot history.
• Sprint: All sprints (default), Current sprint, Previous sprint, or Last 2 sprints — narrows issue-level views to work assigned in those sprint windows when sprint history exists in the snapshot (Sprint field changelog).
• Tribe / squad: Whole portfolio (default), a single tribe, or one squad — filters findings, dashboards, maps, exports, and ceremony packs to issues in that slice.

How it works: scope is stored in the URL (period, sprint, tribe, team) so sidebar links keep the same filter as you move between Brief, Dashboard, Discipline, Findings, Truth gap, CFD, VSM, Initiative PM, Priority matrix, Improvement actions, Ceremony packs, Compare, Export, AI Agents, Resources, Landscape, Control chart, and related views. This is read scope (display filter on the persisted snapshot). It is separate from Run analysis ingest scope (FR-02), which controls what Jira issues are pulled on the next analysis job.

When sprint history is not configured in the workspace snapshot, the Sprint control stays disabled with a short hint — tribe/squad and period filters still work.

Period vs tribe/squad: This quarter (default) narrows discipline-style metrics, CFD window, agent run context, and — when you also pick a tribe or squad — further limits issue-level panels to work items with snapshot activity in the current calendar quarter. All time keeps full history on those metric views. Tribe/squad alone filters findings, Sankey, discipline investigation tabs, improvement actions (by linked findings), run trends, snapshot compare, and export samples to issues in that slice.

Improvement actions: when a tribe or squad filter is active, the kanban list is filtered on the server. Actions with no linked finding refs still appear so you can track squad-level experiments that are not tied to a single rule.

Compare: snapshot compare respects the same tribe/squad scope on finding deltas and issue counts.

Resources: Sankey and resource investigation honor tribe/squad scope on allocation and investigation APIs.

Control chart: the findings panel beside the chart refetches when portfolio scope changes.

Tips: leave tribe and team at all for portfolio-wide reviews; pick a tribe before a tribe sync or PI prep pack; use squad when you coach one delivery team. Org structure highlights the selected tribe in the roster chart without changing roster filters.

When a tribe or squad filter is active, the product separates three lenses so the numbers do not contradict each other:

• Rule-signal / flow quality (Brief risk card primary when filtered — flow health /100; Findings; Dashboard flow health) — hygiene and hierarchy-problem density for the selected slice. This is the headline on RIZIKO under a tribe/team filter, not a lone initiative-wide GREEN badge.
• Scoped delivery (Brief risk evidence line + HTML/Markdown executive summary) — pace, forecast, and blockers recomputed on that slice only, labeled as slice delivery (for example “BENE delivery pace: GREEN (96% SP done in slice)”).
• Initiative delivery (secondary Brief line + export secondary line; Dashboard RAG footnote) — whole-initiative pace and RAG unchanged; sponsors still see whether the full initiative is on track.

Many hierarchy “problem” rows in a squad view can coexist with a green scoped or initiative RAG — they measure process noise in the slice, not portfolio completion pace. HTML and Markdown Executive summary use the same dual-lens Brief model (process + scoped pace + initiative), so an export cannot show only an unlabeled initiative GREEN while Findings show many hierarchy problems.

If the filter matches no issues (or the slice has no delivery sample), Brief and export stay empty-scope safe: forecast stays unavailable, and the primary risk copy says there is no work in that scope — it does not present parent-initiative GREEN as “all clear.” Reset Tribe and Team to all for the classic initiative-wide risk card.

• Who it is for: Scrum Masters, tribe leads, and coaches who need one ranked list of which issues to unblock first—not only which rule families fired.
• Where it sits: below Delivery diagnostic and above Findings insights (top findings by rule and interventions).
• What it shows: up to fifteen work items sorted by a focus score that combines cycle time (CT), lead time (LT), dwell in the dominant workflow stage, rule signals (for example OL-01, CT-06/07, IA-05, blocked dependencies), downstream impact, and whether the issue is new since the last analysis.
• Columns: item (with parent feature/epic), tribe, CT, LT, dominant stage with dwell days, signal tags, and score. Click an issue key to open the issue detail panel.
• Context line: above the table, a short summary names the longest portfolio stage, this week’s constraint (when available), and the analysis scope and date.
• HTML report: the same ranked table appears in the Flow focus items section of the initiative HTML report (after executive summary and Reporting gap), so stakeholders see the same priorities without opening the app.
• How to use it: start with the top three rows in your next stand-up or refinement; cross-check Findings and Value stream map when you need rule evidence or dependency context. This view complements findings-by-rule—it does not replace the control chart or full findings list.

Dashboard — Finish oldest first

Open Dashboard (/flow-analyzer/dashboard) and scroll to Finish oldest first (below Flow focus items).

• Who it is for: Scrum Masters running a stop-starting, start-finishing week.
• Why it exists: Age in a workflow stage is the ranking; story-point size is the glanceable extra so you do not pull a 40-point item into a “finish three this week” goal by accident.
• What problem it solves: A raw 3 in the SP column is easy to miss next to dwell days. Colored planning-poker cards (the same Fibonacci values teams hold up: 0, ½, 1, 2, 3, 5, 8, 13, 20/21, 40, 100) make size pop without opening the issue.
• How it works: each estimate is a compact colored card in the SP column. Missing estimates stay as an em dash — no placeholder card. Colors reuse the product status/BV palette (green, teal, blue, purple, amber, orange, red) rather than a second invented rainbow.
• Where in the UI: Dashboard → Finish oldest first table → SP column. Pick a stage, then finish the top weekly-target rows before starting new work.

Did it work? — outcome verification

Improvement actions now close the loop by themselves. When you create an action, FlowAnalyzer records

the analysis run you are improving from (the baseline). When you move the action to Done, it

waits for the next completed analysis run and compares the rule hit counts behind the action's linked

findings between the two runs.

The verdict appears as a badge on the Done column and in the action's detail panel:

Verdicts are derived from the same rule engine that produced the findings, so an action's outcome is

evidence, not an opinion. Actions with no linked findings show no verdict — there is nothing to measure.

Navigation: Start here first

The sidebar is ranked in two tiers.

• Start here (the Brief) and Dashboard sit at the top, visually separated. Start here answers five

questions in about thirty seconds: how healthy you are, this week's one thing, what to do, what changed,

and where it burns.

• Global portfolio filters in the header (Period, Sprint, Tribe, Team) scope analysis views that honor

the URL parameters. Brief, Dashboard, Discipline, Findings, and Truth gap narrow findings

(and related metrics where wired) to the selected tribe or team. Sidebar links and the Analytics hub keep

those filters in the URL as you move between screens.

• Analysis outputs (always visible) holds reporting gap, discipline, priority matrix, improvement

actions, ceremony packs, and the results report.

• Assist (always visible, below Analysis outputs) holds AI Agents.
• All analysis holds everything else — findings, control chart, value stream map, cumulative flow,

plus the portfolio views (Portfolio, Org structure, compare imports) and map views. It stays open

once you have used it, so returning users keep their depth. Open All analysis → Portfolio → Org structure

to edit tribes, squads, people, and FTE for the active workspace.

Breadcrumbs at the top of each screen show the path you took and let you step back up. Collapsing the

sidebar keeps group boundaries and shows each item's name on hover.

Initiative PM — history playback

Open Initiative PM (/flow-analyzer/initiative/{initiativeId}) to review hierarchy, timeline bars, and bottom charts for one initiative.

• Who it is for: initiative owners and PMs who want to see how scope, status markers, and charts evolved from changelog history—not only the current snapshot.
• Play history: use Play history above the hierarchy tree. The shared playhead scrubs across the tree, SVG timeline (orange dashed line), and bottom charts.
• Controls: play/pause, speed (default 1 calendar day = 1 real second), step back/forward per changelog keyframe, date scrubber, and Jump to date.
• Charts: while playback is on, CFD / BV / scope replay from changelog buckets; static charts return when you stop playback. BV and scope show an orange playhead cursor.
• Note: inner bar fill (% time spent) does not replay worklogs in v1—the legend explains that values stay at the snapshot baseline.

Initiative PM — average time in workflow stage

Below the status workflow strip, Average time in workflow stage shows how long issues in this initiative typically stay in each Jira status column.

• Who it is for: RTEs, tribe leads, and coaches asking where work waits longest before you change WIP limits or swarm a stage.
• What it shows: a bar chart of average dwell hours per workflow status, ordered by your workspace workflow stage order when configured. Statuses outside the configured order appear in gray after the main flow.
• Data source: changelog-derived dwell from the workspace snapshot (same signal as rule FL-06). The chart appears only when status history exists; otherwise you see a short empty-state message.
• How to use it: compare the tallest bars across columns—often Review or Test—to the status strip WIP counts above. A tall bar plus high WIP usually marks the system constraint for that initiative.

Value stream map — measured cycle time

On Value stream map (/flow-analyzer/vsm), node badges show cycle time and age from your snapshot when changelog metrics exist for that issue.

• Who it is for: initiative owners tracing blockers who also need how long items have been open or in flow—not story-point estimates.
• When numbers are real: after live ingest or import with status history; values come from the same persisted timing used on Initiative PM.
• Fallback: if an issue has no dwell or cycle metrics, the map uses a lightweight estimate from story points and status so the layout still renders.

Value stream map — value stream layout (tribe × stage)

On Value stream map (/flow-analyzer/vsm), use the toolbar toggle Value stream (next to Hierarchy) to switch from the dependency graph to a tribe × workflow stage grid.

• Who it is for: RTEs and tribe leads who want a classic lean-style view of where work piles up by team and column—not only hierarchy blockers.
• Each cell shows: WIP count (corner), average dwell days in that status, a queue vs active split bar (non-active vs active_statuses from workflow config), a small throughput sparkline (items leaving the stage per week), and an amber bottleneck tint when recent inflow/outflow exceeds config.cfd.bottleneck_ratio.
• Drill-down: click a cell to open a drawer listing issue keys in that tribe and stage.
• Data source: persisted workspace snapshot (same changelog replay as FL-06 / CFD rules). The toggle stays disabled until snapshot dwell metrics exist.

Initiative PM — stage timing ladder

Below Average time in workflow stage, the Stage timing ladder shows wait vs active dwell along your configured workflow stages, plus P50 lead/cycle summaries and up to three sample story segment rows.

• Who it is for: coaches explaining where time is queue vs touch before changing WIP policies.
• Data source: aggregated timeInStatusSeconds from the workspace snapshot, classified using active_statuses.

Initiative PM — takt vs delivery rate

When the initiative has PI commitment data (piHistory with committed story count), the Takt vs delivery rate panel compares committed demand (stories per week) with trailing throughput from the snapshot.

• Who it is for: RTEs checking whether delivery pace matches PI commitment without inventing demand numbers.
• Roster capacity band: when Org structure squads define Sprint capacity (SP), the same panel adds a flat roster sprint capacity line (weekly story points) alongside completed SP from the snapshot — even when PI commitment is absent. Purple = weekly done SP; dashed green = summed squad capacity (default 2-week sprint assumption).
• Empty state: when neither PI commitment nor squad SP capacity is configured, the panel explains what is missing; no fake takt line is shown.

CFD and control chart — live snapshot replay

Cumulative flow (/flow-analyzer/cfd) and Control chart (/flow-analyzer/chart) prefer changelog replay from your workspace snapshot when one exists, falling back to seed interpolation only when snapshot metrics are unavailable.

• Who it is for: flow coaches who need charts aligned with rule-engine CFD/CA signals, not demo curves alone.
• How it works: the initiative dashboard API enriches CFD series from persisted snapshot WIP-by-stage replay; the control chart page merges completed-issue cycle times from snapshot(s) across initiatives in scope.
• Process control metric (6 weeks): below the CFD chart, the Process control stat card checks the last six weeks for at least one week where Done rose week-over-week and Implementing WIP stayed below 8 (the same WIP-limit threshold used in batch-size coaching). Pass means process changes on this board can work; Miss means capacity or priorities outside the board are the more likely constraint. Use it after a WIP-limit or finish-first experiment to falsify whether the bottleneck is on-board workflow vs off-board demand.

On the Initiative dashboard, the same check appears as a panel below Finish oldest first, with a link to the CFD screen.

4-week flow recovery plan appears on the dashboard (after process control), in ceremony export (flow_recovery_4w), and in Výsledná správa HTML — baseline from CFD, numeric targets, implementing triage with issue keys, weekly steps, and control signals. All numbers come from the workspace snapshot (no AI).

RTE decision checklist (VSM timing)

Who this is for: coaches and delivery leads reviewing the latest analysis for the active workspace.

On Findings (/flow-analyzer/findings), filter by severity, rule family, and search text. Use Operational defect funnel to focus on the Operational Issues (OI) family (including environment-related evidence when present). Expand Discipline investigation on the same page for gate bypass, requirement coverage, epic DoD, PI delivery, operational bucket, multi-project portfolio, and Lean waste tables without switching screens.

On Discipline (/flow-analyzer/discipline), the score overview shows one circle per domain. When the dashboard has DV findings loaded, each domain uses DV severity only when that domain has active rules in Findings; domains without DV coverage show the timeline proxy in the circle with an amber note so a misleading 100 does not appear. The structural signal under each card (for example undecomposed features) always comes from the timeline proxy. The scorecard tabs (Assignment, Mandatory Fields, Planning, Continuous Update, Decomposition) use the reconstructed initiative tree from the workspace snapshot. Story and Bug issues linked directly under an Epic (not only Epic → Task → Story) are now included in that tree. When some scoped issues still fall outside the reconstructed shape (for example Sub-tasks), a Partial hierarchy coverage banner appears on the score overview and Investigation tab — open Findings for full issue-level coverage. Assignment lists stories in an active workflow status with no assignee (using workspace active statuses when configured); when assignees are missing from the feed, empty timelines are used as a stand-in. These cards are timeline proxies — a domain score of 100 means no gaps under that narrow definition, not that every Jira issue is assigned or that mandatory fields match DV-05/DV-06. Prefer Findings (DV family) and Investigation when coaching ownership and field completeness. See also How to read conflicting signals. Open the Investigation tab for gate bypass, coverage, epic DoD, PI delivery, Operational buckets, Multi-project, and Lean waste at full width. The Operational buckets tab lists catch-all tracker issues (for example Prevádzka or Operativa umbrellas) with open child counts, recent child injection, and monthly growth slope. The Multi-project tab surfaces cross-project gate bypass, blocker aging and blocker chain integrity, parent–child coherence, DoD evidence gaps, PI label stack, description-versus-decomposition gaps, clone continuations, clone PI rollover, and remote link churn when the snapshot spans multiple delivery projects under shared parent initiatives. The Lean waste tab helps coaches review behavioural waste patterns by waste type (related catalogue rules and sample keys) and optionally filter samples to parent initiatives or delivery-level work. Issue detail overlays include a Links section for clone, covered-by, and blocking links with status badges when the snapshot has issue links.

Excessive commenting (DV-30 / DV-31)

Who this is for: coaches and team leads who see people spending a lot of time writing Jira comments that do not move the work forward (goldplating or “cover yourself” notes).

What problem it solves: Some teams under-document (caught by DV-18 — no comments on long-running work). The opposite waste is also common: many comments on a ticket with little status or ownership progress. Flow Analyzer measures comment event counts and timestamps only — it never reads comment text.

How it helps:

• DV-30 — Excessive Comment Activity on Issue flags a delivery-level story/bug/task when comment volume is high relative to age and to delivery field changes (status, assignee, estimates, sprint, resolution). Issues with an active impediment flag use a higher threshold so legitimate blocker threads are less likely to fire.
• DV-31 — Excessive Comment Volume by Author flags a person who either owns a large share of all comments in the snapshot or leaves many comments across many issues.

Where to find it: open Findings or the Rules catalogue, filter by the Discipline family, and look for DV-30 / DV-31. Sample issue keys appear on findings so you can open the tickets in Jira and coach toward shorter decision notes or moving status instead of comment sprawl. On Lean waste (Extra processes), the same issue keys may appear as samples when those rules fire.

Continuous update cadence (Discipline timeline proxy)

Who this is for: Scrum Masters and coaches who want teams to update Jira throughout active work — not only in a Friday batch or only at the start/end of a ticket.

What problem it solves: A story can have some comments or field changes and still be a poor living document if updates arrive in long silent gaps, in a burst on many tickets at once, or only when the item is about to close.

How it helps: On Discipline, the Continuous Update domain score and tab now measure cadence, not only whether any status, field, or comment marker exists:

• Per story: longest gap between engagement markers, concentration at the start or end of active work, and irregular intervals between updates.
• Per team: batch patterns when many active issues are updated in the same short time window.

Rows in the Continuous Update tab explain the pattern (for example end-loaded updates or a long gap). When DV findings are available for this domain, the card may also show a findings-based score — use both when coaching.

Where to find it: /flow-analyzer/discipline → Continuous Update tab and the Priebežná aktualizácia domain card in the score overview. When DV findings are loaded, DV-32 (weak cadence per issue) and DV-33 (team batch update pattern) appear under the Discipline family in Findings.

Configuration: open Configuration → Discipline to tune continuous-update cadence thresholds (expected cadence days, gap warn and critical days, batch window and minimum issues, list score threshold, minimum active days, and pattern-detection knobs).

Jira export import workspaces

Some organizations use `jira_export` workspaces when live Jira API access is unavailable or when you want a one-time portfolio upload.

1. In Organization settings, open a workspace and set Type to `jira_export`, then Save workspace.
2. On the workspaces table, use Import data on that row (or Import Jira export… from Workspace details).
3. Choose the export format that matches the files:

• Jira printable export — printable HTML per issue, native history.txt (Name made changes), optional navigator CSV and RSS.
• Per-issue folder export — folders such as epics/KEY/, features/KEY/, initiatives/KEY/ with KEY.html, KEY_history.txt (JIRA HISTORY EXPORT table), and KEY_changelog.json.

1. Choose ZIP or Folder:

• ZIP (recommended for large exports): a single archive of your export tree. The server stores the ZIP and extracts it during the background import job — fastest upload path.
• Folder: select the extracted folder; the browser zips files first, then uploads one archive (slower for large trees).

1. After you start the import, a progress bar in the import panel and in the corner notification tracks upload and each processing step (queued, parsing files, running rules). When the job finishes, the workspace snapshot refreshes and rules run. Results use initiative scope `import-ws-{workspaceId}` for the whole portfolio.

Import and ingest scale limits

Who: Organization admins and operators configuring SaaS workspaces.

Why: Large Jira exports and live ingests run as background jobs. Caps keep uploads predictable and protect shared infrastructure.

What you see: If an export contains more issues than your deployment allows, the import job fails with a clear error in the import panel and job status — split the export or ask your operator to raise the cap.

Default limits (2026-08, NFR-02 M4 spike):

Operators tune caps with FLOW_ANALYZER_IMPORT_MAX_ISSUES (import) and FLOW_ANALYZER_TENANT_INGEST_MAX_ISSUES (live ingest). Flow Analyzer engineering has verified synthetic normalize up to 50 000 issues offline; supported SaaS tier remains 5000 issues per job until product and operations explicitly raise it. See `performance-nfr-scalability.md` for spike data.

On the first successful import of a SAFe-style printable export (for example POIT/ENRL issue keys or Dovera DoD custom fields), Flow Analyzer can automatically apply the SAFe portfolio Jira export preset when the workspace still has the factory default configuration. User-edited or previously saved presets are never overwritten. You can still apply or adjust the preset manually from Organization settings → workspace → SAFe portfolio Jira export preset.

What findings appear after import

Import workspaces run the same rule catalogue as live Jira and seed-demo workspaces. Signal builders on the saved snapshot feed cycle time, DoD checklists, acceptance criteria, worklogs, sprint scope, value-stream links, and chart series (control chart / CFD) into the analysis run.

In practice you should see a broad mix of families on a rich export (for example DoD DG, content history CH, discipline DV, pipeline PL, operational OI, and flow FL / SP), not only a handful of hygiene rows. Seed-demo workspaces share the same pipeline and produce a solid baseline of findings even without Jira.

Charts and side panels (control chart, CFD) use the same snapshot context, so engine findings stay aligned with what you see on the chart screens.

Re-importing creates a new snapshot row (merge mode) or clears prior data (replace mode). On the import workspace settings panel, use Import snapshot history to pick a past snapshot and save a bookmark label (for example Pre-coaching or Post-PI-2). Use Compare imports in the sidebar to prove what improved or regressed between two snapshots.

Field mapping after import

When the export includes printable HTML or issue RSS, Flow Analyzer lists discovered custom fields (label and Jira field id) after the import job completes.

1. Open Organization settings → workspace → Workspace details (for a `jira_export` workspace).
2. Scroll to Map custom fields to workspace config (shown when hints were found).
3. For each row, choose the matching discovered field:

• Parent link → workflow.parent_link_field (hierarchy / orphan rules)
• Acceptance criteria → workflow.acceptance_criteria_field
• Story points → sprint.changelog_story_points_field (metrics and SP changelog rules)
• Business value → estimation.business_value_field (WSJF Business Value and portfolio BV metrics when present in export)
• Time criticality → prioritization.time_criticality_field (WSJF Time Criticality)
• Risk reduction → prioritization.risk_reduction_field (WSJF Risk Reduction — shown when SAFe portfolio DoD is configured)
• Job size → prioritization.job_size_field (WSJF Job Size)
• WSJF score → prioritization.wsjf_score_field (stored computed WSJF Score field, if your Jira stores it)

1. Click Save to workspace config. The next import and analysis run use this mapping.

On Configuration → Prioritization, map Time Criticality and — when your workspace uses SAFe portfolio Definition of Done (Funnel / Reviewing / Analysing stages) — the additional WSJF fields (Risk Reduction, Job Size, WSJF Score). Business Value is mapped under Estimation. You can tune Time Criticality thresholds (required types/statuses, high-TC aging days, WIP inversion rank gap). When no prioritization fields are mapped, Time Criticality and WSJF checks stay inactive.

SAFe WSJF prioritization checks

Who this is for: Product Owners, RTEs, and coaches running SAFe portfolio prioritization on Jira export or live workspaces with epic DoD checklists (including items such as “WSJF finalised”).

What problem it solves: Teams often map only Time Criticality, or mark WSJF as done in DoD while numeric fields are empty or inconsistent. Flow Analyzer checks the full WSJF picture — field completeness, formula consistency, WIP and backlog order versus WSJF, Job Size versus story points, and DoD claims versus data.

Where to find it: Configuration → Prioritization (field mapping and help text when SAFe DoD is detected). After analysis, open Findings or Rules catalogue and filter the Planning Recommendations (PR) family.

When checks run: WSJF completeness and semantic rules activate when (1) workspace config includes SAFe-style DoD stages and (2) at least one WSJF field is mapped. Map all five components for the strongest signal: Business Value, Time Criticality, Risk Reduction, Job Size, and WSJF Score.

Time Criticality-only checks (missing TC, aging high-TC in backlog, WIP inversion by TC alone) still apply when Time Criticality is mapped; when full WSJF scoring is available, WIP and completeness findings prefer the WSJF layer to avoid duplicate noise.

If Parent Link appears in the hints but config still uses the default parent field, a warning reminds you to map before re-importing so hierarchy rules stay accurate.

You can also refine the same fields later on the Configuration screen when this workspace is active.

Jira project → organization unit mapping

After import, Flow Analyzer discovers Jira project keys from issue keys (for example ITST-22 → project ITST, FIRM-10108 → FIRM). Large portfolios often mix portfolio, tribe, and squad Jira projects (for example PORT initiatives, ITST tribe epics, FIRM feature boards).

1. Open Organization settings → workspace → Workspace details ( `jira_export` workspace).
2. Scroll to Jira project → organization units (below field mapping when project keys were discovered).
3. For each row set:

• Jira project — the key prefix (AIT, ITST, FIRM, PORT, …).
• Unit type — what this project represents in your operating model:
• Tribe — value stream / tribe epic container (used for Score by Team and cross-tribe rollup).
• Team — delivery squad or feature board (display label only unless assignee roster maps squads to tribes).
• Community — cross-tribe community or chapter.
• Project — generic delivery project.
• Portfolio — portfolio or program container (for example PORT).
• Program — program-level container.
• Other — anything else; label is stored but does not drive tribe rollup.
• Display label — readable name shown in dashboards (for example “IT Tribe”, “Firmy squad”).

1. Click Save organization mapping. Use Refresh from import after a new import to add newly discovered keys with suggested types (Dovera-style heuristics: PORT → Portfolio, *ST tribe boards → Tribe, squad keys such as FIRM / ENRL → Team).

Only rows with unit type Tribe contribute mapped labels to cross-tribe comparison and Score by Team tribe rollup. Rows marked Team, Project, or other types keep their labels for reference but analysis falls through to parent epic metadata, component ownership, or people roster when resolving tribe for an issue.

On Configuration, use Definition of done to add optional DoD evidence patterns (so checked checklist items without real description evidence can be flagged), and Content & impact to list org-specific impact tokens (so descriptions that name other teams or systems without a dependency link can be flagged). Leave those empty if you do not want those checks. After saving, run analysis again to refresh findings.

Security and credential storage

You do not need implementation details to use the product safely. In short:

• Secrets are not stored in plain text; they are protected in line with the security checklist.
• Logs and support tooling must not embed full issue bodies or tokens.

Operators and security reviewers: NFR-03 checklist. Which Jira fields may be stored (vs link-out only): Jira-derived persistence allow-list.

PRD §11 and single-tenant vs SaaS

Some §11 open questions (PRD v19) are tracked in PRD §11 open questions. Where §12 (multi-tenant SaaS) supersedes older “env-only” assumptions — for example MCP credentials — the open-questions doc points at the SaaS model instead of single-tenant env tokens.

Related tasks (implementation backlog)

Organization MCP (Claude Desktop / Cursor / GitHub Copilot)

Who this is for: organization administrators connecting desktop AI clients to live workspace intelligence; coaches and analysts using governed read access without a bloated tool list.

What it does

• Organization settings → Integrations → MCP lets org admins enable MCP (off by default), copy Cursor, Claude Desktop bridge, or GitHub Copilot snippets, run a Test connection, and review a metadata-only audit log (no finding payloads).
• External MCP clients see at most three tools: `read`, `analyze`, `call_agent`. The Assist agent catalog is exposed as an MCP resource (flow-analyzer://catalog/agents), not as dozens of per-agent tools.
• Connection profiles when creating API keys: Read-only coach (findings, dashboard, flow story), Analyst (+ run analysis), Assist automation (+ allowlisted agents). Keys can also use a legacy full six-tool surface for backward compatibility.

How to set it up

1. Sign in as org admin → Organization and workspaces → Integrations → MCP.
2. Turn on Enable MCP for this organization.
3. Open API keys, create a key with the profile that matches your client (for example Read-only coach for Cursor read-only coaching).
4. Copy the Cursor remote HTTPS or Claude Desktop bridge snippet. Store the API key in your secrets manager or bridge environment variables — never commit it to mcp.json.
5. Run Test connection in the MCP tab to confirm tools/list returns the expected tool count.

When MCP is disabled at the org level, hosted `/mcp` returns `mcp_disabled` for all keys until you enable it again.

GitHub Copilot (coaches)

Who this is for: Scrum Masters and agile coaches who use GitHub Copilot in VS Code or Visual Studio and want the same findings and dashboard evidence as the web app without exporting spreadsheets.

What problem it solves: You connect Copilot to your hosted workspace through MCP, then use the Flow Analyzer flow coach custom agent so Copilot reads live findings before suggesting analysis or Assist agent runs.

How to set it up: Follow `doc/integrations/github-copilot-mcp.md` — enable org MCP, create a profile API key, configure VS Code mcp.json (stdio bridge or remote HTTPS), and copy flow-analyzer-flow-coach.agent.md into .github/agents/ in your coaching repo. Store fa_live_* keys in environment variables or secret inputs, never in committed JSON.

Tool order: read (findings, dashboard, or flow story) before analyze or call_agent. Profile keys expose at most three MCP tools; Assist agents are listed via MCP resource flow-analyzer://catalog/agents.

Rule citations: In Copilot answers, rules appear as WD-01: Missing acceptance criteria (not bare WD-01). call_agent requires write:agents, ai_assist_enabled: true, and the consent header — otherwise the server fails closed with scope_forbidden or consent_required (same as `doc/api/mcp-server.md`).

Claude Desktop (coaches)

Who this is for: Scrum Masters and agile coaches who use Claude Desktop and want the same findings and dashboard evidence as the web app without exporting spreadsheets.

What problem it solves: You connect Claude to your hosted workspace through MCP (stdio bridge or remote HTTPS), then add the Flow Analyzer flow coach skill as Claude Project custom instructions so Claude reads live findings before suggesting analysis or Assist agent runs.

How to set it up: Follow `doc/integrations/claude-mcp-skill.md` — enable org MCP, create a profile API key, configure claude_desktop_config.json (stdio bridge or remote HTTPS), and paste packages/mcp-bridge/skills/flow-analyzer-flow-coach/SKILL.md into a Claude Project. Store fa_live_* keys in environment variables, never in committed JSON.

Tool order: read (findings, dashboard, or flow story) before analyze or call_agent. Profile keys expose at most three MCP tools; Assist agents are listed via MCP resource flow-analyzer://catalog/agents.

Rule citations: In Claude answers, rules appear as WD-01: Missing acceptance criteria (not bare WD-01). call_agent requires write:agents, ai_assist_enabled: true, and the consent header — otherwise the server fails closed with scope_forbidden or consent_required.

Cursor (coaches)

Who this is for: Scrum Masters and agile coaches who use Cursor as their primary AI coding and coaching environment and want governed workspace reads without exporting spreadsheets.

What problem it solves: You connect Cursor to your hosted workspace through MCP (remote HTTPS or the stdio bridge), then add the `flow-analyzer-mcp.mdc` rule so the agent reads live findings before suggesting analysis or Assist agent runs.

How to set it up: Follow `doc/integrations/cursor-mcp.md` — enable org MCP, create a profile API key, configure Cursor Settings → MCP (remote url + Authorization header or bridge command + env vars), and copy flow-analyzer-mcp.mdc into .cursor/rules/. Store fa_live_* keys in environment variables or a local secrets file, never in committed mcp.json.

Tool order: read (findings, dashboard, or flow story) before analyze or call_agent. Profile keys expose at most three MCP tools; Assist agents are listed via MCP resource flow-analyzer://catalog/agents.

Rule citations: In Cursor agent answers, rules appear as WD-01: Missing acceptance criteria (not bare WD-01). call_agent requires write:agents, ai_assist_enabled: true, and the consent header — otherwise the server fails closed with scope_forbidden or consent_required (same as `doc/api/mcp-server.md`).

Guided focus vs Advanced mode

Who this is for: coaches, tribe leads, and team members who want findings and dashboard widgets aligned to their improvement goals without changing which workspace rules run.

What it does

• Guided mode filters what you see on Findings and the portfolio dashboard (top findings, interventions, correlation hints) to rule families that match your selected goals (G1–G8).
• Analysis still runs all workspace rules — Guided mode does not disable rules in the catalogue or engine. Workspace admins continue to manage rule enablement on the Rules catalogue screen.
• Flow Health on the dashboard stays based on all findings in the workspace; a small badge explains that when Guided mode is active.

Where to start

1. On first visit to Flow Analyzer you may see the Focus Wizard (five steps: goals → problems → surfaces → review → apply). You can continue without the wizard to stay in Advanced mode (no personal filter).
2. Re-open the wizard from Guided setup in the Getting Started sidebar, from the Rules catalogue toolbar, or from My focus on your Profile page.
3. Switch between Guided and Advanced on the Profile page without losing your goal selection.

Workspace delivery focus (org default)

Organization admins can set optional shared delivery focus defaults per workspace under Organization and workspaces → open a workspace → Workspace delivery focus (default). Pick one or more G1–G8 goals; members who have not saved their own Focus Wizard profile inherit these defaults in Guided mode. Personal profiles always override workspace defaults. This avoids every new member starting with an empty focus until they complete the wizard. Shared exports still use objective ranking (no per-viewer goal affinity) until the product enables that after org-wide defaults are stable.

Brief scope churn outcome

When scope was added in the analysis window or scope-control (SC) rules fire, Start here shows a Scope churn outcome panel under your goal chips: scope added (SP), % SP done, and SC finding counts, with a link to SC findings on Findings.

Reporting gap — scorecard and audit retainer (#119)

Who this is for: PMO leads, delivery sponsors, and consultants who need to turn a one-off integrity readout into ongoing trust monitoring.

Where: sidebar Overview → Reporting gap (/flow-analyzer/truth-gap).

Overview tab (unchanged core): compares reported throughput with forensic flags on completed work. When the gap is above zero, an estimated delivery capacity at risk line shows days per quarter (estimate) with a methodology tooltip — the same number appears on the Brief risk card (when the gap line is shown) and in the HTML report executive summary.

Scorecard tab: line chart of gap flagged (%) and integrity finding count across real analysis runs (no fabricated history). Needs at least two succeeded runs; otherwise you see guidance to re-ingest or compare snapshots. When a tribe filter is active but historical tribe mapping is missing, the chart falls back to workspace-level trend with helper copy.

Audit retainer tab: organization admins pin a baseline audit run (AlertDialog confirmation). Later runs classify integrity findings as held, regressed, or new, with issue-key drill and links to improvement-action verify outcomes (✓ held / ✗ not held / pending) using the existing verify engine. Without a pinned baseline, use Pin current analysis or open Compare imports to pick a run — no error wall.

Saved views

Completing the wizard creates personal saved findings views (filtered by families= in the URL). Re-running the wizard replaces prior wizard-created views for your account only.