temporal-workflow-design-critic - SKILL.md Agent Skill

name: temporal-workflow-design-critic description: Critique, audit, or score a Temporal workflow design for correctness, production readiness, and best-practice compliance. Use when asked to review a Temporal architecture, evaluate whether a design is production ready, identify anti-patterns or risks, assess Temporal fitness for a use case, or give a design a thumbs up/down. Not for writing or debugging Temporal code — use temporal-developer for that.

Temporal Workflow Design Critic

Use this skill to review a Temporal workflow design, spec, architecture document, implementation plan, pseudocode, workflow code, or code-generation output.

This skill is for critique and review, not implementation.

What this skill does

This skill helps you:

determine whether a use case is a good fit for Temporal
inspect usage of Temporal primitives
identify determinism, retry, timeout, event-history, signal-volume, and payload-size risks
detect anti-patterns and missing design decisions
evaluate production readiness
give concrete remediation guidance
produce consistent review output across designs

When to use this skill

Use this skill when the user asks you to:

review a Temporal workflow design
critique a Temporal architecture or implementation plan
evaluate workflow code or pseudocode against best practices
assess whether a design is production ready
identify risks, anti-patterns, or missing decisions in a Temporal-based design
score or checklist a Temporal design

Do not use this skill for:

deep debugging of a live production incident
replacing SDK documentation
writing the full implementation unless the user explicitly asks for that
deciding product strategy unrelated to Temporal workflow design

Primary review goal

Prioritize:

correctness
operability
production readiness

Do not demand perfection. Accept reasonable tradeoffs, but clearly flag risks, anti-patterns, and missing information.

Expected inputs

This skill works best when the user provides some combination of:

deployment model (Temporal Cloud or self-hosted)
use-case description
workflow diagram
workflow code or pseudocode
Temporal UI execution history
activity definitions
signal, query, or update usage
timeout and retry settings
task queue and worker topology
expected scale, volume, and duration

If important inputs are missing, explicitly call that out and mark affected checks as inconclusive.

Review method

When reviewing a design, follow this sequence:

Decide whether the use case is actually a good fit for Temporal.
Inspect workflow-level correctness and determinism.
Evaluate use of Temporal primitives.
Check event-history growth, payload size, and long-running execution strategy.
Inspect retries, timeouts, idempotency, and cancellation behavior.
Evaluate worker topology, task queues, and routing choices.
Check visibility, versioning, and replay safety.
Return a structured critique with severity-ranked findings and actionable fixes.

Reference materials

For detailed guidance during review, consult these supporting files:

rubric.md — Complete review rubric covering Temporal fit, workflows, child workflows, activities, signals, queries, updates, workers, timers, side effects, data converters, visibility, versioning, Continue-As-New, sessions, and storage optimization (sections 1-16).
checklist.md — Structured pass/fail/inconclusive checklist for all review categories.
decision-guide.md — Verdict rubric (approve, approve with changes, needs revision, high risk), open questions template, and optional structured JSON output format.

Output contract

Always return results in this structure:

# Workflow Design Critique

## Verdict
- status: approve | approve_with_changes | needs_revision | high_risk
- summary: <1-3 paragraph summary>

## Top Issues
1. [severity] <issue title>
   - why it matters
   - evidence from design
   - recommended fix

## Category Review
### Temporal fit
### Workflows
### Child Workflows
### Activities
### Signals
### Queries
### Updates
### Workers and Task Queues
### Timers / Schedules / Cron
### Data / Payloads / Converters
### Visibility
### Versioning
### Long-running execution

## Open Questions
- <question>

## Checklist Result
- pass/fail/inconclusive per item

Severity levels

Use only these severity levels:

critical — likely to fail, become non-deterministic, exceed limits, or cause production incidents
high — serious design problem likely to impair correctness, scale, or operability
medium — suboptimal design likely to cause friction, cost, or maintenance issues
low — improvement opportunity or missing optimization
info — observation or tradeoff explanation

Default judgments

Apply these defaults unless the design clearly justifies otherwise.

Local activity vs regular activity

Default to regular activities.

Use local activities only when very short execution and high-throughput fan-out justify them.

Child workflow vs activity

Default to activity.

Use child workflows only when partitioning, lifecycle isolation, or routing semantics justify them.

Workflow-to-workflow communication

Acceptable options include:

signals
queries
updates
Nexus where applicable
activity-mediated client calls for cross-namespace interaction where needed

Large payload handling

Prefer:

passing references
moving data-heavy work into activities
compression
explicit handling over hidden remote payload fetches

Large workflow history

Prefer:

Continue-As-New
partitioning with child workflows where justified
reducing per-event data size and message volume

Parallelism

Parallel execution should use async invocation patterns with promise or future collection and later aggregation.

Worker-specific activity queues

Use when capabilities, locality, security, or rate control justify them.

Schedule vs timer

Use timers for relative delays inside workflows.

Use schedules for calendar-based or recurring launches.

Reviewer operating style

When using this skill:

be specific, practical, and conservative
do not assume missing details are safe
distinguish between blocking issues and reasonable tradeoffs
provide concrete remediation guidance, not vague advice
clearly separate evidence, risk, and recommendation
mark missing-information areas as inconclusive instead of guessing

Anti-pattern catalog

Explicitly call out the following when present.

Critical anti-patterns

non-deterministic workflow logic
workflow logic depending directly on external mutable state
passing large data blobs through workflow history
activity side effects without idempotency
signal floods against a single workflow
search attributes used as business-state storage
workflow retry policy used to compensate for transient activity failures

High-risk anti-patterns

child workflows used purely for code organization
local activities used for long or failure-prone work
schedules used for one-time delayed starts without need
cron used where schedules should be used
missing Continue-As-New strategy in high-volume or long-running workflows
no replay or versioning strategy

Medium-risk anti-patterns

identical timeout policies for all activities
over-fragmented activities causing event-history bloat
memo or visibility data assumed to be strongly consistent
arbitrary task queue splitting

Maintainer note

Keep this skill:

stable enough for repeatable agent use
readable by humans
extensible as Temporal features evolve
opinionated toward production safety

When updating, preserve:

explicit rules
default recommendations
anti-pattern detection
structured output expectations
practical review questions