I Built Salesforce Flow Sense: A Smarter Way to Debug Flows

The Question I Keep Hearing

"Why does my Flow keep failing on the same record type?"

I have lost count of how many times I have heard that exact question. The Flow looks correct on the canvas. Debug Mode passes. The user is sure the data is fine. But the moment the Flow runs in production on a real record, it falls over.

The frustrating part is what comes next. You ask an AI assistant to help, and it cheerfully proposes a one-line fix — add a null check, widen the field, wrap it in a try/catch. The fix patches the symptom. The next failure rotates to a different record. You are back to square one.

I built Salesforce Flow Sense to break that loop.

The pattern I kept seeing

Most Flow failures I walk into are not Flow bugs. They are upstream problems wearing a Flow mask.

A "null collection variable" inside a loop is usually a Get Records that returned empty because of a sharing rule the developer did not know about. A STRING_TOO_LONG exception sometimes turns out to be a spam bot filling a field with garbage that no field-widening will solve. A record-triggered Flow that "stopped firing" is often firing — silently failing because the fault path was never built and the error went nowhere.

There is also the bulkification trap. The "No Pink in Loops" rule is non-negotiable, and yet a fresh AI suggestion will happily nest a Create Records element inside a loop because the logic "reads more naturally that way." It works for one record. It breaks the moment a list view update touches two hundred.

The literal error message is rarely the actual problem. And generic AI assistants, given the literal error message, tend to propose literal fixes.

That is the gap. The fix is correct for the wrong problem.

What Flow Sense Is

Flow Sense is a Claude Code plugin. It gives Claude a curated catalog of common Salesforce Flow, Apex, and deployment gotchas to cross-reference before proposing fixes.

The plugin activates automatically when you start working on a Salesforce task. You do not have to remember to invoke it. When the assistant encounters a symptom that looks familiar, it checks the catalog first, names the underlying pattern, and proposes a diagnosis-first response rather than a patch. If you want to call it explicitly, the command is /salesforce-flow-sense:gotcha-lookup.

The core principle is one line: diagnose root cause, not literal error.

The Catalog Itself

v0.1.0 ships with seventeen seed entries covering Flow and Apex. Each entry has a stable reference ID — entry one is always entry one. That number does not move when the catalog grows.

That detail matters more than it sounds. When a team can point at the same numbered entry in a code review or a ticket, the reference holds across sessions and across people. The catalog becomes a shared vocabulary instead of a fresh explanation every time.

Entries follow a fixed structure: what the symptom looks like, what the underlying cause usually is, and how to prevent it. No hand-wavy advice. If the prevention is not concrete, the entry does not make it into the catalog. That gate is deliberate. A vague entry is worse than no entry, because it gives the team something authoritative-looking to point at instead of doing the actual work.

How It Changes the Debugging Conversation

Same symptom, two very different responses:

| Without Flow Sense | With Flow Sense |
| --- | --- |
| "Add a null check on the collection variable" | "Inspect why the Get Records returned empty before assuming the data is at fault — often a sharing issue" |
| "Widen the field to handle the longer value" | "Look at what is actually writing the long value — a spam pattern is more likely than a real business need" |
| Patches the symptom in one place | Names the upstream pattern so the next instance is also covered |
| Each conversation starts fresh | Stable references the team can cite in a PR or runbook |
| Confidence comes from a fluent answer | Confidence comes from a catalog entry the answer is grounded in |

The fluent-answer trap is real. A confident, well-written suggestion that happens to be wrong is harder to push back on than an obviously confused one. The catalog gives the assistant a reason to slow down before being confident.

What Has Not Changed

Flow Sense is not magic. A few honest limitations.

Seventeen entries is a starting set, not coverage. A genuinely novel Flow bug — the kind you would email a Salesforce MVP about — will not be in the catalog yet. The plugin will still reason from first principles in that case, the same as any debugging session without it.

Complex orchestration bugs that span multiple Flows, triggers, and integrations still need a human to map the call graph. The catalog can flag patterns inside one Flow. It cannot tell you that your record-triggered Flow is being recursed by a Process Builder you forgot about.

And none of this replaces proper test coverage. If your Flows do not have test data that exercises the unhappy paths, no plugin is going to save you from the production incident.

How to Use It Right Now

Four steps to get started.

1. Install the plugin. From inside Claude Code, run /plugin marketplace add shantanudutta1/salesforce-flow-sense followed by /plugin install salesforce-flow-sense. If you are working from a local clone for development, point Claude Code at the directory with claude --plugin-dir /path/to/salesforce-flow-sense.

2. Point it at a real problem. Pick a Flow you have actually been debugging — not a synthetic example. Describe the symptom in plain English ("this record-triggered Flow on Opportunity is not firing on update"). Let the plugin decide whether the symptom matches a known pattern.

3. Read the diagnosis before the fix. When the response cites a catalog entry, read the entry. The point of the plugin is that the named pattern teaches you something about your org. The fix is downstream of the diagnosis, not the other way around.

4. Send back the next gotcha. When you hit a gotcha that is not in the catalog and feels like it should be, open a GitHub Issue on the repo using the What happened / Root cause / Prevention structure. The catalog only stays useful if it grows with the community.

What Is Coming Next

v0.2.0 is in design. The plan is a scheduled weekly routine that drafts candidate entries from Salesforce Known Issues, MVP blogs like Automation Champion and UnofficialSF, Stack Exchange, Reddit, and the Trailblazer Community. Candidates pass through a quality gate and then an adversarial reviewer before they are posted as GitHub Issues for manual review. The routine never writes to the catalog directly. Curation stays human.

v0.3.0 expands the catalog into deployment pitfalls and Tooling API pitfalls — two areas where I have seen the most consistent pain in real engagements — and adds a topic index so duplicate entries get caught before they ship.

The license is MIT. Fork it, run it inside your own team's setup, send a pull request. The catalog is more useful with more eyes on it.

Stuck on a Flow gotcha that should be in the catalog? Let's talk — I am collecting the next batch.