[SC-17022] Document risk tiering workflow integration

[kam-validmind]

Pull Request Description

What and why?

Documents the risk tiering workflow integration shipped in SC-17022 (validmind/backend#3347 + validmind/frontend#2714, merged 2026-08-07). The story carries the needs-docs label; nothing in the docs covered any of it before this PR.

Before: The risk tiering guides covered templates, calculation, and assessments only. The workflows guide had no mention of risk tiering — no Risk Tiering workflow target, no stage-change steps, no governance stages.

After:

• New page — Set up risk tiering workflows: governance stages (Settings → Risk Tier Stages, its two tabs, and which workflow step consumes each), adding a risk tiering workflow (Applies to: Assessment vs Template, scope, Manually / On Risk Assessment Published / On Risk Tier Template Published start modes, the one-publish-triggered-workflow-per-scope rule), configuring stage-change steps and branching on the assessed risk tier, the stage badge + Active Workflows rail, and the governance-run model (one run per published version; rejection ends the run; republishing aborts prior runs and starts a fresh review; approval never publishes — a person does).
• Workflow step types (_workflow-step-types.qmd): adds Risk Assessment Stage Change and Risk Tier Template Stage Change step reference sections (HTML + RevealJS variants), placed between Artifact Status Change and Workflow State Change to match the builder's step order.
• Add workflows (_add-new-workflows.qmd): adds the Risk Tiering target and an "Add risk tiering workflows" tab (HTML + RevealJS variants).
• Workflow states (_workflow-states.qmd): adds the Risk Tiering Workflows tab to the three tab lists.
• Risk tiering pages: governance-stage key concept and access paths on the overview page; Assessment Stage badge + Active Workflows rail in the assessment sidebar reference; publish-triggers-a-review notes on the assessment and template publish sections; sidebar/listing entries for the new page.

All UI labels, step names, trigger names, and constraints were verified against the merged frontend/backend code on main (not just the PR descriptions) — including the post-merge correction that displaced runs end as aborted (the separate superseded status was removed).

How to test

Rendered locally, one page per invocation via the bundled helper:

skills/validmind-docs-coverage/scripts/render-pages.sh \
  guide/risk-tiering/set-up-risk-tiering-workflows.qmd \
  guide/risk-tiering/working-with-risk-tiering.qmd \
  guide/risk-tiering/manage-risk-tier-assessments.qmd \
  guide/risk-tiering/manage-risk-tier-templates.qmd \
  guide/workflows/workflow-step-types.qmd \
  guide/workflows/configure-workflows.qmd \
  guide/workflows/workflow-states.qmd \
  training/administrator-fundamentals/using-validmind-for-risk-management.qmd

All eight pages render cleanly; the only warning (validmind/validmind.qmd) is pre-existing site chrome from _quarto.yml, present on unmodified pages too. New anchors (#risk-assessment-stage-change, #risk-tier-template-stage-change, #define-governance-stages, #add-a-risk-tiering-workflow) verified in the rendered HTML. git diff --check clean.

Preview links (after the validate deploy finishes):

• https://docs-staging.validmind.ai/pr_previews/kam/sc-17022-risk-tiering-workflows-docs/guide/risk-tiering/set-up-risk-tiering-workflows.html
• https://docs-staging.validmind.ai/pr_previews/kam/sc-17022-risk-tiering-workflows-docs/guide/workflows/workflow-step-types.html#risk-assessment-stage-change
• https://docs-staging.validmind.ai/pr_previews/kam/sc-17022-risk-tiering-workflows-docs/guide/workflows/configure-workflows.html
• https://docs-staging.validmind.ai/pr_previews/kam/sc-17022-risk-tiering-workflows-docs/guide/workflows/workflow-states.html
• https://docs-staging.validmind.ai/pr_previews/kam/sc-17022-risk-tiering-workflows-docs/guide/risk-tiering/working-with-risk-tiering.html

What needs special review?

• Feature-flag stance: the feature sits behind launchdarkly.rollout.risk-tier-engine.workflows (subordinate to risk-tier-engine), off by default. Following the existing risk-tiering docs convention, the pages do not mention flags — the new page's prerequisites say "Risk tiering enabled for your organization". Confirm this should merge now vs. being held for the flag rollout.
• Governance-run semantics ("How governance runs behave" section) are drawn from the story's docs-spec comment and the merged backend behavior — worth a product read to confirm the wording on rejection/republish/abort.
• The _add-new-workflows.qmd include still describes a "Workflow Target" selector for record/artifact workflows while the current UI uses tabs; that predates this story and was left as-is (flagging for a separate cleanup).

Dependencies, breaking changes, and deployment notes

• Documents validmind/backend#3347 and validmind/frontend#2714 (both merged).
• No dependencies on other docs PRs; no breaking changes.

Release notes

Added documentation for risk tiering workflows: define governance stages, start reviews automatically when an assessment or template is published (or on demand), move stages with dedicated workflow steps, branch on the assessed risk tier, and track review progress on the assessment and template pages. Learn more ...

Checklist

• What and why
• Screenshots or videos (Frontend)
• How to test
• What needs special review
• Dependencies, breaking changes, and deployment notes
• Labels applied
• PR linked to Shortcut
• Unit tests added (Backend)
• Tested locally
• Documentation updated (if required)
• Environment variable additions/changes documented (if required)

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[juanmleng]

Really nice piece of work — I went through this claim by claim against origin/main in both product repos rather than against the PR descriptions, and essentially everything checked out: the UI labels, the step names, the trigger names, the Settings nav paths, the step ordering in the builder, the one-publish-triggered-workflow-per-scope rule, the Risk Assessment Field: Assessed Risk Tier branch label, and the "ends as aborted" wording. That last one is the kind of detail that usually goes stale, so it was good to see it right.

Two things in the new page are worth fixing before this goes out, and both are a sentence each. The rest is minor or already on your radar.

The stage-deletion callout promises a safeguard that doesn't exist

Worth fixing before merge.

An admin who follows this page can delete a stage a workflow step depends on, and the review will then silently stop advancing. The callout at set-up-risk-tiering-workflows.qmd:56 says a stage in use by a workflow step cannot be deleted, and tells the reader to unhook it from the step first. Neither half holds.

The platform only refuses the delete when an assessment or template is currently sitting in that stage — it never looks at workflow steps. RiskTierAssessmentStage.get_dependencies returns assessments matched on stage_id and nothing else (db/risk_tier_assessment_stage.py:186), and the handler describes itself as returning "records currently set to this stage". So deleting an unused stage — the Approved stage nobody has reached yet, say — succeeds. The workflow step keeps pointing at a stage that is gone, and at run time the step resolves nothing, logs an error and returns false (workflows/managers.py:6315). No error reaches the user; the badge just never moves.

The suggested remedy also doesn't help in the case that genuinely is blocked: unhooking the step won't let you delete a stage an assessment currently occupies, and the page offers no way out of that one.

Fix: state the real rule — a stage can't be deleted while an assessment or template is currently in it, and deleting a stage a workflow step still references is allowed and will quietly break that step, so update the step first.

Following the page produces a workflow that never runs

Worth fixing before merge.

A reader who follows this page end to end builds a governance workflow that never fires, with nothing to tell them why. "Add a risk tiering workflow" ends at Save Draft (set-up-risk-tiering-workflows.qmd:88) and hands off to configuring steps; nothing on the page says the workflow has to be published before it does anything.

A draft workflow starts nothing. A manual start comes back with "Cannot start a draft workflow" (routes/ui_workflows.py:1468), and the publish-triggered case — which is the whole point of the feature — simply never fires, with no signal at all. The sibling flow does cover this: configure-workflows.qmd runs 1. Add → 2. Configure steps → 3. Link → 4. Publish workflow. This page substitutes its own section for steps 2–3 and drops step 4 along with them.

Fix: after "Configure risk tiering steps", add a line pointing at Publish workflow and say plainly that a draft workflow never starts.

Regenerating the chatbot map quietly dropped a page from three routes

Non-blocking, and not really yours to solve.

Someone asking the in-app assistant about record stages while sitting on the Workflows settings page has just lost the canonical how-to from the assistant's context. The regenerated chatbot-product-map.md in the second commit isn't purely additive — adding the new page pushed /guide/workflows/manage-record-stages.html out of the related-docs list for /settings/workflows, /settings/workflow-states and /workflows.

suggest_related_docs keyword-matches, sorts by path and truncates with related[:6] (site/scripts/generate_chatbot_product_map.py:350). The ranking is alphabetical rather than relevance-based, so which page falls off is arbitrary: the new page sorts under /guide/risk-tiering/, ahead of everything under /guide/workflows/, and evicts whatever was last. Nothing warns when the cap bites, and every future guide page in an early-sorting directory will do the same thing to something else.

Fix: nothing needed here beyond deciding whether you're happy with the trade. The generator is the real fix and is worth tracking separately.

Prerequisites miss the permission the stages half of the page needs

Non-blocking, one bullet.

A reader with workflow rights but not template rights won't see Risk Tier Stages in the sidebar at all, and the page gives them nothing to go on. The prerequisites at set-up-risk-tiering-workflows.qmd:15 list Customer Admin or equivalent workflow permissions, but "Define governance stages" is gated on the risk tier template permission instead — every stage route is @requires_auth(resource="RiskTierTemplate", action="manage"), and the sidebar entry needs read_risk_tier_template.

Fix: add a second prerequisite bullet, phrased the way manage-risk-tier-templates.qmd already does it ("Governance Admin or Validator role with manage_risk_tier_template permission").

Archived versions are terminal for governance, and the page doesn't say so

Non-blocking.

A reader is likely to try restarting a review on the version that was just displaced, and get refused. The page explains that republishing archives the previous version and aborts its runs, then says a manual review "can be re-run on demand" (set-up-risk-tiering-workflows.qmd:121). Joining those two sentences leads somewhere that doesn't work: no workflow of any kind can start on an archived assessment or template (routes/ui_workflows.py:1446-1460).

Fix: one clause in "How governance runs behave" — once a version is archived it's terminal for governance, and a re-run happens on the current version, not the displaced one.

The Workflow Target selector

Non-blocking, and predates this PR — you already flagged it.

Just to confirm your read: there's no Workflow Target selector in the UI at all any more. Settings → Workflows is three tabs with per-tab buttons — Add Workflow, Add Artifact Workflow, Add Risk Tiering Workflow (pages/Settings/Workflows/index.tsx:1084-1100). The new Risk Tiering bullet inherits that stale frame and then contradicts it in its own second sentence by sending the reader to a tab, so someone following steps c–d in order has two conflicting instructions. Agreed it's out of scope here, but worth tracking separately so it doesn't get inherited by whoever adds the fourth workflow kind.

On the things you asked about

Feature-flag stance — I'd ship it. The precedent you're leaning on is real: the four existing risk-tiering guide pages are already on main and published while the engine flag still gates the feature, and none of them mention flags. "Risk tiering enabled for your organization" matches that exactly. I don't see a reason to hold this for the rollout.

Governance-run semantics — accurate as written. I checked each claim separately: the one-run-per-published-version binding, the abort-on-republish wording, approval never changing status, and rejection ending the run all match the merged behaviour. The two gaps in that area are the publish step and the archived-is-terminal point above — nothing in it is stated wrongly.

One for the product side, not this PR

The behaviour behind the first comment is worth a ticket on its own. Stage deletion checks only assessments and templates currently in the stage, never the workflow steps that reference it, and the resulting dangling reference fails closed at run time with only a log line to show for it. Either the dependency check should include referencing workflow steps, or the failure should surface on the execution instead of being swallowed. The docs change above just describes today's behaviour accurately — this is the behaviour worth changing.

Also minor and entirely optional: manage-risk-tier-assessments.qmd got proper sidebar-reference entries for the Assessment Stage badge and the Active Workflows rail, while manage-risk-tier-templates.qmd gets one passing sentence — the template detail page renders the identical pair, so the asymmetry may read as an omission later.

[juanmleng]

Really great job @kam-validmind ! thanks so much for taking this PR. I just left a couple of items to look at, other than that, is good to go!

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[github-actions]

Lighthouse check results

✓ INFO: Average accessibility score is 0.92 (required: ≥0.9) — View the workflow run

Audit mode: changed pages (4 URL(s))

Show Lighthouse scores

Commit SHA: 5a66c08

For a thorough audit, run the Lighthouse check workflow manually (Actions → Lighthouse check → Run workflow) with depth 0–2, or add the lighthouse:full label for depth 2 on the next validate run.

Page	Accessibility	Performance	Best Practices	SEO
/guide/risk-tiering/manage-risk-tier-assessments.html	0.93	0.72	1.00	0.91
/guide/risk-tiering/manage-risk-tier-assessments.html	0.93	0.74	1.00	0.91
/guide/risk-tiering/manage-risk-tier-templates.html	0.92	0.72	1.00	0.91
/guide/risk-tiering/manage-risk-tier-templates.html	0.92	0.73	1.00	0.91
/guide/risk-tiering/set-up-risk-tiering-workflows.html	0.93	0.72	1.00	0.91
/guide/risk-tiering/set-up-risk-tiering-workflows.html	0.93	0.73	1.00	0.91
/guide/risk-tiering/working-with-risk-tiering.html	0.91	0.71	1.00	0.91
/guide/risk-tiering/working-with-risk-tiering.html	0.91	0.70	1.00	0.91
/guide/risk-tiering/manage-risk-tier-assessments.html	0.93	0.72	1.00	0.91
/guide/risk-tiering/manage-risk-tier-templates.html	0.92	0.73	1.00	0.91
/guide/risk-tiering/set-up-risk-tiering-workflows.html	0.93	0.72	1.00	0.91
/guide/risk-tiering/working-with-risk-tiering.html	0.91	0.70	1.00	0.91