Rubric v1.0 · updated 2026-06-08
Methodology
Flow Doctor is a heuristic linter. It parses your flow YAML in the browser, walks the task tree, and checks it against the failure modes that Kestra users repeatedly hit in production. Each rule is grounded in a public artifact: most map to a real Kestra GitHub issue (the numbers below link straight to them); the Kestra 2.0 · AI rules map to Kestra's stated direction on native agent orchestration rather than a legacy issue number — flagged as such, never dressed up as a fabricated issue. This is an outside-in tool built from public sources; the value is in catching the obvious-in-hindsight gaps before you deploy, not in replacing your own judgement or usage data.
The five dimensions
| Dimension | Max | What it asks |
|---|---|---|
| Failure handling | 25 | Will a transient error take the whole run down? Checks retry coverage on fallible tasks, flow-level error handling, and a flow timeout. |
| Observability readiness | 20 | When this flow fails, will you be able to see why? Flags loop/subflow patterns whose failures surface poorly today, and fragile expression access. |
| Scale risk | 20 | Will this hold up under load? Flags high-frequency triggers paired with heavy work (worker-memory risk) and sequential-backfill exposure. |
| Guardrails | 20 | Can a single execution run away or stampede? Checks per-task timeouts on long-running work and flow concurrency limits on triggered flows. |
| YAML hygiene | 15 | Is the YAML itself a trap? Detects zero-width/invisible characters, tab indentation, and structural issues that silently break flows. |
Every rule, and the issue it maps to
| Dimension | Rule | Kestra issue |
|---|---|---|
| Failure handling | I/O task (HTTP, script, query, cloud) has no `retry` policy | #1246 |
| Failure handling | Flow has fallible tasks but no top-level `errors` block | #1246 |
| Failure handling | No `finally` block for guaranteed teardown | #1246 |
| Failure handling | AI / agent task has no retry — providers rate-limit and 5xx constantly | Kestra 2.0 · AI |
| Observability | ForEach / ForEachItem loop — sub-execution failures surface empty logs/Gantt today | #13115, #16495 |
| Observability | Subflow task — child logs may not bubble to the parent on failure | #13115 |
| Observability | Fragile field access on `taskrun.value` / loop values | #16373 |
| Scale risk | High-frequency schedule (sub-5-min cron) driving heavy work — worker-memory growth | #13129, #6129 |
| Scale risk | Realtime / streaming trigger (Debezium, Kafka) — JVM heap pressure under load | #6129, #13129 |
| Scale risk | Scheduled flow — backfills run sequentially, not in parallel | #2041 |
| Scale risk | AI / agent task fans out inside a loop with no concurrency cap — cost + rate-limit stampede | Kestra 2.0 · AI |
| Guardrails | Long-running task has no `timeout` — a hung step blocks a worker | #1493 |
| Guardrails | Triggered flow has no `concurrency` limit — overlapping-execution stampede | #1493 |
| Guardrails | AI / agent task has no timeout — a hung or looping call burns tokens indefinitely | Kestra 2.0 · AI |
| Guardrails | Note: Kestra has no flow-level timeout yet — enforce per-task | #1493 |
| YAML hygiene | Invisible / zero-width character silently breaks parsing | #13079 |
| YAML hygiene | Tab used for indentation (illegal in YAML) | #13079 |
How scoring works
Each dimension starts at full marks. Every finding subtracts a penalty weighted by severity (critical > warning > note), capped so one noisy pattern can't drive a dimension below zero. The total is the sum of the five dimensions, out of 100:
- 80–100 · Production-ready — Resilient to the failure modes Kestra users most commonly hit.
- 50–79 · Fragile — Will run, but has gaps that bite on the first bad day in production.
- 0–49 · High risk — Likely to fail in ways that are hard to debug. Fix before you deploy.
If the YAML fails to parse, structural dimensions are withheld (scored 0) rather than shown as passing — a broken flow should never read as "reliable."
What it deliberately does not do
- It doesn't connect to your Kestra instance, account, or execution history.
- It doesn't validate plugin-specific properties or run the flow.
- It doesn't claim completeness — v1 ships the highest-frequency failure modes. The roadmap is a
kestra flow doctorCLI, a CI gate, and an in-editor lint.
Built by Roman Martins. Independent and unofficial — not affiliated with Kestra.