[SC-16429] Document artifact field-change workflow triggers

.claude/skills

@@ -0,0 +1 @@
+../skills

AGENTS.md

@@ -49,6 +49,19 @@ Documentation is written in Quarto Markdown (`.qmd`). Key conventions:
 - Cross-references use relative paths ending in `.qmd`
 - Images are stored alongside their `.qmd` files
 
+## Documentation coverage reviews
+
+When validating documentation coverage for a Shortcut story or engineering change:
+
+- Read the full story and inspect the final implementation pull requests. Treat the implemented behavior as authoritative when it differs from the story description, while verifying merge and release state before calling it shipped.
+- Compare that behavior with documentation on current `origin/main` and classify coverage as Covered, Partial, Outdated, Missing, or Source Gap.
+- Search for every consumer of edited Quarto includes and validate all affected formats, including both HTML guides and RevealJS training where applicable.
+- Render affected pages one at a time. Use `skills/validmind-docs-coverage/scripts/render-pages.sh` for multi-page validation.
+- Add direct links to each changed page in the pull request after the ready-for-review `validate` job deploys the preview.
+- Verify current review, validation, and merge state immediately before describing a pull request in Shortcut or a release tracker. Do not update tracker task state unless explicitly requested.
+
+For the complete Shortcut-to-documentation workflow, use [ValidMind documentation coverage](skills/validmind-docs-coverage/SKILL.md).
+
 ## Pull requests and release notes
 
 Documentation pull requests must follow the repository's release-note policy:

site/guide/workflows/_add-new-workflows.qmd

@@ -47,6 +47,7 @@ iv. Under **Workflow Start**, select when the workflow should be initiated:
 
 - **Manually** — Start this workflow manually.^[[Initiate workflows](/guide/workflows/manage-workflows.qmd#initiate-workflows)]
 - **On Artifact Registration** — Start this workflow when an artifact is logged on a record.[^on-artifact-registration]
+- **On Field Change** — Start this workflow when a specific artifact field changes.[^on-artifact-field-change] To configure, select a field under **Artifact Field to Monitor**.
 - **Via Webhook** — Start this workflow when a webhook event is received.
 
 v. Under **Workflow Expected Duration**, define the SLA for the workflow based on the start date in days, weeks, months, or years.
@@ -80,6 +81,14 @@ vi. Click **Save Draft** to save your blank workflow, and then [configure your w
     <br></br>
     When selecting date or date time fields, check **Schedule workflow start for this date** to set the workflow to trigger on the existing date captured in the field rather than when its value changes.
 
+[^on-artifact-field-change]:
+
+    [Manage artifact fields](/guide/validation/manage-artifact-fields.qmd)
+    <br></br>
+    Only artifact fields available to the selected artifact type appear. Artifact fields that apply to all artifact types also appear. Record fields displayed from the parent record are not available as triggers.
+    <br></br>
+    When selecting date or date time fields, check **Schedule workflow start for this date** to set the workflow to trigger on the existing date captured in the field rather than when its value changes.
+
 [^artifact-workflow-record-scopes]:
 
     [Manage inventory record types](/guide/inventory/manage-inventory-record-types.qmd)
@@ -133,9 +142,10 @@ iv. Under **Workflow Start**, select when the workflow should be initiated:
 
 - **Manually** — Start this workflow manually.
 - **On Artifact Registration** — Start this workflow when an artifact is logged on a record.
+- **On Field Change** — Start this workflow when a specific artifact field changes. To configure, select a field under **Artifact Field to Monitor**. Only artifact fields available to the selected artifact type appear; record fields displayed from the parent record are not available as triggers.
 
 v. Under **Workflow Expected Duration**, define the SLA for the workflow based on the start date in days, weeks, months, or years.
 
 vi. Click **Save Draft** to save your blank workflow, and then configure your workflow steps.
 
-::::
+::::

skills/validmind-docs-coverage/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: validmind-docs-coverage
+description: Verify and implement documentation coverage for a ValidMind Shortcut story or engineering change by comparing final merged frontend/backend behavior with current documentation, classifying the gap, updating shared Quarto sources, validating every affected guide and training output, and preparing reviewer-ready pull requests and release-tracker updates. Use for single-story docs checks, `needs-docs` tickets, release documentation subtasks, or requests to create a documentation PR for a shipped change.
+---
+
+# ValidMind Documentation Coverage
+
+Validate coverage from implementation evidence, then make the smallest complete documentation change when authorized.
+
+## 1. Establish scope
+
+1. Read the repository `AGENTS.md`.
+2. Fetch the full Shortcut story, including comments, related stories, epic, linked branches, and pull requests.
+3. Identify the final implementation PRs in every affected repository.
+4. Inspect the PR bodies, changed files, relevant patches, tests, merge status, and later corrective PRs.
+
+Treat the final implementation diff as authoritative for behavior when it differs from the Shortcut description. Verify merge and release state separately. Distinguish:
+
+- Customer problem and expected behavior
+- Implemented product behavior
+- Explicit limitations and out-of-scope behavior
+- Proposed architecture that did not ship
+
+Do not treat an `internal` implementation label as evidence that a customer-visible capability needs no documentation.
+
+## 2. Compare with current documentation
+
+1. Fetch the latest `origin/main`.
+2. Extract user-facing terminology, UI labels, routes, configuration, limits, errors, and edge cases from the implementation.
+3. Search documentation with `rg`, starting in the most relevant section under `site/`.
+4. When the change is tied to a product route, consult `chatbot-product-map.md` and its frontend snapshot.
+5. Search for Quarto includes that consume any candidate shared source.
+
+Classify the result:
+
+| Status | Meaning |
+|---|---|
+| Covered | Current docs match the shipped behavior and important limitations. |
+| Partial | The feature is mentioned, but new options or behavior are missing. |
+| Outdated | Current instructions or stated behavior are now wrong. |
+| Missing | No appropriate documentation coverage exists. |
+| Source Gap | Implementation or release state is too uncertain to document safely. |
+
+For a verification-only request, stop after reporting the classification, evidence, affected pages, and recommended scope. Do not edit files or external trackers until authorized.
+
+## 3. Implement an approved update
+
+1. Confirm the worktree and current branch before editing.
+2. Start from current `origin/main` on a `codex/sc-<story-id>-<slug>` branch.
+3. Update the smallest authoritative source.
+4. Preserve Quarto variables, `.qmd` cross-references, conditional HTML/RevealJS variants, and existing terminology.
+5. If editing an include, find every consumer:
+
+```bash
+rg -n "_source-name\\.qmd" site --glob '*.qmd'
+```
+
+Document operationally important limitations without exposing unnecessary backend mechanics.
+
+## 4. Validate every consumer
+
+Render every affected parent page and every output format. Quarto accepts one page reliably per invocation for this repository; do not pass multiple page paths to one `quarto render` command.
+
+Use the bundled helper from the repository root:
+
+```bash
+skills/validmind-docs-coverage/scripts/render-pages.sh \
+  guide/example/page.qmd \
+  training/example/module.qmd
+```
+
+Then:
+
+1. Run `git diff --check`.
+2. Inspect rendered HTML under `site/_site/` for the new copy and anchors.
+3. Report render warnings explicitly and determine whether they are introduced by the change.
+4. Do not claim hosted preview success until the GitHub `validate` check passes.
+
+## 5. Prepare the pull request
+
+Follow `.github/pull_request_template.md` and the repository release-note policy.
+
+Include:
+
+- Shortcut story and final implementation PRs
+- Before/after documentation behavior
+- Exact local render commands or helper invocation
+- Special-review assumptions and limitations
+- A user-facing release-note entry
+- The `documentation` label for external content changes
+
+The hosted preview is created only after a draft PR becomes ready for review. Its base path is:
+
+```text
+https://docs-staging.validmind.ai/pr_previews/<branch>/
+```
+
+After `validate` succeeds:
+
+1. Verify each relevant preview page returns successfully.
+2. Add direct links to every changed rendered page, including useful section or RevealJS slide anchors.
+3. Prefer direct reviewer destinations over the preview root.
+
+## 6. Update release tracking
+
+When asked to update a release documentation tracker:
+
+1. Resolve the exact tracker and subtask for the engineering story.
+2. Comment with the documentation PR link and the behavior covered.
+3. Re-read GitHub state immediately before describing review, validation, or merge status.
+4. Do not mark the tracker task complete unless the user explicitly asks you to do so.
+
+## Evidence rules
+
+- Do not infer deployment or release from a merged PR alone when release evidence is required.
+- Do not describe a PR as approved, validated, or merging without checking current state.
+- If private-repository connectors return `404`, use authenticated `gh` as the fallback and preserve the same evidence standard.
+- Keep `Source Gap` explicit when implementation, configuration, or ownership cannot be verified.

skills/validmind-docs-coverage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ValidMind Docs Coverage"
+  short_description: "Verify and publish ValidMind documentation coverage"
+  default_prompt: "Use $validmind-docs-coverage to verify documentation coverage for this Shortcut story and prepare any required docs PR."

skills/validmind-docs-coverage/scripts/render-pages.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ "$#" -eq 0 ]]; then
+  echo "Usage: render-pages.sh <site-relative-page.qmd> [...]" >&2
+  exit 2
+fi
+
+repository_root="$(git rev-parse --show-toplevel)"
+site_root="${repository_root}/site"
+
+for requested_page in "$@"; do
+  page="${requested_page#site/}"
+  if [[ ! -f "${site_root}/${page}" ]]; then
+    echo "Page not found: ${requested_page}" >&2
+    exit 2
+  fi
+
+  echo "Rendering ${page}"
+  (
+    cd "${site_root}"
+    quarto render "${page}" --profile development
+  )
+done