Trigger-action maps

A trigger is an event the system can detect. Good triggers include:

• a new message enters a named inbox;
• a form submission receives an identifier;
• an invoice changes from draft to submitted;
• a scheduled time arrives;
• a monitored value crosses a threshold;
• a person clicks “prepare report.”

“When a customer needs help” is not directly observable. Translate it into an event, such as a new ticket or an unanswered reply older than four hours. Also define trigger boundaries. Does an edited form count as a new submission? Do forwarded emails qualify? What timezone governs the schedule?

Every event should have a stable identifier. Webhooks and queues may deliver the same event more than once. If the workflow cannot recognize an event it already processed, a retry might send duplicate messages, create duplicate records, or charge twice.

An action changes or produces something. “Use AI” is not an action. “Classify the message into one of six allowed categories and return supporting text spans” is.

Separate actions that are often compressed into one box:

1. read the source message;
2. extract required fields;
3. classify the request;
4. fetch the account record;
5. draft a proposed response;
6. validate policy constraints;
7. request approval;
8. send the approved response;
9. record delivery status.

Each separation reveals a contract. The account lookup needs an identifier. The draft needs verified facts. The policy check needs structured proposed actions, not just polished prose. Sending needs an approval record. Delivery confirmation needs the provider’s result.

Arrows alone are not enough. Label what moves between steps. For an order inquiry, useful state might include:

workflow_id
source_message_id
customer_id
order_id
request_category
evidence
proposed_response
approval_status
delivery_status
attempt_count

This state makes the workflow inspectable. It also prevents a dangerous habit: asking an AI model to infer facts that another system already knows. If shipping status comes from the order database, store the retrieved status and its timestamp. Do not let the model invent or silently reinterpret it.

Distinguish workflow state from source-of-truth business data. A workflow can record that it proposed an address change, but the customer database remains authoritative for the current address. This distinction matters during retries and recovery.

Every decision diamond should have explicit outcomes. Instead of “valid?”, write the rules:

• required fields present → continue;
• required field missing → request information;
• conflicting identifiers → human queue;
• unsupported file type → safe rejection;
• policy-prohibited request → specialist escalation.

Name who owns each branch. “Manual review” is incomplete if no queue, service-level target, or responsible role exists. A fallback that no one checks is a silent failure.

Add stop conditions too. A workflow should know when it is complete, cancelled, expired, or awaiting information. Without terminal states, old runs can remain ambiguous and later resume unexpectedly.

For each external dependency, ask:

• What if it times out?
• What if it returns malformed data?
• What if it succeeds but the acknowledgment is lost?
• Is retry safe?
• How many attempts are allowed?
• Where does exhausted work go?

Suppose the final action posts a summary to a team channel. If the first call succeeds but the connection closes before confirmation, a naive retry posts twice. The workflow needs an idempotency key or a check for an existing post. “Retry three times” is not a recovery design unless duplicate effects are controlled.

The map should also include stale data. A price fetched ten minutes before approval may no longer be valid. Attach timestamps or versions and decide when a step must refresh its inputs.

Write each node in this form:

Step name
Input: exact fields and source
Operation: rule, model task, human decision, or external action
Output: structured result
On success: next state
On uncertainty: fallback branch
On technical failure: retry, pause, or escalation
Owner: responsible system or role
Evidence: what is logged

This template is deliberately technology-neutral. A spreadsheet, automation platform, or custom service can implement it. Choosing software after mapping the process prevents product features from dictating business logic.

For a weekly meeting digest:

1. A scheduler emits digest_due with a week identifier.
2. Code fetches meetings from the approved calendar range.
3. A deterministic filter removes private and cancelled events.
4. AI groups remaining titles into themes and drafts a summary.
5. Schema validation confirms every cited meeting ID exists.
6. A coordinator reviews the draft.
7. The system posts the approved text with the week ID as an idempotency key.
8. Posting success or failure is recorded.

If calendar access fails, the workflow does not ask AI to guess the week. It pauses and alerts the owner. If no meetings qualify, it ends as no_content, not as an error. If the reviewer rejects the draft, it stores the reason and ends or returns for revision according to policy.