| name | workflow-validate |
| description | Review Notion Worker workflows for trigger typing, unstable step order, non-serializable results, swallowed failures, secret handling, and duplicate side effects |
| user-invocable | true |
| disable-model-invocation | true |
| allowed-tools | ["Read","Glob","Grep","Bash"] |
Instructions
Review workflow definitions under src/workflows/ and any modules they call. Read .agents/skills/workflow-guide/SKILL.md before starting, then inspect the installed workflow and trigger declarations.
Report findings by severity. For every finding, include the file and line, production impact, and a concrete fix. Do not invent issues when the code is already safe.
Critical
- A file does not default-export
createWorkflow(...), is nested below src/workflows/, or relies on a key that differs from its filename.
- A trigger-specific event field is accessed without valid narrowing.
- A step result is not JSON-serializable or later code relies on an in-memory mutation that will be absent when the step replays.
- Step order can change between equivalent executions because of conditional calls, unstable iteration, or non-deterministic branching.
- Any non-deterministic operation occurs outside a step, whether its result can vary or its external effect depends on whether it runs. This includes relevant I/O, mutable external state, current time, randomness, generated identifiers, messages, notifications, creates, updates, and action-style calls.
- Two steps can have the same name within one run. Repeated operations should include a stable entity ID or an index from a collection returned by an earlier step.
- A non-idempotent side effect can be duplicated on retry without a downstream idempotency key or equivalent guard.
- Errors from external requests are ignored or swallowed, causing failed work to be reported as successful.
- Credentials are hard-coded, committed, or logged.
Warnings
- A step is not awaited.
- A step name is vague, does not identify the operation, or derives an index from data that was not returned by an earlier step.
- A callback returns more data than later code needs, especially large or sensitive payloads.
- Required environment variables are read without a clear missing-configuration error.
- An HTTP response is consumed without checking
response.ok or an accepted status.
- Multiple triggers are declared but their paths do not share a cohesive behavior or are not exhaustively handled.
After the review, run npm run check and npm run build when dependencies are installed. Distinguish implementation findings from environment or dependency failures.
