# Temporal Workflow Design Critic

> 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.

- Skill: `temporalio/temporal-workflow-design-critic` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add temporalio/temporal-workflow-design-critic`
- Raw SKILL.md: https://api.skillmd.com/api/skills/temporalio/temporal-workflow-design-critic/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: temporalio (https://skillmd.com/u/temporalio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/temporalio/temporal-workflow-design-critic

---


# 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:

1. correctness
2. operability
3. 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:

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

## Reference materials

For detailed guidance during review, consult these supporting files:

- [rubric.md](references/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](references/checklist.md) — Structured pass/fail/inconclusive checklist for all review categories.
- [decision-guide.md](references/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:

```md
# 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