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

Temporal Design Skill

Give your AI coding agent the ability to review Temporal workflow designs. Point it at a design doc, architecture spec, pseudocode, or workflow code and get a structured critique covering correctness, production readiness, and best-practice compliance.

[!WARNING]

This Skill is currently in Public Preview, and will continue to evolve and improve.

We would love to hear your feedback - positive or negative - over in the Community Slack, in the #topic-ai channel

What It Reviews

• Whether a use case is a good fit for Temporal
• Workflow-level correctness and determinism
• Anti-patterns, retry/timeout/payload risks, and missing design decisions
• Production readiness of a Temporal architecture
• Worker topology, task queues, and routing choices
• Versioning, visibility, and replay safety

Each review produces a structured verdict (approve / approve with changes / needs revision / high risk) with severity-ranked findings and actionable fixes.

Installation

Via manual clone (user-level)

Cloning into ~/.claude/skills/ makes the skill available across all sessions and projects for your user.

mkdir -p ~/.claude/skills && git clone https://github.com/temporalio/skill-temporal-design ~/.claude/skills/temporal-design

Via CLI flag (per-session)

claude --plugin-dir /path/to/skill-temporal-design

This loads the skill for a single session without permanently installing it.

Review checklist

Score each item as one of:

• pass
• fail
• inconclusive
• not_applicable

Workflows

• Workflow use case is appropriate for Temporal
• Workflow logic is deterministic
• Replay/versioning concerns are addressed
• Event history growth is managed
• Workflow ID strategy is intentional
• Workflow timeouts are not misused
• Workflow failure semantics are understood
• Workflow retry policy is not added without strong reason

Child Workflows

• Child workflows are used only where justified
• Parent does not start an excessive number of children
• Parent close policy is intentional
• Parent/child communication model is explicit

Activities

• Activities are idempotent
• Activity granularity is appropriate
• Long-running activities heartbeat
• Payload sizes are safe
• Large data is passed by reference where possible
• Polling strategy is efficient
• Timeout settings are activity-specific
• Retry policy is intentional
• Cancellation handling is correct
• Local activities are justified

Signals

• Signals are used where runtime state change is needed
• Signal handlers are deterministic and idempotent
• Signal handlers avoid heavy work
• Signal volume is safe
• Continue-As-New compatibility is considered

Queries

• Queries are read-only
• Queries are used appropriately for state reads

Updates

• Updates are deterministic and idempotent
• Validation is used where appropriate
• Update-handler behavior is well scoped

Workers and Task Queues

• Worker count supports high availability
• Registrations are consistent per task queue
• Task queue strategy is intentional
• Rate limiting is considered
• Ordering assumptions are valid

Timers / Schedules / Cron

• Timers are used appropriately
• Schedule usage is justified
• Overlap policy is intentional
• Jitter/backfill considerations are addressed
• Cron is avoided unless specifically required

Data / Visibility

• Data converter choices are intentional
• Compression/encryption concerns are handled
• Datetime cross-language serialization is addressed
• Search attributes are used only for visibility
• Sensitive data is not stored in search attributes
• Eventual consistency is understood for memos/visibility

Versioning / Long-running execution

• Replay-safe versioning strategy exists
• Patches have a cleanup plan
• Continue-As-New strategy exists where needed
• Timer and state carry-forward behavior is handled

Decision rubric

Approve

Use when the design:

• follows Temporal fundamentals correctly
• shows awareness of determinism, idempotency, history growth, and failure handling
• has no critical or high-severity flaws

Approve with changes

Use when the design is broadly sound but has:

• several medium-severity issues
• missing operational details
• review questions that should be resolved before production

Needs revision

Use when the design has:

• one or more high-severity issues
• unclear Temporal primitive selection
• insufficient handling of history, payload size, retries, or long-running behavior

High risk

Use when the design includes:

• critical non-determinism risks
• obvious misuse of Temporal as data plane
• major idempotency gaps
• unbounded history growth
• signal or payload patterns likely to fail in production

Open questions template

When the source material is incomplete, ask targeted questions such as:

• Is the target deployment Temporal Cloud or self-hosted?
• What is the expected peak workflow start rate?
• What is the longest expected workflow duration?
• How many activities and child workflows can occur per execution?
• What are the largest expected payload sizes?
• Are any activities side-effecting external systems?
• What is the retry and timeout policy per activity?
• How many signals or updates can one execution receive?
• Is Continue-As-New planned?
• Are there cross-namespace or cross-service workflow communications?
• Are search attributes used only for visibility?
• What is the versioning plan for workflow changes?

Optional structured output

Use this when the user asks for machine-readable output:

{
  "verdict": "approve_with_changes",
  "summary": "The design is broadly sound but has unresolved event history and signal-volume risks.",
  "issues": [
    {
      "severity": "high",
      "category": "Signals",
      "title": "Signal volume may block Continue-As-New",
      "why_it_matters": "High sustained signal rates can prevent workflow progress and cause history-limit failures.",
      "recommendation": "Aggregate signals, shard by workflow, or reduce per-workflow signal rate."
    }
  ],
  "checklist": {
    "workflow_determinism": "pass",
    "activity_idempotency": "pass",
    "history_management": "fail",
    "signal_safety": "fail",
    "versioning_strategy": "inconclusive"
  },
  "open_questions": [
    "What is the maximum sustained signal rate per workflow execution?"
  ]
}

Review rubric

1. Temporal fit

Determine whether the use case is appropriate for Temporal.

Good fit indicators

• long-running, multi-step business process
• need for durable execution
• retries and failure recovery matter
• coordination across services matters
• human-in-the-loop or asynchronous progression exists
• waiting, timers, external callbacks, or approvals are required

Poor fit indicators

• extreme low-latency requirements where milliseconds matter
• simple synchronous read-only operations
• using Temporal as a data plane instead of a control plane
• pushing large data blobs through workflows unnecessarily

Flag the design if Temporal is used primarily for:

• direct query serving
• high-frequency micro-latency trading or similarly latency-critical paths
• bulk data transport instead of orchestration

Questions to ask

• What business process is being orchestrated?
• Where does Temporal fit in the architecture?
• What starts the workflow?
• How often does it run?
• How long does it run?
• Is Temporal being used only where durable orchestration is needed?

2. Workflow review

Check whether workflow definitions follow Temporal execution constraints and best practices.

Determinism

Workflows must be deterministic.

Flag:

• non-deterministic branching
• reliance on wall clock, random values, or mutable external state in workflow code
• use of run IDs for logic
• code changes that would break replay without versioning

Ask:

• Does the design acknowledge workflow replay?
• Are replay tests or replayer usage included?
• Is there a versioning plan for workflow evolution?

Event history awareness

Workflows must account for event history growth.

Flag:

• unbounded loops without Continue-As-New strategy
• too many signals, activities, child workflows, or updates in one execution
• repeated large payloads in history
• no partitioning strategy for long-running or high-volume workflows

Recommend:

• use Continue-As-New at or before warning levels
• partition work with child workflows where justified
• keep workflow state compact

Workflow ID usage

Verify:

• workflow IDs are meaningful business identifiers where appropriate
• uniqueness constraints are intentionally used as idempotency protection
• reuse policy is explicitly considered for closed workflows

Flag:

• frequent reuse of the same workflow ID
• logic based on run ID

Timeouts

Assume default workflow timeouts are usually correct unless the design justifies changes.

Flag:

• workflow execution or run timeouts set without clear reason
• workflow timeouts used instead of explicit timers for business deadlines
• workflow task timeout implications ignored when histories are large or converters are expensive

Recommend:

• use timers inside workflows to model business timeouts
• tune workflow task timeout only when justified

Failure semantics

Verify the design understands:

• non-Temporal failures fail workflow tasks and are retried
• workflow failures should not be used for transient operational issues
• workflow retry policies are generally not recommended

Flag:

• workflow retries added without strong justification
• assumptions that workflow exceptions behave like activity retries

3. Child workflow review

Default rule

When in doubt, prefer an activity over a child workflow.

Valid reasons to use child workflows

• partition large workloads to control event history growth
• isolate ownership boundaries
• route execution by task queue, trust boundary, or workload type
• model durable sub-processes with their own lifecycle

Weak reasons

• organizing code structure
• reducing cost
• replacing normal language modularity

Flag:

• child workflows used only for code organization
• too many child workflows started by one parent
• missing parent close policy reasoning
• assumptions that parent and child share local state

Guidance

• starting more than 1000 child workflows from one parent is a design smell
• starting hundreds may already create latency concerns
• parent-child state sharing must happen through signals or explicit communication

Questions to ask

• Why is this a child workflow instead of an activity?
• How many children can one parent start?
• Does the parent need the child result?
• What happens to children if the parent closes?

4. Activity review

Core principle

Activities must be idempotent and treated as at-least-once.

Idempotency

Flag:

• side-effecting activities without idempotency protection
• reliance on "this only runs once" assumptions
• lack of idempotency keys where external actions occur

Granularity

Evaluate whether activities are too broad or too granular.

Guidance:

• bundling multiple operations is acceptable if timeout and retry boundaries are intentional
• too much bundling reduces observability and makes retries too coarse
• too much fragmentation increases event history and orchestration complexity

Long-running activities

Verify:

• long-running activities heartbeat
• heartbeat timeout is short enough for timely failure detection
• heartbeat payload contains resumable progress where useful

Payload size

Flag:

• large inputs or outputs that risk payload limits
• designs that pass blobs instead of references
• repeated large payload serialization in workflow history

Recommend:

• pass references instead of full payloads
• move data-heavy handling into activities
• compress payloads through a converter where appropriate

Polling

Evaluate whether polling is designed efficiently.

Guidance:

• frequent polling should usually happen inside one activity loop
• infrequent polling can often use activity retries
• signals or async activity completion may be better than polling

Timeouts

Verify:

• each activity has intentionally chosen timeout settings
• Start-To-Close is usually set
• Schedule-To-Close is used intentionally
• Schedule-To-Start is usually unset unless needed for host-specific routing or queue-unavailability detection

Flag:

• identical timeout policies applied blindly to all activities
• server-side timeouts shorter than normal upstream completion time
• duplicate-action risk from retries ignored

Local activities

Prefer regular activities unless there is a specific need for:

• very high throughput
• very short-lived work
• large fan-out of short tasks

Flag local activities that:

• run longer than a few seconds
• are used without understanding tradeoffs
• require worker-side rate limiting or routing they cannot support well

Cancellation

Verify cancellable activities heartbeat, or otherwise use supported semantics correctly.

5. Signal review

Signals are appropriate when workflow state must change during execution.

Required understanding

Signals are:

• recorded in event history
• delivered with the next workflow task
• ordered per workflow execution
• subject to replay and determinism requirements

Flag:

• signal handlers that perform heavy logic
• signal handlers invoking activities directly without strong reason
• non-idempotent signal handlers
• signal rates too high for one workflow execution
• signal volume that risks history growth or blocks Continue-As-New

Best practice

Signal handlers should usually:

• update workflow state only
• avoid expensive computation
• let main workflow logic react afterward

Questions to ask

• What sends the signal?
• How often can it happen?
• Can duplicates occur?
• Is Continue-As-New required?
• Could the signal rate prevent it?

6. Query review

Queries are best for reading workflow state.

Rules

• queries are synchronous
• queries must be read-only
• queries are available for running and completed workflows, but require a worker on the task queue

Flag:

• queries that mutate workflow state
• external stores used for live workflow state when queries would be simpler
• assumptions that query data is always available without workers running

7. Update review

Updates are appropriate when callers need validated, synchronous workflow state changes.

Rules

• update handlers must be deterministic
• update handlers must be idempotent
• validation is recommended
• validators must not mutate workflow state
• rejected updates via validation are not written to history

Flag:

• update handlers that mutate state non-deterministically
• missing validation for business-critical mutations
• designs that ignore latency or handler contention

Guidance

Calling activities from update handlers is generally acceptable when justified and carefully designed.

If low latency matters, ask whether early-return patterns are needed.

8. Worker and task queue review

Check topology and routing for correctness, availability, and intent.

Best practices

• run at least two workers for high availability
• all workers on the same task queue must register identical workflows and activities that may be dispatched there

Unique task queues are justified for:

• rate limiting
• routing to special hardware such as GPUs
• worker-local filesystem or privileged environment access
• workload isolation or differentiated priority

Flag:

• arbitrary task queue splits that add complexity without routing value
• inconsistent registrations on one queue
• assumptions of strict FIFO ordering
• intentional backlog growth without understanding Temporal's consumption semantics

Rate limiting checks

Inspect whether:

• worker-side concurrency and rate limits are intentional
• server-side task queue activity limits are configured consistently

Note: server-side rate limiting is configured differently on Cloud (namespace settings via UI/tcld) vs self-hosted (dynamic config). Verify the design targets the correct mechanism.

Questions to ask

• Why are there multiple task queues?
• Are special hardware or trust-boundary requirements involved?
• Is ordering assumed?
• Is backlog growth acceptable?

9. Timers, schedules, and cron

Timers

Verify:

• timers are used for relative delays inside a workflow
• timer durations are at least one second when reliability matters

Schedules

Use schedules when:

• a whole workflow execution must start at a calendar time
• execution is recurring
• a scheduled launch is more appropriate than an internal timer

Use timers instead when:

• the delay is relative to workflow state
• the delay belongs inside an already running workflow
• schedule action-per-second limits would be exceeded

Flag:

• schedules used for single delayed starts when a normal workflow plus timer would be simpler
• overlap policy not considered
• jitter not considered when many schedules fire together
• risky backfill strategies

Cron

Generally recommend schedules instead of cron workflows.

Flag:

• cron used where schedules are better supported
• cron combined with unsafe Continue-As-New assumptions

10. Side effects

Use side effects carefully.

Guidance

• if the side effect can fail, prefer an activity
• side effects are not general-purpose integration hooks

Flag:

• side effects used for failure-prone work
• side effects treated like normal external integration steps

11. Data converter and payload codec review

Check whether serialization, compression, and encryption choices are safe and operationally sound.

Best practices

• compression is generally recommended
• encryption may justify a custom converter or codec
• key rotation must be considered if encryption is used
• search attributes are not protected by custom converters or codecs

Note: both Cloud and self-hosted support codec servers for decoding payloads in the UI and CLI. Cloud encrypts data at rest automatically with AES-256-GCM — custom encryption via a Payload Codec is for zero-trust requirements. Self-hosted has no automatic encryption at rest — you must implement a custom Payload Codec if encryption is needed.

Cross-language datetime/duration warning

Flag designs that:

• assume datetimes or durations serialize consistently across languages
• mix languages without a common converter format

Latency

Verify whether converter or codec latency:

• contributes to workflow task execution time
• risks workflow task timeout under large histories or high throughput

12. Visibility review

Search attributes

Verify search attributes are used only for operational visibility, not business logic.

Note: both Cloud and self-hosted support custom search attributes, but per-namespace limits differ. Cloud allows up to 40 Keyword attributes and 20 of most other types. Self-hosted with SQL (v1.20+) allows fewer per namespace (e.g., 10 Keyword, 3 of most others). Self-hosted with Elasticsearch has no per-namespace limits but is subject to Elasticsearch mapping limits. Verify limits against the target deployment.

Flag:

• sensitive data in search attributes
• search attributes used to drive workflow decisions
• large duplicate state stored there
• assumptions of immediate consistency

Memos and visibility APIs

Note:

• memos are eventually consistent
• visibility APIs are eventually consistent
• control flow must not depend on immediate freshness

13. Versioning review

Check whether workflow evolution is safe for replay and in-flight executions.

Best practices

• prefer worker versioning for short-running workflows where appropriate
• use workflow patch/versioning APIs when needed for replay compatibility
• do not let patches accumulate forever
• remove version markers only after in-flight execution and retention concerns are handled

Flag:

• workflow logic changing without replay-safe versioning
• patches with no retirement plan
• long-running workflows ignoring patch retention needs
• absent replayer-based testing

14. Continue-As-New and long-running workflows

Check whether long-lived workflows remain healthy over time.

Best practices

• use Continue-As-New before history becomes too large
• pass forward enough state to resume safely
• recalculate and re-establish timers after Continue-As-New
• ensure pending activities and handlers are resolved before Continue-As-New

Flag:

• timers assumed to carry over automatically
• child workflow behavior on parent close misunderstood
• signal or update handlers possibly still running during Continue-As-New
• missing state handoff design

15. Sessions and worker-specific routing

Sessions

Sessions are only available in Go.

Note:

• if a worker process dies, session-related activities may retry together
• sessions should be clearly justified

Worker-specific task queues

Approve these when used for:

• local files
• privileged environments
• specialized hardware
• sticky locality requirements

16. Storage optimization review

Check whether long-running workflows control storage growth and event-history cost.

Best practices

• keep payloads small
• use references for large objects
• use Continue-As-New strategically
• avoid unnecessary history growth through over-fragmentation or excessive messaging

Note: Cloud retention is configurable from 1-90 days (default 30) via UI or tcld. Self-hosted retention is set when creating or updating a namespace via CLI or SDK. Verify the retention period is appropriate for the workflow's expected duration and audit requirements.