name: present, matches directory name, valid kebab-case (^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$)

name convention: the name should describe the workflow's end-to-end purpose using thing-process or thing-process-approach; flag names that overfit the exact graph shape or enumerate too many steps

description: present, concise, specific, and not placeholder text (TODO, <placeholder>)

goal-hint: hint text displayed across user interfaces (TUI, web, email, Slack, etc.) when the workflow is activated, guiding the user to provide a specific goal. Most workflows should include this because most workflows expect the user to supply their own objective. If present, it should be a concise, actionable question (e.g., "What kind of data analysis do you want to perform?"). Flag hint text that is generic or unhelpful. If absent on a workflow that clearly expects user-supplied goals, recommend adding it

goal: optional, but if present it should express a stable, fixed objective and be meaningfully distinct from description. Flag generic goals that merely restate the workflow's purpose (e.g., "Produce an acceptable X for the requested purpose") — they provide no runtime value and clutter the user interface. Recommend replacing them with goal-hint or removing them entirely

Optional fields: license, compatibility, metadata — check for correctness if present (e.g., compatibility under 500 characters)

Unknown fields: flag frontmatter fields that do not match the workflow conventions in this workspace as warnings, especially custom fields that appear to duplicate executable configuration already represented in the DOT graph

prefer thing-process for the default case, for example code-review or blog-generation

prefer thing-process-approach when different workflows for the same process need different tradeoff signals, for example code-generation-iterative or agent-creation-guided

treat approach as a broad strategy or cost/quality tradeoff, not as a literal summary of the graph

warn on names that try to encode the entire pipeline shape, such as create-review-refine-test-deploy, unless there is a strong workspace-specific reason for that style

The Markdown body should begin with a short human-readable explanation of the workflow before the first dot fenced code block; flag workflows that jump straight into the DOT block without any introductory prose

The first dot fenced code block in the body contains a valid-looking directed graph such as digraph name { ... }

The workflow has a clear executable path from start to finish

Node and edge names are readable and internally consistent

Prompts, agent attributes, conditions, and labels are attached to the correct nodes or edges

The DOT source follows the workspace house style: keep the Start -> ... entry edge near the top, then colocate each node definition with its outgoing edge or edges where practical

The graph is not missing obvious terminal or branching connections

Only the first dot block is relied on for execution; additional DOT blocks, if any, are treated as documentation and should not create ambiguity

When a node uses workflow="name", treat it as a composed child workflow node and check that the composition boundary is clear and justified; this attribute is normalized to workflow-handler semantics rather than acting like a normal LLM, shell, or branch node

When a node uses a FanOut… node ID prefix (static fan-out), check that it has multiple outgoing edges (a fan-out with a single branch is unnecessary) and that the branches converge at a downstream node (either an explicit FanIn… prefix / shape=tripleoctagon node or a structural convergence); flag fan-out nodes with no plausible fan-in point

When a node uses fan-out="key" (dynamic fan-out), check that it has exactly one outgoing edge (the runtime creates parallel instances from the stored list), that a fan-in node (FanIn… prefix or shape=tripleoctagon) is reachable downstream, and that the context key is plausibly populated by an upstream node — either a shell node with store or an agent node with context-writable=true that writes a JSON array via workflow_set_context; flag nested dynamic fan-out (dynamic fan-out inside another dynamic fan-out's template subgraph) as an error

The sequence of steps makes progress toward the stated goal rather than repeating generic prompting

The workflow breaks non-trivial tasks into meaningful stages with clear outputs or decision points

Branches, loops, and approval gates are used only where they add value

Revision loops have a plausible feedback path rather than a vague cycle

Human review (via ask attribute) is used appropriately for approval, oversight, or trust-boundary decisions

Multi-question interviews via interview-ref are used appropriately — combining a routing decision with structured feedback in a single review pause, not overloading a single interview with unrelated questions that would be clearer as separate human nodes

When an interview uses show-if, check that the referenced store key belongs to an earlier question and the condition syntax is valid ("store_key == value" or "store_key != value"); flag show-if conditions that reference a store key from the same or a later question

When an interview uses finish-if, check that it is on a yes-no, confirm, or single-select question — finish-if is not supported on freeform or multi-select questions; verify that the early exit value makes sense for the interview flow and that questions after the gate are ones the user would genuinely want to skip

Workflow composition is used appropriately — child workflows should encapsulate meaningful reusable subprocesses, not obscure simple local steps without a readability or reuse benefit

Parent workflows should focus on orchestration, while child workflows should own detailed internal execution where that split improves clarity

Top-down design is a valid approach: a workflow may intentionally reference agents or child workflows that do not yet exist, planning to create them later. When a workflow appears to follow this pattern, evaluate the pipeline structure and stage responsibilities on their own merits rather than penalizing unresolved references; instead note which dependencies remain to be created

The workflow is no more complex than necessary for the task

When a workflow uses parallel fan-out (FanOut… node ID prefix or the underlying shape=component), check that: all branches are genuinely independent and do not depend on each other's output; branches reconverge at a clear fan-in point (either an explicit FanIn… prefix / shape=tripleoctagon node or a structural convergence where all branches share a common downstream node); join_policy, error_policy, and max_parallel are appropriate for the task; and the fan-out is not used where a simple sequential pipeline would be clearer

When a workflow uses a sequential loop-and-check pattern to iterate over a collection of items, consider whether the items are independent — if so, suggest the appropriate fan-out pattern: if the list is known at graph-definition time, use static fan-out (FanOut… node ID prefix / shape=component) where the number of branches is fixed in the DOT graph; if the list is determined at runtime (e.g., produced by a shell node with store), use dynamic fan-out (fan-out attribute) which creates parallel instances from a variable-length list; if items have dependencies on each other's output, a sequential loop is still the correct choice

Referenced agent names should be plausible; use list_agents to confirm availability and metadata fit when uncertain. Forward-referencing agents that do not yet exist is valid in top-down design — the runtime falls back to a default agent, so flag missing agents as informational dependencies rather than errors

Agent selection should be justified by metadata, not name alone: description should match the task, keywords should overlap domain terms, when-to-use should provide positive signals, and when-not-to-use should not conflict with the node's role

The workflow does not overuse agent.* overrides where simpler inline attributes would be clearer

A workflow with no agent attributes may be valid, but note when explicit agent selection would materially improve clarity or control

For workflow="name" nodes: check that the child workflow name is plausible (use list_workflows to compare alternatives when composition matters); check that the child goal is passed clearly via goal="..." or a sensible default from prompt/label; and flag missing child workflows as outstanding dependencies in top-down designs rather than errors

Child workflow selection should also be justified by metadata, not name alone

Recommend nesting a child workflow only when it encapsulates a meaningful reusable subprocess, improves readability, or cleanly separates orchestration from execution; flag trivial or over-engineered nesting

Prompts are specific enough to guide each node's local task

When a node uses persist, check that the workflow uses it for the right reason: prefer persist when a node should keep its own conversational context but threads do not need to be shared across nodes. If the apparent intent is a shared multi-node conversation, warn that persist alone auto-generates different thread-id values per node and therefore does not create cross-node session sharing

When multiple sequential nodes appear intended to share one conversation, check for an explicit shared thread-id with fidelity="full" or graph-level defaults (default-fidelity="full", default-thread-id="...") instead of repeated persist attributes

Flag reuse of the same thread-id across different agents or across parallel branches, because shared threads should remain on one agent and one sequential path

When the workflow uses prompt-ref, shell-ref, ask-ref, or interview-ref, referenced ids exist in code blocks or code chunks in the same WORKFLOW.md, are unique, and are used where they improve readability, typically for long or multiline content rather than short single-line values

If goal is present, prompts should use $goal consistently. If goal is absent but prompts reference $goal, check that goal-hint is set (the user's response becomes $goal at runtime)

The workflow does not overuse content refs where simpler inline attributes would be clearer

When a workflow uses interview-ref, check that the referenced YAML block is valid interview spec YAML (has a questions array with at least one entry, each question has question text and a recognized type)

Check that freeform questions in the interview spec have store keys — a freeform question without store collects an answer that is never stored, which is almost certainly a mistake

Check that the routing question (first single-select) has option labels matching the outgoing edge labels from the human node

Check that show-if conditions reference valid store keys from earlier questions and use the correct syntax; flag conditions that would always be true, always be false, or reference non-existent keys

Check that finish-if is only used on supported question types (yes-no, confirm, single-select) and that the early-exit value is a valid answer for that question type (e.g., "yes" or "no" for yes-no, an option label for single-select)

Flag interview-ref used for a single simple question where ask or ask-ref would be simpler

When a shell node uses store="key", check that the stored key is referenced downstream — either in a fan-out attribute, a $KEY expansion in a prompt or shell command, or an edge condition; flag store on shell nodes without downstream consumers as a warning (storing data nobody reads)

When a shell node uses store-as="json", check that the shell command plausibly produces valid JSON output (e.g., uses jq, prints a JSON literal, or wraps output in JSON structure); flag store-as="json" on commands whose output is unlikely to be valid JSON

When a dynamic fan-out node references a context key via fan-out="key", verify that an upstream node populates that key — either a shell node with store="key" (ideally with store-as="json") or an agent node with context-writable=true that calls workflow_set_context to write a JSON array (e.g., fan-out="items"); flag fan-out keys with no plausible upstream producer

If the workflow is explicitly intended to be ephemeral, the directory contains a .gitignore file with exactly *

If the workflow is permanent, it should not use custom frontmatter like ephemeral: true or other non-standard markers to indicate temporary status

Report whether the ephemeral/permanent status is clear from the directory contents and workflow context

If the workflow only appears temporary by context but does not explicitly claim ephemeral status, a missing sentinel is usually a warning rather than a failure

keywords: if present, check that keywords are relevant, not redundant with the description, and include likely user-intent words and domain terms. Flag generic or overly broad keywords. If absent, recommend adding keywords to improve discoverability

when-to-use / when-not-to-use: if present, check that entries are specific, actionable, and complementary to the description rather than duplicating it. Flag vague signals. If absent, recommend adding them to improve manager delegation accuracy

Coherence check: verify that description, keywords, when-to-use, and when-not-to-use work together — they should be complementary, not redundant

Agent and composition coherence: check that agent and child workflow assignments are consistent with their metadata (see Agents and Prompts above). For composition, check that the parent description, node names, and child workflow purposes fit together coherently; use list_workflows when needed to compare alternatives

The file has no placeholder content (TODO, <placeholder>, empty sections)

The body begins with a short human-readable explanation before the DOT block, and any additional Markdown documentation after the DOT block supports the workflow and does not contradict it

References to supporting files in scripts/, references/, or assets/ point to files that actually exist

References from DOT to reusable fenced code blocks via prompt-ref, shell-ref, ask-ref, and interview-ref point to ids that actually exist in the same file

References from DOT to composed child workflows via workflow="name" point to workflows that exist when the review scope allows that to be checked; if child workflows do not yet exist, note them as outstanding dependencies for top-down designs rather than treating them as errors

When supporting files are large, check existence and relevance without reproducing their full contents in the report

The workflow is understandable to both the execution engine and a human reader

Formatting is consistent (heading levels, list styles, code block languages)

Terminology is used consistently throughout

Conventions match other workflows and workflow-related skills in the same workspace; compare against one or two nearby examples when available

DOT organization is easy to scan: entry edge first, then node-local blocks instead of a large separated edges section and nodes section

The workflow's frontmatter, Markdown explanation, and DOT graph do not contradict each other

The workflow name aligns with current workspace naming guidance and, when present, any approach modifier is used consistently with similar workflows

If the workflow uses composition, parent and child workflows use consistent terminology for the subprocess being delegated

✅ Pass — criterion fully met

⚠️ Warning — minor issue or room for improvement

❌ Fail — significant problem that should be fixed

Workflow not found: Report the error clearly and suggest checking the name or path. Prefer listing .stencila/workflows/ directories directly; mention stencila workflows list only if that command is available in the current environment.

Multiple workflows requested: Review each workflow separately with its own report section. Ask the user to confirm if reviewing all workflows is intended.

No body content: Flag this as a failure — a workflow without a DOT pipeline is incomplete for execution unless the user explicitly asked for documentation only.

No dot block: Flag this as a failure for an executable workflow. The first dot block is the executable pipeline source of truth.

Additional DOT blocks: Treat only the first dot block as executable. If later DOT blocks could confuse the intended pipeline, flag that as a warning.

Unknown agents: Use list_agents when agent selection matters so you can assess availability and metadata fit. If agents do not exist, distinguish between two cases: (a) the workflow appears to be designed top-down with intentionally planned agents — list them as outstanding dependencies to create, not as errors; (b) the names look like accidental placeholders or typos — flag them as warnings. The runtime accepts unresolved agent references (logging a warning and falling back to a default agent), so missing agents never block validation or execution.

Unknown child workflows: Use list_workflows when workflow composition matters so you can assess availability and metadata fit. As with agents, distinguish intentional top-down forward references from accidental placeholders. List planned but not-yet-created child workflows as outstanding dependencies rather than flagging them as errors.

Ephemeral status unclear: If the workflow seems temporary but lacks the .gitignore sentinel, flag that as a warning or failure depending on how strongly the workflow claims to be ephemeral.

Supporting files are large: For files in scripts/, references/, or assets/, check that they exist and are referenced where appropriate, but do not reproduce their full contents in the report.

User asks to fix issues: If the user asks you to apply suggestions, make the changes, then validate using the workflow directory path or WORKFLOW.md path before reporting completion; use name-based validation only when the name is unambiguous.

This skill reviews the structure, quality, and conventions of a workflow definition. It does not execute the workflow or verify the runtime behavior of referenced agents

DOT graph assessment is based on static review of the workflow definition, not full execution semantics