🔄 The cycle in one sentence
Plan (aligns the what and the how) → Build (AI builds and validates) → Troubleshoot (you return the error with context) → Optimize (you improve it in layers). And around all of it: verify for real and make a backup before every change.
The cycle isn’t a straight line with an endpoint: after optimizing, you usually go back to debugging (did the change break something?) or even planning (did a new requirement come up?). That’s why it’s drawn as a loop — and the backup is what makes that loop safe.
Illustrative diagram — the cycle is a loop, not a queue. The coordinator (the AI) reads the error you send back and suggests a fix; optimizing often feeds back into debugging.
🗺️ Phase 1 — Plan
What it is
The alignment phase. In Plan Mode, the AI researches the right resources, asks clarifying questions (interval? columns? what counts as “urgent”?) and proposes a numbered plan for you to approve. You haven’t built anything yet — you’re defining what to build and how, at the stage when it’s cheapest to change your mind.
What is it?Clarifying questions — the questions the AI raises before building (output format, data source, edge cases). Answering them well is half the work.
Why learn
Skipping the plan is the #1 cause of rework: the AI builds one thing, you wanted another, and now there are nodes to redo. Aligning on the plan takes one conversation; aligning afterward costs a rebuild.
🎯 Goal: get an approvable plan before any build.
Entre em plan mode. Quero <descreva o resultado, ex.: "um workflow que monitora o Gmail por e-mails com 'urgente' no assunto e registra cada um numa planilha">. Antes de construir: 1. Pesquise os recursos/nós necessários. 2. Liste as perguntas de esclarecimento (colunas, ações extras, casos de exceção). 3. Apresente um plano numerado com a arquitetura e as credenciais que vou precisar. Não escreva nada até eu aprovar.
✅ How to verify: the response includes questions + a plan + the list of credentials. You answer, adjust the plan, and approve—only then does the build start.
Key concepts
Right resources.
Resolve questions first.
Numbered and approvable.
You give the “okay.”
🏗️ Phase 2 — Build
What it is
With the plan approved, the AI builds the workflow/project and validates itself what it can do (automatically fixes validation problems). In bypass permissions, it runs without asking for confirmation at every step. Remember: the output may vary between runs—don't compare them screen by screen.
Why learn
Watching the build early has two benefits: you learn how the system works and can interrupt fast if the AI goes off track — saving time and tokens. The bypass speeds things up, but you stop seeing each step; use it judiciously.
🎯 Goal: build what was approved and validate it before testing.
Aprovado. Construa exatamente o plano acima. Ao terminar: - Valide o que foi criado e corrija problemas de validação automaticamente. - Me diga claramente o que ainda preciso fazer à mão (credenciais, mapeamento, criar destinos). - Não considere "pronto" sem antes apontar o que falta para eu testar.
✅ How to verify: the build is assembled and validated; the AI lists what’s manual. You don’t try to test before knowing what still needs to be configured.
🎯 Practical tip
If your version has different names and layout from a tutorial, that’s fine: AI is non-deterministic. Judge by the final behavior, not by how each step looks.
Key concepts
AI self-corrects.
Without interrupting.
Stop if it fails.
Expected, not a defect.
🙅 What AI does NOT do
What it is
The boundary of automation. Some steps need you: create OAuth credentials (log in with your account), create the destination spreadsheet/folder, and map fields (say which value goes in which column). And the golden rule: key/secret never in chat — only in an environment file.
What is it?OAuth — the secure way to authorize an app to access your account (Gmail, Sheets) without giving it your password. Map fields — connect each input (sender, subject) to the correct column/output.
✓ The AI does
- ✓Choose and set up the nodes/files.
- ✓Validate and auto-correct what you can.
- ✓Suggest the columns and mapping.
- ✓Tell you exactly what’s left to do by hand.
✗ You do it (manually)
- ✗Create the OAuth credentials (sign in to the accounts).
- ✗Create the destination spreadsheet/folder.
- ✗Confirm the final mapping of the values.
- ✗Store the key in .env — never paste it into the chat.
Why learn
Without knowing where the boundary is, you end up waiting for AI to do what only you can do (authorize your own account)—or, worse, pasting a key into chat because you're impatient. Knowing the division speeds up the build and keeps secrets safe.
🎯 Goal: get a checklist of what must be done manually before testing.
Before I test, give me a checklist of what ONLY I can do: - Which OAuth credentials to create and in which nodes/services. - Which destinations I need to create (spreadsheet, folder) and which columns they should have. - How to map each input field to the output. For keys/secrets, tell me where to put them in the environment file—never ask me to paste a key here in the chat.
✅ How to verify: you get a clear list of manual actions. No instruction asks you to paste secrets into the chat.
Key concepts
You authorize.
Create a spreadsheet/folder.
Value → column.
Never in chat.
🔧 Phase 3 — Troubleshooting
What it is
When something breaks, the right instinct is to return the error with context: copy the entire message, say which node/step it happened in and what you expected, and ask for a diagnosis + cause + fix. The AI reads the inputs/outputs of each step and fixes it. Then you run it again—one fix at a time.
Illustrative diagram — reading the input, the step, and the expected output helps locate the error. The AI needs the exact message + where it occurred.
Why learn
"It errored" without context turns into guesswork. The exact message + where it happened + what you expected turn the problem into an actionable request — and AI often finds the real cause (a wrong model format, an invalid time expression, a field read with different capitalization) and fixes it quickly.
🎯 Goal: return the error in a way that lets the AI fix it on the first try.
Apareceu um erro. Aqui está o contexto completo: - Onde aconteceu: <nó/passo, ex.: "nó Google Sheets append"> - O que eu esperava: <ex.: "que a linha fosse adicionada na planilha"> - O que aconteceu: <descreva o sintoma> - Mensagem de erro (literal): """ <cole a mensagem de erro exatamente como apareceu> """ Diagnostique a causa, explique por que aconteceu e corrija. Não mude mais nada além do necessário para resolver isso.
✅ How to verify: the AI explains the cause and applies a focused fix. You reload/rerun; if it still fails, repeat the template with the new error.
Key concepts
Paste it exactly.
Which node/step.
Ask for the cause.
Without changing anything else.
⚡ Phase 4 — Optimize
What it is
Once the basics are working, “works” becomes “works well.” You improve it by layers, in order of priority: (1) error handling—what breaks; (2) logic—what's inefficient; (3) output quality—the experience (formatting, signature); (4) performance—speed from trigger to delivery. One change at a time, testing at each step.
What is it?Edge case — an unusual situation that could break the workflow (email without a signature, empty field, automated sender). Optimizing largely means covering these cases.
Why learn
Polishing the output before handling errors is a waste of time: a beautiful email is worthless if it never arrives. This priority order ensures you spend effort where the payoff is greatest—and making one change at a time keeps each problem easy to locate.
🎯 Goal: optimize one layer at a time, grounded in what already exists.
No workflow já existente chamado "<nome exato do workflow>", aplique UMA melhoria: <descreva a mudança, ex.: "quando a busca não achar uma política, em vez de inventar, envie uma resposta dizendo que vamos pesquisar e retornar">. Não crie um workflow novo — edite este. Me explique o que vai mudar antes de aplicar, e depois me diga como testar essa mudança especificamente.
✅ How to verify: the AI edits the named workflow (doesn't create another one), explains the change, and specifies the exact test. You test only this layer before moving on to the next.
Key concepts
One at a time.
Error > logic > output.
Name the workflow.
With each layer.
🔬 Real verification & testing
What it is
The skill that carries through every phase: testing with scenarios reais (happy path, edge cases, and out of scope), verify numbers and facts against the source, and require the agent to refuse to make things up what it doesn’t know. The golden rule remains: green ≠ correct — running without errors doesn't prove the answer is correct.
Why learn
To test a filter, you need to send exactly the type of input it should catch. An “out-of-scope” test (e.g., asking something that isn’t in the knowledge base) reveals whether the agent is honest or hallucinates. A good agent says “I don’t have that information” — and that’s desirable, not a bug.
🎯 Goal: put together a test plan that covers happy paths, edge cases, and out-of-scope cases.
Monte um plano de teste para <descreva o que foi construído> com 3 categorias: 1. Caminho feliz: <ex.: uma pergunta dentro do escopo, com resposta na base>. 2. Caso de borda: <ex.: entrada incompleta / formato incomum>. 3. Fora de escopo: <ex.: algo que NÃO está na base> — aqui o agente deve dizer honestamente que não sabe, sem inventar. Para cada teste, diga: a entrada exata, o resultado esperado e como conferir (números/fatos contra a fonte). Lembre: green ≠ correto.
✅ How to verify: you run all three types. The happy path gets the content right (not just “green”); the out-of-scope case produces an honest refusal, not an invented answer.
🎯 Practical tip
Check the numbers precisely: “30 days” and “one year” are different answers. Open the result and compare it with the source—don’t rely only on the green indicator.
Key concepts
Running doesn’t mean getting it right.
Happy path, edge case, out of scope.
Numbers and sources.
"I don't know" is good.
💾 Back up before making changes
What it is
The discipline that makes the cycle safe: before any change, do a backup (duplicate or export as JSON) and establish a tested baseline. That way, if the next optimization breaks something, you can revert it without losing what already worked.
What is it?Export JSON — save the workflow as a text file that you can reimport to restore the exact previous state. Baseline — a version you’ve confirmed works, used as a restore point.
Why learn
Without a baseline, you run two risks: being unable to roll back when something goes wrong, and blame the new change for a problem that already existed. Confirming that the happy path works before and after each change keeps the diagnosis honest.
🎯 Goal: create a safe baseline before optimizing.
Antes de eu começar a otimizar, me guie a: 1. Fazer um backup do estado atual (export em JSON ou duplicar) e onde salvá-lo. 2. Rodar um teste de caminho feliz para registrar a linha de base que funciona. Confirme que está tudo verde e correto AGORA. Só depois disso seguimos para as melhorias — uma de cada vez, testando após cada uma.
✅ How to verify: you have a saved backup file and a passing happy path test. If something breaks later, you can reimport the JSON and return to the good state.
Key concepts
Save first.
Return point.
Reimport and go back.
Don't blame the new one.
Your workflow ran without any errors (everything is green), but when you open the draft, you see that it cited "one year" when the policy says "30 days." What does that mean?
📌 Module Summary
Next Module:
3.3 — Ready-to-Use Prompt Library (copy-run)