workflow-design

Files (25)

• CHANGELOG.md
• LICENSE
• PUBLISHING.md
• README.md
• SKILL.md
• EVALS.md · evals/
• broken.flow.json · evals/fixtures/
• scenarios.json · evals/
• intake.flow.json · examples/
• ai-gates.md · references/
• dynamics.md · references/
• engines.md · references/
• evolving.md · references/
• human-flows.md · references/
• modeling.md · references/
• proving.md · references/
• slas.md · references/
• conformance.py · scripts/
• conformance.selfproof.spec.json · scripts/
• dynamics.py · scripts/
• dynamics.selfproof.spec.json · scripts/
• flowcheck.py · scripts/
• flowcheck.selfproof.spec.json · scripts/
• redproof.py · scripts/
• selfproof.spec.json · scripts/

SKILL.md (first lines)

# Workflow design, proof, and dynamics

A workflow is anything an item moves through: intake → review → approval → fulfillment,
draft → edit → publish, ticket → triage → assignment → close. It has **stations** (where an
item waits), **gates** (where a decision is made), and **transitions** (how it moves).

## Which phase am I in?

Route by the situation, not by curiosity — read only the reference the task needs:

- **Designing a flow, adding a status field, or reviewing a data model** → Phase 1.
- **Auditing tests, a green suite that shipped a bug, "do these tests protect anything?"** → Phase 2.
- **"Where do items get stuck?", "is this approval step worth it?", reading an event log** → Phase 3.
- **The flow's definition is changing while items are in flight** → Phase 4 (and capture
  the Phase 3 baseline *first*).

And four contexts that change *where* the rules land, not the rules — read alongside the
phase you are in:

- **No code at all** — the flow runs on spreadsheets, forms, or paper →
  [references/human-flows.md](references/human-flows.md) (the log is a sheet; the CSV
  bridge feeds `dynamics.py` unchanged).
- **A human gate reviews AI/agent output** — drafts, classifications, proposed actions →
  [references/ai-gates.md](references/ai-gates.md) (the agent is an actor, never a
  decider; rubber-stamp detection; a prompt change is a flow change).
- **Time promises** — SLAs, deadlines, reminders, escalation →
  [references/slas.md](references/slas.md) (an SLA needs an execution point; deadlines
  stored, not recomputed; set bounds from measured p90).
- **Choosing the substrate** — hand-rolled tables vs a workflow engine →
  [references/engines.md](references/engines.md) (engines orchestrate code, these flows
  orchestrate decisions; the hybrid; keep your own log either way).

Four phases, in order. Skipping phase 1 makes phase 3 impossible — the metrics that tell you
where a flow is stuck can only be computed from a transition log that was designed to support
them. Phase 4 is where flows that survived the first three break anyway.

| Phase | Question | Read | Run |
|---|---|---|---|
| **1. Model** | What are the states, who may move an item, what is recorded? | [references/modeling.md](references/modeling.md) | `flowcheck.py my-flow.json` |
| **2. Prove** | Do the tests guarding this flow actually catch anything? | [references/proving.md](references/proving.md) | `redproof.py spec.json` |
| **3. Measure** | Where does the flow stall, and which gate is theater? | [references/dynamics.md](references/dynamics.md) | `dynamics.py --db app.sqlite` |
| **4. Change** | How do you move a flow that is full of in-flight items? | [references/evolving.md](references/evolving.md) | (checklist) |

For a full engagement (new flow, end to end), copy this checklist and check items off as
you go:

```
Workflow progress:
- [ ] Model drafted as a flow JSON; flowcheck.py exits 0
- [ ] Transition log designed (actor_kind on every row, enumerated reason codes)
- [ ] Guards implemented; every guard has an assertion
- [ ] redproof spec written; every guard went red and was restored
- [ ] Anything visible opened in a real client
- [ ] Metrics run once on real or fixture data; refusals fixed at the log, not the metric
- [ ] Before any later definition change: phase-3 baseline captured
```

## The tools

Four stdlib-only Python scripts. Each has `--selftest`, and each is red-proofed by a shipped
spec — including the red-prover itself.

| Tool | What it does |
|---|---|
| [`scripts/flowcheck.py`](scripts/flowcheck.py) | Lints a flow definition: unreachable states, dead ends, gates with no rejection destination, rejections with no enumerated reason, automatic transitions wearing a human decision's name. Suppression only via a reasoned `allow` list, and an `allow` entry that suppresses nothing is itself reported. |
| [`scripts/redproof.py`](scripts/redproof.py) | Proves both sides of every guard: removes it and requires your suite to go **red**, then runs it in place against a **known-good artifact** and requires it to pass (catching guards that reject everything). Where a guard checks an agreement, it forces **both halves to be read from the built artifact** and refuses an assumed side. Restores files byte-for-byte. |
| [`scripts/dynamics.py`](scripts/dynamics.py) | Computes the metrics below (plus the top real paths items take) from a SQLite transition log. Refuses any metric the log cannot support instead of printing a confident wrong number. |
| [`scripts/conformance.py`](scripts/conformance.py) | Holds the real log against the declared flow model, both directions: observed transitions the model forbids (off-model moves, broken per-item chains, exits from terminal states, auto passes recorded as human, undeclared rejection reasons) and declared edges nobody has ever taken. Reports per-item **trace fitness**. No allowlist on purpose: a violation means the model file or the code is wrong, and the model file is cheap to fix. |

```bash
python scripts/flowcheck.py --selftest && python scripts/redproof.py --selftest && python scripts/dynamics.py --selftest && python scripts/conformance.py --selftest
```

The model you lint in phase 1 is not documentation that rots — `conformance.py` turns it
into an executable claim about production: `--db app.sqlite --flow my-flow.json`. Run it
whenever the log and the model might have drifted, and after any phase-4 change.

Each tool is a feedback loop, not a one-shot check: run it, fix what it reports, run it
again, and only move on at exit 0. For `flowcheck`, fix the model (or add a *reasoned*
`allow` entry) — never delete the rule. For `redproof`, a guard that stays green means fixing
the **assertion or the fixture**, not the spec. For `dynamics`, a refused metric means fixing
the **log**, not computing the number another way.

[`examples/intake.flow.json`](examples/intake.flow.json) is a worked flow that passes
`flowcheck` cleanly — the fastest way to see the modeling rules as a concrete object.

Every rule below came from a flow that shipped and then failed in a specific way. They are
stack-independent: the examples may be SQL or shell, but no rule depends on a language,
a database, or a framework.

---

## Phase 1 — Model

**One current value plus an append-only history. Never two competing fields.**
`status` and `is_approved` will diverge. The one that a screen reads and the one that a
guard reads will not be the same one. Keep a single current state, and a separate
transition log that only ever gets rows appended.

**Every transition is an event with a name, an actor, and a timestamp.**
"Who moved this and when" is not an audit luxury — it is the raw material of phase 3.
Without an actor on every row, you cannot compute a single dynamics metric.

**Never name an automatic state after a human decision.**
If nobody looked at it, it is not `approved`; it is `auto_passed` or `skipped`. The moment
the two share a name, the most valuable metric you have — *what fraction of this gate is
actually a human decision* — becomes uncomputable, and every audit that reads the log lies.

**Store what you route on; never recompute it at read time.**
If an item is routed to a queue based on a lookup (category → team), write the resolved key
onto the item at the moment of the transition. Recomputing at read time means the next edit
to the lookup table silently rewrites history: last month's items appear to have been routed
somewhere they never went.

**Two labels that change on different clocks are two fields, not one enum.**
If A almost never changes after intake and B changes several times a day, an enum of their
cross-product loses transitions: you cannot tell "B changed" from "A was wrong". Split the
axes, and the state machine shrinks.

From ghorbanies/workflow-design, MIT.