Writing a Flow description AI can actually follow

You paste “my Flow isn’t working” into an AI chat tool and get back generic Salesforce advice, none of it about your Flow. That’s not the tool failing. It never saw your Flow. It saw one sentence about it.

A screenshot doesn’t fully fix this either. It shows shapes and labels, not the condition inside a Decision element or what a formula actually evaluates. The fix is writing the logic down in words, once, in an order AI can reason about.

---

Why the screenshot isn’t enough

A Flow canvas is a diagram of sequence. The parts that actually decide what happens, the filter on a Get Records, the formula in a Decision, the exact field a Assignment element changes, live inside each element, not on its face. AI reading a screenshot sees boxes and arrows and has to guess at what’s inside them. It guesses fluently, which is worse than guessing badly, because fluent wrong answers don’t look wrong.

Writing the logic out forces you to open every element anyway, which is usually where you notice the actual bug before you’ve even asked a question.

---

Step 1: name the trigger and the object, first

Before anything else, write the two facts a Flow can’t function without.

Flow name: [whatever it's called]
Object: [the record this runs against]
Trigger: [record-triggered on create / on update / on create or update, scheduled, or run from a screen/button]
Run context: [before-save or after-save, if record-triggered]

Before-save and after-save Flows on the same object can look identical in the builder and behave completely differently, one can edit the record directly and cheaply, the other has to make a second save. Getting this wrong at the top means everything that follows is describing the wrong thing.

---

Step 2: describe each element as a sentence, in order

Walk the canvas top to bottom. For every element, write one line: what kind it is, and what it actually does. Not what it’s named, what it does. A Decision called “Check Status” tells AI nothing; the condition inside it does.

1. [Decision] If Stage = "Closed Won" AND Amount > 50000, go to path A, else path B
2. [Get Records] Path A: fetch related Contact records where Role = "Approver"
3. [Assignment] Path B: set Discount_Approved__c to false
4. [Loop] For each Contact from step 2, check Email_Opt_Out__c
...

If a Decision has more than two outcomes, write all of them, not just the one you think is broken. If a formula field is involved, paste the formula itself, not a description of what you assume it does.

---

Step 3: name what you already suspect

Say where you think the problem is, and why, before asking for help. This does two things: it stops the answer from re-explaining Flow basics you already know, and it gives the model something concrete to argue with, the same way stating an instinct helps in a written spec.

What I think is happening: [your best guess]
What makes me think that: [the evidence, e.g. "the discount field is blank on records that should qualify"]
What I've already ruled out: [anything you've checked and confirmed is fine]

---

Step 4: ask for the specific thing you need

Paste steps 1 through 3 together and ask for exactly one of these, not all three at once.

Given the Flow described above:
1. Where is the logic most likely to produce [the symptom]? Point to the specific element and step number.
2. Rewrite this as a plain-English description a non-technical stakeholder could read
3. What test records would exercise every path, including the ones nobody expects to hit?

Asking for one at a time keeps the answer anchored to your actual Flow instead of drifting into a general Flow-building explainer.

---

When it breaks

It suggests a fix using an element type your org doesn’t have access to, or a feature from a different Salesforce edition. Confirm any suggested element exists in your edition before building it. Recent platform features are the least reliable ground here, the same as with any Salesforce question.

It’s confidently wrong about what a formula evaluates to. Formula logic, especially with nested IF or CASE statements, is exactly the kind of thing that sounds authoritative and is still wrong. Test the formula in a sandbox with a record you can predict the outcome for, don’t trust the read.

The Flow is too long to describe in one pass. Break it at each Subflow boundary or major branch, and describe one chunk at a time. A Flow you can’t summarize in a page probably has a real complexity problem worth raising on its own.

It proposes rebuilding the whole Flow instead of finding the one broken step. That’s usually a sign your step 3 wasn’t specific enough about what you’d already ruled out. Add more of what you’ve confirmed works, and ask again.

You wrote the description and found the bug yourself before asking anything. That’s not a failure of the method, that’s the method working. Fix it and keep the write-up. The next person who inherits this Flow gets the documentation you just wrote for free.

---

What to try next

Keep the plain-English version from step 4 with the Flow itself, in a description field or a linked doc. The next person to touch it, possibly you in eight months, inherits a Flow that explains itself instead of one that has to be re-read from scratch.