DEV Community: SAMUELFMEDEIROS

Dois checkouts na mesma página: como eu unifiquei o funil do meu produto de pet

SAMUELFMEDEIROS — Sun, 15 Nov 2026 04:04:54 +0000

Dois botões de compra na mesma página custam mais do que parecem. Não é branding, é conversão: quem hesita entre dois checkouts geralmente não escolhe nenhum.

Eu tinha isso no meu site de pet. A mesma página vendia o guia por dois caminhos diferentes, com dois preços diferentes, e nenhum dos dois era o checkout que eu queria de verdade. Levou uma auditoria com curl para eu ver a bagunça que eu mesmo criei.

Como um funil quebra sem fazer barulho

A página /guia vendia um PDF de 51 páginas por R$ 47 através do Stripe. A página /guias/, listando os artigos, tinha um link de afiliado da Kiwify para um produto de R$ 27 que nem existia mais na conta. E o /petshop mostrava o PataPass com oito botões de WhatsApp e um preço de R$ 99, sem nenhuma demonstração pública.

Três caminhos de compra, três preços, um único produto por baixo. Nenhum deles estava quebrado — todos respondiam 200. É esse o problema: funil fragmentado não dá erro, ele só vaza.

O número que revela isso não é o de visitas, é o de checkout iniciado. E 200 na página não significa nada quando existem dois botões.

O que eu troquei, e por quê

Consolidei tudo em um checkout só: Mercado Pago, na loja que roda no meu domínio próprio. A escolha não foi por preferência de marca. Foi por três motivos verificáveis:

Pix. Aprovação no mesmo instante. Um produto de R$ 47 com boleto ou cartão de terceiro dia perde o comprador no caminho.

Um lugar para a garantia. O artigo 49 do Código de Defesa do Consumidor dá 7 dias de arrependimento, com devolução de 100%. Isso já era prometido no Stripe. Mas prometer em dois checkouts significa que só um dos dois realmente cumpre — e eu não tinha como garantir qual.

Um lugar para a contagem. Com dois checkouts, cada venda paga ficava dividida em duas contagens diferentes, e eu não conseguia responder "quantas vendas esse post gerou". Com um, a resposta é uma consulta.

O preço único ficou R$ 47 — o mesmo que a página já anunciava. O de R$ 27 nunca esteve no ar como produto comprável; era um cadastro pronto que não foi publicado na conta da Kiwify. Deixar os dois números no mesmo funil só ensinava o visitante a esperar uma promoção que não existia.

O erro que aprendi a não repetir

Antes de redirecionar o botão antigo, eu precisei de uma coisa chata e necessária: confirmar que o produto novo existia na loja de verdade. Não a página, o produto.

O código da loja tem uma rota /products que serve o catálogo. Foi ela que respondeu:

GET /products -> 12 itens, nenhum com id "pet-em-casa"

Se eu tivesse só criado a página e apontado o botão, o resultado seria pior que o problema original. A rota /item?id=<slug> fazia items.find(...) || items[0] — quando o id não existia, caía no primeiro produto da lista. O visitante clicava no guia de pet e via um ebook de engenharia de software, com preço e estoque do produto errado.

Consertei a causa: id que não existe agora é "produto indisponível", com os botões desabilitados, em vez de fingir que é o primeiro item da lista. É um bug de uma linha que vende o produto errado — o tipo de coisa que teste de unidade não pega, porque a página responde 200 e parece certa.

O que isso ensina sobre "publicar" produto digital

Três verificações, na ordem, que eu deveria ter feito desde o começo:

O produto existe no catálogo servido? Não no arquivo, não na configuração: na resposta HTTP que o checkout usa.
A preferência de pagamento é criada com o valor certo? Uma POST no endpoint de criação devolve o total. total: 47 e installments: 6 são a prova. "O botão está lá" não é prova.
Todas as portas antigas fecham? Se um link velho continua vendendo, o funil continua partido. Redirecionar é parte da entrega, não faxina posterior.

É a mesma lógica do post anterior sobre agentes que dizem "feito". O botão de compra é a versão mais cara dessa mentira: um checkout que existe na página mas não no catálogo é um "feito" que custa venda.

O detalhe que quase passa

A primeira versão do meu redirecionamento não funcionou. Eu coloquei a regra de /item?id=pet para /pet depois do mapa de rotas estáticas, então a rota antiga respondia antes dela e o 301 nunca disparava. O curl mostrou 200 onde eu esperava 301, e o texto loc= vazio.

Sem medir, eu teria anunciado a correção e ela não existiria. O teste local e o de produção deram o mesmo resultado, o que é o único jeito de saber que a regra pegou.

Series start (if you landed here first): https://dev.to/samuelfmedeiros/a-marketplace-price-is-retail-not-cost-how-not-to-build-margin-on-the-wrong-number-2oek

O guia está em focinho.seu.pet/guia, e o checkout em safmarket.seu.pet/pet. Se você tem loja própria e mais de um botão de compra na mesma página, o teste é simples: conte quantos checkouts o seu funil abre. Se a resposta for maior que um, o vazamento já começou.

Se você quer o caminho inverso do que este texto descreve, o ebook O agente que não mente cobre R$ 37 os 14 capítulos sobre provar que o trabalho foi feito, em português.

Seu agente disse 'feito' e não era: o gate que eu instalo em um dia

SAMUELFMEDEIROS — Sun, 15 Nov 2026 03:43:48 +0000

Todo mundo que colocou um agente de IA para codificar já viu isso:

Feito! Implementei o cache, os testes passaram, pode subir.

Você abre o diff. O cache não tem invalidação. Os testes passaram porque um deles
está com assert True. E a função que "passou" nunca foi chamada no caminho real.

O agente não mentiu de propósito. Ele otimizou para a frase que encerra a tarefa.
Enquanto o critério de "pronto" for o próprio agente dizendo que está pronto, você
não tem verificação, tem opinião com fonte suspeita.

O que eu mudo: quem escreve não é quem certifica

O arranjo que funciona é chato e pequeno:

Builder, o agente que escreve o código. Ele não dá nota para o próprio trabalho.
Critic, um segundo processo (outro prompt, outro modelo, outro contexto) que recebe só o artefato e os critérios, e devolve uma nota de 0 a 100 com a evidência que sustenta a nota.
Gate, um número. Abaixo do threshold, não entrega. Sem negociação, sem "mas dessa vez é simples".

O detalhe que faz diferença não é a nota. É a evidência: cada ponto perdido tem
que apontar para um arquivo, um comando, uma saída. Nota sem evidência é crítica
decorativa, e crítica decorativa é pior que nenhuma, porque dá sensação de cobertura.

O teste que eu rodo para saber se o gate é real

Montei de propósito um projeto com dois problemas plantados: uma chave de API
escrita dentro do código e uma suíte de testes que cobre só parte do que o programa
faz. Rodei o loop.

FAIL secret-scan  w=60.0  0.0s  token sk-abc123
FAIL cobertura    w=40.0  0.0s  cobertura 41pct
SCORE=0.0  THRESHOLD=85.0  GATE=failed (round 1/8)
EVIDENCE=/tmp/atl/loop-report-r1.json

Nota 0 de 100, entrega reprovada, relatório gravado. É exatamente esse o resultado
esperado num projeto doente. No projeto saudável, o mesmo loop dá nota alta e libera.

O teste que importa para o seu gate é este: plante uma falha e veja se ele
reprova. Gate que nunca falhou não é gate, é enfeite com log.

Onde isso costuma quebrar na vida real

O gate que olha o texto do agente. Se o critério é "o agente disse que passou", você está medindo eloquência.
O teste que passa por ausência. pytest -q verde com 0 testes coletados é o verde mais comum e o mais caro.
A métrica que só sobe. Cobertura de 41% lida como "quase lá" há três meses.
O segredo no código. Aparece em log, em print de erro, em repositório público , e nenhum teste falha por isso, a menos que exista um passo que procure.

Nenhum desses é problema de modelo. É problema de contrato de entrega.

Como testar em 10 minutos, sem pagar nada

Peguei o loop que eu uso e publiquei a skill aberta: passo a passo, referências e os
scripts, com o mesmo caso de teste que usei acima.

Series start (if you landed here first): https://dev.to/samuelfmedeiros/your-agent-said-it-works-that-is-an-opinion-not-a-result-2hp5

Skill gratuita e o comando de instalação: https://skills.seu.pet/p/ai-test-loop
Repositório: https://github.com/Samuelfmedeiros/ai-test-loop

Roda contra qualquer agente que execute comandos. Se o seu loop não reprova um projeto
com falha plantada, você descobriu isso hoje e não em produção.

Se você não quer montar isso sozinho

Montar o gate é fácil. O que consome tempo é calibrar os pesos, cobrir o que o seu
projeto realmente faz, ligar no CI e convencer o time de que "85" é um número e não
um clima.

Eu instalo isso no seu projeto em um dia útil: gate com nota, evidência por ponto e
guardas no CI (teste de IA e diff visual). O primeiro ciclo roda junto com o seu time,
no seu código.

Setup guiado, R$ 1.500: instalação e configuração de até 2 skills em 1 projeto, com o primeiro ciclo rodando ao vivo e o registro de como repetir.
Setup + time, R$ 3.000: o anterior, mais 2 sessões de 1h com o time, guardas no seu CI e 30 dias de suporte por e-mail, até 3 projetos.
Diagnóstico, R$ 490: mapeio o processo que dói, digo o que vale automatizar e o que não vale. Abatido do projeto se você seguir.

Escopo, o que não entra e o que acontece depois do primeiro mês estão escritos na
página, sem letra miúda: https://skills.seu.pet/servico?utm_source=devto&utm_medium=artigo&utm_campaign=servico-validacao&utm_content=ai-test-loop

Se o seu caso for outro (atendimento que perde contato, planilha que ninguém confia),
a conversa de 30 minutos é gratuita e eu digo se nenhuma dessas coisas resolve o seu
problema. Dizer "não resolve" também faz parte do serviço.

O resumo que eu queria que alguém tivesse me dado antes: pare de perguntar ao agente
se ele terminou. Coloque um número entre o agente e o deploy, e faça a evidência
apontar para o arquivo. O resto é ajuste.

Twenty checkout sessions, zero sales — and every one of them was mine

SAMUELFMEDEIROS — Sun, 15 Nov 2026 03:17:13 +0000

My store dashboard said this:

page_view        11
checkout_start    9
purchase          0

An 81.8% view-to-checkout rate and a 0% close rate. Two ways to read that. Either my pricing is catastrophic, or the top of the funnel is fake. I spent an hour assuming the first one before I checked the second.

The top of the funnel was fake. All nine checkout opens were me.

The number that gave it away

Stripe's own list of checkout sessions was the only source I had not looked at. Twenty sessions, live mode:

status    payment_status   count
open      unpaid           15
expired   unpaid            5

Twenty sessions opened, zero paid. Fine, that is just low traffic, right? No. Look at what the sessions actually contained:

created     status   amount  currency  product
...4712137  open     4700    brl       ship-your-mcp-server
...4711914  open     14700   brl       pack-completo
...4711913  open     4700    brl       mcp-oauth-debug
...4708349  open     6700    brl       guia-agente-que-entrega
...4705960  open     4700    brl       visual-regression-gates
...4705958  open     4700    brl       visual-regression-gates
...4705957  open     4700    brl       visual-regression-gates

Three sessions for the same product within three seconds. Eleven different products inside a few minutes. One payment method list on every single session. That is not a customer comparing options. That is a script walking the catalog, and the script had my IP.

I had been testing checkout links after a deploy and never cleaned up the signal. Then I read the dashboard, saw 81.8%, and started writing a plan to fix a conversion problem that did not exist yet.

Why the dashboard could not tell me

Every analytics stack will tell you "a checkout started". Almost none will tell you "a customer started a checkout". The event has no buyer attached to it, so a bot, a probe, your staging run and a real person land in the same counter.

The fix is not a better dashboard. It is attaching evidence to the event, at the moment it is written:

Identity. Was the request from my own IP, my own cookie, or a header my test harness sets? Those events get a dono class, not a customer class.
Timing. Sessions per IP inside a sliding window. Three in ten minutes is a comparison shopper being unlucky. Eleven in thirty seconds is a walker.
Payment method surface. If every session exposes the exact same method list and none progresses, nothing human is in the loop.
Status, not just creation. open and unpaid is not a sale. A dashboard counting session creation as intent will always look better than the business.

That last one is the whole bug in one line: I was counting my intent to test, not their intent to buy.

The class of bug that keeps paying me visits

I have written about this shape before, in three other costumes:

A regex that matched a single digit, so 1.234 silently became 1, and a dashboard read the same number for three weeks.
A guard reading a database that no longer received events, reporting "0 pending" with full confidence.
A watchdog restarting services at boot because systemctl is-active returns non-zero for activating.

Same shape every time: the check reports on a proxy, the proxy drifts from reality, and the report stays green. You do not fix this by being more careful. You fix it by making each number answer a narrower question with its evidence attached. Not "did a checkout start" but "which person started how many checkouts, from where, and did any of them finish".

What the real funnel looks like now

Once test traffic is excluded, the honest numbers on my store are small enough to be embarrassing and useful at the same time:

29 human visitors in two days of measurement
2 leads, both from the free skill
0 sales, from anyone, ever

Nine checkouts at 81.8% was a story I could act on. Twenty-nine humans and no sale is a different story: there is no conversion data yet, because there is not enough traffic to convert. Optimising a page that 29 people saw is a way to feel productive.

So the fix went in the other direction. I made the test traffic visible instead of removing it, because the next person to read the dashboard needs to know which class of visitor produced the number:

def classifica_visitante(ua, ip, dono_header, cookie_dono):
    if dono_header or cookie_dono:
        return "dono", "marcado"
    if ip and ip in IP_DONO:
        return "dono", "ip_dono"
    if _BOT_RE.search(ua or ""):
        return "bot", "ua_bot"
    if _REAL_BROWSER_RE.search(ua or ""):
        return "humano", "ua_navegador"
    return "incerto", "ua_desconhecido"

The incerto class matters more than it looks. The previous version defaulted unknown traffic to "human", and a single probe generated 61 page views attributed to one person. Absence of evidence is not evidence of a customer.

One caveat I now carry: adding a classification column to a table does not retroactively classify history. My own first read of the new dashboard showed 323 "uncertain" visitors and looked like a traffic spike. It was the column's default value on rows written before the column existed. If a metric changes shape on the day you shipped it, that is the migration, not the market.

The rule I keep

Before writing a single line about conversion, click the path yourself with the data open. The gap between "the dashboard says" and "the provider says" was twenty sessions and one hour. The provider knows who paid. The dashboard knows who loaded a pixel.

If you want the same evidence rule wired into your own checkout — the one that stops counting a bot, a probe and a customer in the same number — the AI Test Loop skill ships the gate and the tests that fail when the evidence is missing.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/dois-checkouts-na-mesma-pagina-como-eu-unifiquei-o-funil-do-meu-produto-de-pet-8fj

See the AI Test Loop skill
See all skills

Five open issues, one bug: your MCP OAuth refresh token is being replayed after rotation

SAMUELFMEDEIROS — Sun, 15 Nov 2026 03:07:54 +0000

Five open issues, one bug: your MCP OAuth refresh token is being replayed after rotation

I read five open issues across Codex, Claude Code, Gemini CLI and Hermes Agent in one sitting. They look like five different bugs. They are one bug wearing five costumes: the client keeps using a refresh token the server already rotated, and never tells you.

Here is the pattern, the code that causes it, and the check that catches it before your users do.

Five symptoms, one mechanism

From the issues themselves:

Project	Symptom as reported
`openai/codex` #39054 (22 comments)	"a rejected refresh token stays usable, so Codex retries it forever and never surfaces re-authentication"
`openai/codex` #48507	"concurrent processes race refresh-token rotation in `.credentials.json`; next startup hits `invalid_grant`"
`anthropics/claude-code` #89862	"`refresh_token` request omits `scope`, so the refreshed token comes back with the wrong scope and the server 401s"
`google-gemini/gemini-cli`	"concurrent MCP OAuth refreshes race, and any refresh failure..."
`NousResearch/hermes-agent`	"background agents replay a dead MCP OAuth refresh token"

Every one of these is the same three lines of logic missing:

A refresh attempt returns 400 invalid_grant.
Nobody persists that rejection.
The next attempt reads the same token from disk and tries again.

OAuth 2.1 rotated refresh tokens are single-use by design. Once the authorization server hands you a new one, the old one is dead. A client that treats "I have a refresh token" as "I can refresh" will spin forever against a corpse.

The bare `except` that hides the death

This is the shape I keep finding. It parses as defensive. It is the opposite:

def get_access_token():
    creds = load_credentials()
    if creds["access_token"] and not expired(creds["access_token"]):
        return creds["access_token"]
    try:
        new = refresh(creds["refresh_token"])
        save_credentials(new)
        return new["access_token"]
    except HTTPError as e:
        if e.code == 401:
            pass          # fall through to return whatever we have
        raise
    return creds["access_token"]   # <-- the dead one, returned as if alive

Two failures live in that pass:

The rejection is not recorded. Nothing marks the refresh token as revoked. The next call loads the same record from disk, sees a non-empty refresh_token, and repeats the identical doomed request.

A stale token is returned as valid. Falling through to creds["access_token"] hands the caller a token that the resource server has already rejected, and the surface error becomes a generic 401 on the tool call — not "your auth is dead, re-login". The user sees a broken tool, not an auth problem. The two issues that say "never surfaces re-authentication" are exactly this line.

The rotation race

The second failure mode needs no server at all. It needs two processes.

Codex #48507 documents it cleanly: several TUI sessions plus an app-server daemon share one .credentials.json. Stripe access tokens live 1h, Supabase 24h. At T0+24h two processes refresh at once:

proc A: read refresh_token=R1  -> POST /token -> gets R2 -> writes {R2}
proc B: read refresh_token=R1  -> POST /token -> 400 invalid_grant

proc B did nothing wrong. It read a valid file and used a token that was valid a millisecond earlier. The server is correct to reject it: R1 was single-use and R1 is gone. But proc B — running the bare-except code above — now concludes the grant is broken and demands a full re-login.

Every reboot. All servers at once. That is the reported symptom, and it is not a server bug.

Three checks that catch it

If you maintain an MCP client, these are the assertions worth having. They are cheap and each one maps to a real reported failure.

1. The rejection must be persisted, not swallowed.

def refresh_access(creds):
    try:
        new = post_token_endpoint(creds, grant="refresh_token")
    except OAuthError as e:
        if e.error == "invalid_grant":
            mark_revoked(creds["server_url"])   # persist, do not pass
            raise ReauthRequired(creds["server_url"])
        raise
    return new

The test: force invalid_grant twice, assert the second call never hits the network and the error is ReauthRequired, not a timeout or a 401 on an unrelated tool.

2. Rotation must be atomic across processes.

Writing the file is not the race; read-modify-write is. A file lock around the refresh, plus a re-read inside the lock, collapses the race:

with file_lock(CRED_PATH):
    creds = load_credentials()          # re-read AFTER the lock
    if creds["access_token"] and not expired(creds["access_token"]):
        return creds["access_token"]    # someone else already refreshed
    return refresh_access(creds)

The test: spawn two processes against a stub server that rotates on every call. With the re-read, both succeed and only one token request is made. Without it, one gets invalid_grant.

3. scope must be sent on refresh.

RFC 6749 §6 makes scope optional — omit it and the server should replay the original grant. Real servers do not. Claude Code #89862 has the table:

interactive login  (sends scope)            -> scp=mcp.access  -> 200
client refresh     (omits scope)            -> scp={guid}      -> 401
manual   refresh   (sends scope)            -> scp=mcp.access  -> 200

Same refresh token, same endpoint. The only difference is the parameter. Against Entra this fails reliably; other authorization servers fail less predictably, which is worse, because it presents as "auth breaks every hour or so".

Send the original scope:

payload = {"grant_type": "refresh_token", "refresh_token": token}
if original_scope:
    payload["scope"] = original_scope   # do not rely on the server's memory

Why this is hard to see in production

The failure is not loud. A revoked refresh token produces a 401 on a tool call three layers away from the auth code. Your logs show a failed tool, not a dead grant. Users retry, which multiplies the attempts, which makes it look like a flaky server.

The tell is the retry count on a token that was rejected once. If invalid_grant appears more than once for the same (server, refresh_token) pair in your logs, the client is replaying. That is the number to alert on.

What I packaged from this

I turned these three checks into a skill people can drop into an agent workflow: mcp-oauth-debug — reproduces each failure against a stub authorization server, then asserts the three behaviors above. It exists because I hit the invalid_grant loop in my own agent stack and spent longer than I want to admit blaming the server.

If you are debugging one of the five issues above, the stub-server repro is the fastest way to know whether your client replays a dead token: rotate on every call and count the requests.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/seu-agente-disse-feito-e-nao-era-o-gate-que-eu-instalo-em-um-dia-57n9

The reproducible checks are packaged as a paid skill — mcp-oauth-debug (R$ 47, Stripe, instant delivery). The article above is the full diagnosis; the pack is the stub server and the assertions.

Written while reading open issues on 2026-11-15. Issue numbers and quotes are from the public trackers on that date; line numbers and code inside each project may have moved since.

The flag file my watchdog wrote was 0 bytes, so the alert fired for 8 days

SAMUELFMEDEIROS — Sun, 15 Nov 2026 01:11:29 +0000

A monitoring script is supposed to stop shouting once you've been told. Mine shouted every morning for eight days, and the reason was a file with zero bytes.

The design that looked fine

The pattern is common: a cron job runs every hour, checks something, and when the check fails it sends a message. To avoid a message every hour, it keeps a latch — a small JSON file with the date of the last time it warned. If the latch says "already warned today", the job stays quiet.

def already_warned(chave):
    try:
        with open(LATCH) as fh:
            dados = json.load(fh)
        return dados.get(chave) == today()
    except FileNotFoundError:
        return False
    except Exception:
        return False          # <-- the line that cost me 8 days

Note the last branch. It exists "to avoid crashing the monitor". It does something else entirely: it converts every imaginable bug into "not warned yet", which is the loudest possible state.

What actually broke

The write side looked like this:

def grava_latch(chave):
    dados = {}
    try:
        with open(LATCH) as fh:
            dados = json.load(fh)
    except Exception:
        pass
    dados[chave] = time.strftime("%Y-%m-%d")
    with open(LATCH, "w") as fh:
        json.dump(dados, fh)

time was never imported in that module. NameError: name 'time' is not defined — raised inside the try, caught by the bare except Exception: pass. Except no: the failing line is after the try, so the exception propagated to the caller, which wrapped the call in its own except: pass, then sys.exit(0). The file had already been created by open(LATCH, "w") before the crash. Result: a latch that exists, is 0 bytes, and reads as "never warned".

Every symptom pointed the wrong way:

The job's exit code was 0.
The job's output was empty.
The latch file existed with a fresh mtime.

Three green signals, one broken behaviour. If I had only looked at systemctl status or the job's status field, I would have concluded the alert was a duplicate-delivery problem and gone hunting in the message sender.

The three rules I extracted

1. A latch is state, so verify it is state. A zero-byte, unparsable or stale file must be treated as an error, not as "nothing recorded yet". After writing, read it back and assert the content:

with open(LATCH, "w") as fh:
    json.dump(dados, fh)
    fh.flush()
    os.fsync(fh.fileno())
assert os.path.getsize(LATCH) > 0

Cheap, boring, and it turns a silent 8-day failure into a single loud crash on the first run.

2. except Exception: pass is a decision to lose the bug. Keep the catch, but surface the exception when a debug flag is set, or at minimum write repr(exc) into a sibling .err file. Silence belongs to cases you can name (FileNotFoundError on first run), not to the case "I do not know what happened".

3. Status fields lie in one specific direction. A job that exits 0 without doing anything is indistinguishable from a job that did it. This is the same class of failure as an HTTP 200 from the wrong server: the indicator measures liveness, not the thing you care about. Assert the effect, not the exit.

Why I keep finding these

Every one of these bugs is a verification bug wearing a different costume. I have now hit, in the same codebase, in a few weeks:

A parser whose regex matched a single digit, so 1.234 silently became 1 and a dashboard read the same number for three weeks.
A guard script reading the wrong database file, reporting 0 pending — accurate for a database that no longer received events.
A watchdog that restarted services on boot because systemctl is-active returns a non-zero code for activating, and the shell appended a second line that never matched.
This one: a flag file that existed, empty, and therefore said "nothing happened".

The shape is identical each time: the check reports on a proxy, the proxy drifts from reality, and the drift is invisible because the report is green. You do not fix this class by being more careful. You fix it by making each check answer a narrower question with evidence attached: not "is the service up" but "which PID is listening and does its identity match the version I deployed"; not "did the job run" but "did the effect it was supposed to produce appear".

The part that actually costs the time

Not the bug. Bugs are cheap. The expensive part is the two days spent looking at the alerting pipeline, because the alert had to be lying — the job was green.

The rule I follow now, before touching any fix: when something contradicts itself, the first job is to find which measurement is fake. One tail of the raw output, one read-back of the file, one query of the actual store — done in that order, before any hypothesis about the system's behaviour. Reading the raw tail instead of grepping for the success string is what surfaced this one; the traceback was in the last three lines, and the grep for warned had hidden it.

If you want the checklist I use to make "done" mean something before shipping an agent or a job that claims it worked, it is here as a free package:

The latch and the watchdog are two of the seven chapters in The Agent That Delivers: guia-agente-que-entrega — R$ 67, instant delivery.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/five-open-issues-one-bug-your-mcp-oauth-refresh-token-is-being-replayed-after-rotation-5705

The AI Test Loop skill, free

It is the gate I put in front of my own agents: separate reviewer, no paid model in the loop, exit codes that CI can read, and never a pass for an inconclusive run.

O agente que escreve o código não pode ser o que o certifica

SAMUELFMEDEIROS — Wed, 04 Nov 2026 20:21:20 +0000

Toda demo de agente termina igual

O modelo escreve o arquivo, roda a coisa, imprime "pronto". Ninguém confere.

A entrega que parecia terminada às 2 da manhã vira um arquivo que não existe, um
teste que nunca rodou e um resumo confiante.

Batemos nisso vezes suficientes para parar de acreditar na palavra do agente que
fez o trabalho. Não porque o modelo é preguiçoso — porque um LLM não consegue
certificar o próprio artefato. Ele declara sucesso de dentro, onde não vê a falha.

Três falhas, uma causa

Construir um laço de validação para os nossos agentes expôs três modos de quebra:

Autoavaliação forjada. O modelo que gerou o artefato é o modelo que o avalia. Mesmo contexto, mesmos pontos cegos. Ele diz "parece correto" sobre um diff que nunca executou.
FoFo — Found on False. A IA não pode corrigir a própria prova. Quem escreve o código não escreve o teste que o valida, e quem julga não compartilha contexto com quem construiu.
Verificação fraudável. Se o verificador mora onde o agente alcança, o agente falsifica o verificador. Um pytest.py falso que devolve 0 não é hipótese — é o movimento óbvio.

As duas primeiras são sobre autoridade: só evidência externa pode declarar
PRONTO. A terceira é sobre alcance: a evidência tem de ser produzida num lugar
que o construtor não toca.

O gate cego

Então a arquitetura parte o laço e põe a prova do lado de fora:

Tarefa ──▶ [SOUL / Builder] ──▶ [Gate cego] ──▶ [Juiz / Revisor] ──▶ Envelope
              ▲                    │ FAIL              │ REJECT
              └──── required_fix ──┘                   │ (max_attempts → ESCALADO)
                     (re-gate, estrito)                ▼ APROVADO → SUCESSO

Builder / SOUL. Rascunha a partir de persona + memória procedural + tarefa. Pode referenciar um segredo pelo nome ($VAULT_X), nunca pelo valor.
Gate cego. O ambiente inalcançável. Roda a ferramenta de verdade — HTTP via curl, nc, ffprobe, EXPLAIN em seco, HMAC-SHA256, um regex declarado — e devolve (passou: bool, log: str). A evidência é refeita a cada tentativa. Gate verde da rodada 1 nunca é reaproveitado na rodada 2.
Juiz / Revisor. Uma sessão sem o histórico do Builder, confrontando rascunho
- log do gate contra as regras injetadas. Ele emite um veredito de roteamento, não o texto final. A rejeição injeta required_fix no próximo prompt do Builder, invisível ao canal humano.

O contrato é tipado (Pydantic v2 — sem LangChain, sem LangGraph, decisão
documentada): o envelope carrega soul_id, um status restrito a
SUCCESS | ESCALATED_TO_DM | TOOL_FAILURE, e uma trilha de auditoria com
self_correction_count, rules_applied, latency_ms, hedge_warning e o
gate_log cru.

A regra de ouro do laço

O LLM pode sugerir que terminou. Só evidência externa pode declarar PRONTO.

SUCCESS só existe quando gate_pass == true e judge_pass == true. Todo o
resto termina em ESCALATED_TO_DM (teto de tentativas) ou TOOL_FAILURE. O agente
para onde a autorização termina — o que provamos num piloto ao vivo que bateu num
404 real e devolveu nenhum payload inventado em vez de alucinar um.

O que é preciso para confiar no testador

Gates vêm em dois tipos, ambos declarados num registro só:

subprocess: argv renderizado com o artefato, executado como processo do host.
static: validador determinístico em processo (um regex de prompt MEDIA:), ainda fora do intérprete do LLM e ainda declarado no registro.

Parâmetros entram por string.Template, então literal de shell/HTTP/JSON
(%{http_code}, {"exact":false}) nunca colide com interpolação.

O harness mede a si mesmo com função pura, sem LLM no meio, em seis dimensões —
contratos determinísticos, autoteste do orquestrador, orquestração ponta a ponta,
política de custo, operação viva, documentação. Cada dimensão devolve um de quatro
estados (PASS | FAIL | NOT_VERIFIABLE | ERROR), e o veredito é derivado, não julgado:

APTO          todas as dimensões PASS e total >= 90% do teto (fixo)
COM RESSALVAS nenhum FAIL/ERROR, mas algo é NOT_VERIFIABLE (>= 70%)
REPROVADO     qualquer FAIL/ERROR, ou total < 70%

Dimensão não executada fica no denominador, e os códigos de saída são 0 / 1 / 2 —
para o CI poder chamar. Inconclusivo nunca passa o gate: essa regra veio de uma
máquina quebrada que, sem ela, teria entregue verde.

Onde está hoje

Números honestos, todos medidos localmente:

44 testes pytest verdes
2 pilotos ponta a ponta (dois projetos sem relação, mesmo motor)
1 entrega real num canal humano (message_id=43843)
política de custo imposta: o gate nunca chama modelo pago

Não é framework. Sem montanha de dependência, sem marketing de agente-de-agentes.
A alegação é estreita de propósito: não deixa seu agente mais inteligente, deixa o
"pronto" valer alguma coisa.

A versão de código aberto do motor do laço, incluindo o registro de gates e o
harness de qualidade, está aqui:

Kit de templates: agente que entrega — os 12 arquivos que esse laço precisa no seu repo: contrato, gate, watchdog e entrega: kit-templates-agentes — R$ 97, instant delivery.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/make-your-ai-agent-prove-it-a-deterministic-delivery-gate-5b8i

→ Baixe a skill AI Test Loop grátis

The Agent That Writes the Code Cannot Be the One That Certifies It

SAMUELFMEDEIROS — Tue, 03 Nov 2026 03:14:54 +0000

Every agent demo ends the same way

The model writes the file, runs the thing, and prints "done". Nobody checks.
So the deliverable that looked finished at 2am turns out to be a file that does
not exist, a test that was never run, and a summary that was confident.

We hit this enough times to stop trusting the word of the agent that did the
work. Not because the model is lazy — because an LLM cannot certify its own
artifact. It declares success from the inside, where it cannot see the failure.

Three failures, one root cause

Building a validation loop for our agents surfaced three distinct ways it breaks:

Forged self-evaluation. The model that generated the artifact is the model evaluating it. Same context, same blind spots. It says "looks correct" about a diff it never executed.
FoFo — Found on False. The AI must not correct its own proof. Whoever writes the code cannot write the test that validates it, and whoever judges cannot share context with whoever built.
Cheatable verification. If the verifier lives where the agent can reach, the agent forges the verifier. A fake pytest.py that returns 0 is not a hypothetical — it is the obvious move.

The first two are about authority: only external evidence can declare DONE.
The third is about reach: the evidence has to be produced somewhere the
Builder cannot touch.

The held-out gate

So the architecture splits the loop and puts the proof outside:

Task ──▶ [SOUL / Builder] ──▶ [Held-out Gate] ──▶ [Judge / Reviewer] ──▶ Envelope
              ▲                    │ FAIL              │ REJECT
              └──── required_fix ──┘                   │ (max_attempts → ESCALATED)
                     (re-gate, strict)                 ▼ APPROVE → SUCCESS

Builder / SOUL. Drafts from persona + procedural memory + task. It may reference a secret by name ($VAULT_X), never by value.
Held-out Gate. The unreachable environment. Runs the real tool — HTTP over curl, nc, ffprobe, an EXPLAIN dry-run, HMAC-SHA256, a declared regex — and returns (passed: bool, log: str). Evidence is re-run on every attempt. A green gate from round 1 is never reused in round 2.
Judge / Reviewer. A session without the Builder's history, confronting draft + gate log against the injected rules. It emits a routing verdict, not the final text. Rejection injects required_fix into the next Builder prompt, invisible to the human channel.

The contract is typed (Pydantic v2 — no LangChain, no LangGraph, decision
documented): the delivery envelope carries soul_id, a status restricted to
SUCCESS | ESCALATED_TO_DM | TOOL_FAILURE, and an audit trail with
self_correction_count, rules_applied, latency_ms, hedge_warning and the
raw gate_log.

The golden rule of the loop

The LLM may suggest it finished. Only external evidence may declare DONE.

SUCCESS exists only when gate_pass == true and judge_pass == true.
Everything else terminates as ESCALATED_TO_DM (attempt ceiling) or
TOOL_FAILURE. The agent stops where the authorization ends — which we proved
on a live pilot that hit a real 404 and returned no invented payload instead of
hallucinating one.

What it takes to trust the tester

Gates come in two kinds, both declared in one registry:

subprocess: argv rendered with the artifact, executed as a host subprocess.
static: an in-process deterministic validator (a MEDIA: prompt regex), still outside the LLM interpreter and still declared in the registry.

Parameters are injected through string.Template, so shell/HTTP/JSON literals
(%{http_code}, {"exact":false}) never collide with interpolation.

The harness measures itself with a pure function, no LLM in the middle, across
six dimensions — deterministic contracts, orchestrator self-test, end-to-end
orchestration, cost policy, live operation, documentation. Each dimension
returns one of four states (PASS | FAIL | NOT_VERIFIABLE | ERROR), and the
verdict is derived, not judged:

APTO          all dimensions PASS and total >= 90% of the (fixed) ceiling
COM RESSALVAS no FAIL/ERROR, but something is NOT_VERIFIABLE (>= 70%)
REPROVADO     any FAIL/ERROR, or total < 70%

Unexecuted dimensions stay in the denominator, and exit codes are 0 / 1 / 2 —
so CI can call it. Inconclusive never passes the gate: that rule came from a
broken machine that would otherwise have shipped green.

Where it stands

Honest numbers, all from local measurement:

44 pytest tests green
2 end-to-end pilots (two unrelated projects, same engine)
1 real delivery to a human channel (message_id=43843)
cost policy enforced: the gate never calls a paid model

Not a framework. No dependency mountain, no agent-of-agents marketing. The
whole claim is narrow on purpose: it does not make your agent smarter, it
makes "done" mean something.

The open-source version of the loop engine, including the gate registry and the
quality harness, is here:

Agent templates kit — the 12 files this loop needs in your repo: contract, gate, watchdog and delivery: kit-templates-agentes — R$ 97, instant delivery.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/o-agente-que-escreve-o-codigo-nao-pode-ser-o-que-o-certifica-2f65

→ Download the free AI Test Loop skill

Make your AI agent prove it: a deterministic delivery gate

SAMUELFMEDEIROS — Mon, 26 Oct 2026 11:20:11 +0000

Make your AI agent prove it: a deterministic delivery gate

Tags: ai, testing, agents, devtools
Canonical URL: https://skills.seu.pet/en/blog/make-your-agent-prove-it?utm_source=devto&utm_medium=article&utm_campaign=make-your-agent-prove-it

npx ai-test-loop --config loop.json — one command, five seconds, nothing installed. Runs a deterministic critic over your artifact and returns a score, a gap list and the raw output of every check.

Prefer Python? pip install ai-test-loop gives you the same gate. Free version · Full pack

The agent said it was done. The gate disagreed.

A real run from this week: the builder reported done, the critic scored 55 and returned a gap list with names and weights. Two checks were failing, one of them a secret scan that found a token in the diff. No opinion was involved — the report attached the raw output of every check. This is what a deterministic delivery gate looks like when you stop asking the model whether the work is good and start measuring.

This skill is now published as a real package. npx ai-test-loop runs in five seconds with nothing installed; pip install ai-test-loop gives you the same gate in Python. The repository is open (MIT), and the free version is a real download — not a teaser.

Why the same context lies

The classic failure: one context writes the code, runs the tests, reads the result and decides whether it is done. The model that produced the bug is the model that judges the fix. The gate breaks that loop by moving the judgement into a separate process that executes real commands and returns numbers, not prose.

Builder — writes the change. No veto power over the verdict.
Critic — runs every declared check against the real artifact. Scores it. Never asks a model if it is good.
Reviewer — independent context, fresh, no justification from the builder. Returns strict JSON.
Security gate — fail-closed. A secret, a high-severity finding or an injection issue blocks delivery even with a perfect score. Inconclusive counts as blocked.

Rule zero: builder ≠ critic ≠ reviewer. If one context does all three, the loop is theatre.

The gate, step by step

Declare the checks before writing code — for each check: name, command, weight and what "pass" means. Weights sum to 100.

   {"checks":[{"name":"pytest","cmd":"set -o pipefail; pytest -q","weight":40},{"name":"no_secret_scan","cmd":"gitleaks detect --no-banner","weight":30}]}

Run the critic — it executes every command for real, captures the evidence and never asks a model whether the work is good.

   python scripts/loop_runner.py --config loop.json --round 1

Score, compare, decide — above the threshold goes to the reviewer; below, take the largest gap, fix it and run again. Cap the rounds (8 is plenty): if it never converges, the check set is wrong, not the code.
Independent review before delivery — same artifact, fresh context, no justification from the builder. A panel of 2-3 specialists (quality and security always) returning strict JSON.
Security gate, fail-closed — a secret in the diff or history, a high-severity finding, an auth/path-traversal/injection issue block delivery even with perfect tests. An inconclusive answer counts as blocked, never as pass.
Report with score, evidence and what was not verifiable — the report states what was measured, with raw output, and what could not be checked — no "probably fine".

Four ways a green loop lies

Piping hides the exit code — pytest | tail returns the exit code of tail (0), so the critic scores 100 with a failing test hidden in the output. Use set -o pipefail inside every check.
A timeout shorter than the check is a silent zero — the critic is killed by its own timeout, the orchestrator reads score 0 with an empty gap list, and loops with nothing to fix. Set the timeout above the real duration and always keep the critic's raw log.
A short-circuiting "pass" — a server answering 200 may be the wrong server: on a port collision the check tests a different app and fails for the wrong reason. Assert identity (title, version, a known payload), not just reachability.
A stale baseline regenerated to go green — regenerating a visual baseline "to pass" erases the regression the test exists to catch. Baselines change by explicit decision, justified in the history — never to silence a check.

Install it now

The package ships a dependency-free runner (Node or Python), the scoring rubric, the reviewer prompt and the security checks. Two commands, two ecosystems, one name, same gate.

npx ai-test-loop --config loop.json
# or, if you prefer Python
pip install ai-test-loop && ai-test-loop --config loop.json

Next in this series (the one after this): https://dev.to/samuelfmedeiros/the-cron-runs-says-completed-and-the-message-never-arrives-4pam

Yurumi: the dry run that wrote and the error that hid its own name

SAMUELFMEDEIROS — Fri, 23 Oct 2026 00:25:59 +0000

The tool that always said "ok"

Every fifteen minutes, a small script read the system's scheduled task list and wrote one point per task into Yurumi's vector memory. That way, when I asked the agent "did the 3am backup run?", it did not have to guess — the snapshot was indexed.

The output was always one green line. crons ok, nothing to re-embed, known total. Green for weeks. And it was a lie on three fronts at once.

The first was invisible by construction: it read one jobs file, the root one. Except most of my tasks live in per-profile stores, separated precisely so scopes never mix. Hundreds of jobs did not exist in the index — and an empty result in a memory system is indistinguishable from "this never existed".

The second was worse: the script had --dry-run, documented as "lists what would change only (writes nothing)". And it wrote. set_payload was called with no guard condition at all, so a command I used to inspect things safely was mutating the index.

The third is the one that kept me from seeing the other two.

The error that lied about its own name

When it failed, the report looked like this:

(yurumi-cron-sync indisponível: ModuleNotFoundError: )

Note the void after the colon. The message was assembled from type(e).__name__ and nothing else — the class name, without the exception text. For months I read "ModuleNotFoundError" and went hunting for a broken import.

The real cause was different: an absolute path from another operating system hardcoded in the file, inherited from before the machine migration. The first file it tried to open did not exist, and the FileNotFoundError was caught — but what reached the screen was the name of a later exception. A mislabelled alarm is worse than a silent one.

The number that surfaced once the dry run was honest

The fix came in three layers.

First the path: the base directory now comes from an environment variable with a home fallback, and the repository root is derived from __file__.

Then the read: load_jobs() now opens every store, deduplicating by id — the same job can appear in more than one file and must not become two index points. That is where a trap I had not predicted showed up: orphan pruning. Computed against a single store, it would delete from the index crons that are alive in another profile. Pruning is not about "what is not in the file", it is about "what is in no file at all". It is the kind of bug that throws nothing — it just removes data.

With the full read and the fixed pruning, the index told the truth: 762 cron points, of which 440 pointed at jobs that no longer existed anywhere. After pruning: 326, with four new jobs in the same run. Measured just now, in a verification run: 326 cron points inside a collection of 13,675.

Months of deleted jobs, with the index keeping a ghost of every one. In a hybrid search, an orphan point competes with a live one: it steals rank from a legitimate result.

Third, --dry-run got the guard it was missing, and the error message started carrying str(e)[:160] — enough to read "file X does not exist", not enough to dump a stack trace into the log.

python3 scripts/yurumi_cron_sync.py --dry-run
python3 scripts/yurumi_cron_sync.py --prune
python3 -m pytest tests/test_portability.py -q

The green that belonged to another commit

Here is the part that bothered me most, because it is not about code.

I finished the fix, documented both pitfalls in the repository's AGENTS.md, and pushed. The CI run for commit c6afd00 was created about seven minutes late and then cancelled by concurrency — another run on the same branch took the slot. No test ran on that commit, and no failure appeared.

The green I saw afterwards came from an empty commit, a47468d, with the same file tree, created only to re-trigger the suite. That one ran end to end: Ruff, pytest on 3.12, a clean install, and the secret scanner. The code was the same — but the commit carrying the fix was never tested, and I only noticed because I read the log instead of looking at the icon.

The same day offered another cheap example: a watchdog for a bridge that no longer exists since the migration was producing 49 alerts in six hours.

What changes

All three defects shared one signature: a tool reporting success without having measured anything. The code said ok because the exception was caught, because an empty store is not an error, because writing in simulation mode leaves no different trace.

The balance: "does this cron exist?" now has a truthful answer, the index shrank 57% without losing a single live job, and the mode that promises not to write finally does not. A test that rejects absolute paths from another system also landed (7 passed), along with the rule that a green commit is the one that ran, not its neighbour.

Next step

Validate the job name during pruning, not just the id: a stable id prevents duplicates, but a renamed job stays in the index under the old name, and today that passes as a normal update.

Se você mantém guardas e watchdogs próprios, o Roger MLOps Guard traz a
checklist de como provar que o guarda dispara de verdade, com o teste que falha
quando ele não dispara.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/twenty-checkout-sessions-zero-sales-and-every-one-of-them-was-mine-4pdc

See the Roger MLOps Guard skill
See all skills

The 302 that pretended to be a 200

SAMUELFMEDEIROS — Thu, 22 Oct 2026 23:32:21 +0000

The error that was not in the form

In production, every contact form submission came back with the default error message. The browser console was no help: the fetch died with a generic type, no body and no useful status. The reflex is to open the form code — and there was nothing wrong there. The backend answered. The database answered. The messages table existed.

It took me longer than I would like to accept the uncomfortable part: the problem was in neither end I could read in the editor. It was in the middle of the path — the site's own proxy and the access layer in front of the domain.

I split the path into three layers and tested one at a time: the form in the browser, the site's same-origin proxy, and the panel API that stores the messages.

Two traps stacked on one path

The first one had shown up days earlier and was documented in a code comment. Calling the panel API straight from the browser, from another origin, returned an empty body and no origin-allowed header. The fetch translated that into "network failure", the most dishonest message on the list — network failure suggests a cable, not an origin policy.

The fix was a same-origin proxy: a route inside Next itself that takes the browser request and forwards it server-side, with a closed list of allowed prefixes and a segment limit. Without a closed list, a proxy like that becomes an open door into the other service.

With the proxy live, sending the same POST through the site, the error stayed. And that is when the origin moved: an access configuration created in the middle of the night, meant to protect the admin panel, was covering the entire domain. Every request — including the public prefix the proxy needs to reach — got a redirect to the login screen. The browser followed it, was blocked by the origin policy, and the fetch died. The backend never saw the request.

Protecting the whole domain is the comfortable default of every access service, and it is exactly what breaks every endpoint the site has to call on its own.

Why the diagnosis took so long

One tooling detail cost more time than the bug: Python's HTTP library follows redirects by default. The probe I had been using said "200, healthy" — because it was reading the login page, not the API. A 200 on a login screen is a legitimate 200 and a completely wrong answer.

The right way to probe is to look at the real status code without following the redirect:

curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" \
  -X POST "https://<panel>/api/<public-prefix>" \
  -H "Content-Type: application/json" -d '{}'
# 302 https://<account>.cloudflareaccess.com/cdn-cgi/access/login/...   <- access in front

And the check that proves the server is up without writing anything to the database, because payload validation runs before the handler:

curl -s -o /dev/null -w "%{http_code}\n" -X POST "https://<panel>/api/<public-prefix>" \
  -H "Content-Type: application/json" -d '{}'
# 422 = reached the validation handler (open, server alive)
# 302 = login in front (closed too tight)
# 500 = server actually broken

Three codes, three meanings that cannot be confused — before that I only had the binary "worked / did not work".

The cure was infrastructure, not code

Not a single line of the site changed. The fix was creating an access app per path: coverage on the public prefix with a bypass policy, while the admin prefix stayed behind the login. The previous app, which covered everything, became the example of what not to do on a domain serving both the API and the panel.

Then four proofs in a row: a direct POST to the backend returned 201; a POST through the site proxy returned 201; an end-to-end test in a real production browser showed the success message with zero page errors; and a new row appeared in the messages table. It is no good for the API to answer if the path the user actually walks is still broken — which is why the final proof was in the browser, not in curl.

I measured it again just now: the public prefix returns 422 (open, validation working) and the admin prefix returns 302 to the login screen (closed, as it should be).

What stays

Three lessons, all about measuring — none about typing code:

Access is per path, not per domain. A domain serving site, API and panel needs per-route policy, otherwise the login eats the public endpoint and the symptom shows up far away, inside CORS.
200 without checking the final URL and the body proves nothing. A probe that follows redirects answers a different question than the one you asked.
A CORS error is a symptom, almost never the cause. The fetch only knows how to say "it failed"; the reason was three layers up, in a configuration that never passes through the editor.

The probe stopped being a command I remembered to run and became a periodic routine: it hits the public prefix expecting the validation response and confirms the admin side is still closed. Silent when everything is in place — an alert that screams all the time goes unread.

Next step

Run the same check on the other side: sweep the other subdomains that gained an access app in the last few weeks and find out which public endpoints are sitting behind a login nobody sees. The form was the first place where the failure hurt, and it is unlikely to be the only one.

O mesmo raciocínio de "200 não é resultado" está detalhado, com o roteiro de
verificação, aqui:

Next in this series (the one after this): https://dev.to/samuelfmedeiros/the-129-elements-that-only-existed-once-javascript-loaded-k23

The Agent That Does Not Lie — R$ 37, 14 chapters on exactly this: the check that reports 200 while the thing behind it is down:
get the ebook

The 200 that is not a result
See all skills

The 129 elements that only existed once JavaScript loaded

SAMUELFMEDEIROS — Thu, 22 Oct 2026 17:27:40 +0000

The page that arrived empty

Opening the portfolio with JavaScript blocked should show an ugly but readable site. It showed a frame. The header was in the HTML, the text was in the HTML, and nothing rendered — because almost everything arrived with opacity: 0 baked into the style attribute.

I measured production before touching a single line: 129 tags with inline opacity:0 in the HTML served by portifolio.seu.pet. Sixty of those are absolute layers and decorative grids, which is expected. The rest include real content — section headings, project cards, the hero block itself. The browser received the whole page and the visitor saw the background.

The culprit was not badly written CSS. It was a component pattern that looked harmless and appeared in 52 places across the repository.

The pattern that kept repeating

The portfolio uses framer-motion for entrance animations. The canonical way to write one is:

initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}

The component starts transparent and animates into view. On the client that works beautifully. The problem is what the server does with that initial: it serialises opacity:0 into the HTML. On the first paint the content is there, invisible, waiting for JavaScript to arrive and animate it. If the JS fails, lags, or simply never runs, the content never shows up.

Inside ProfileSection.tsx the variant was worse. Two hero layers used animate={{ opacity: 0, ... }} gated by mounted ? 1 : 0, where mounted comes from state that only flips to true inside a useEffect. On the server mounted is always false. So the HTML shipped with opacity:0 fixed and the grid background layer (line 676) and the cockpit SVG overlay (line 694) simply did not exist in the served page. Without hydration, they never would.

This was not a new bug. It was the third recurrence of the same family:

08/15 — commit 7322c55, PR #50: the "About" button and four other above-the-fold elements were invisible until hydration, from the same serialised initial.
08/12 — commit 4e279bc: CookieBanner read localStorage in the useState initialiser, rendered differently on server and client, and threw a React #418 hydration mismatch on every fresh visit.
10/19 — commit 8fee520, PR #142: the two hero layers.

Three episodes, three point fixes. The pattern stayed alive in 52 spots.

The cure: born visible, animated later

The root fix was not swapping opacity: 0 for opacity: 1 — that would kill the animation. It was inverting the gate: the HTML is born visible, and animation is only allowed on the client, after mount.

const mounted = useMounted();
<motion.div initial={mounted ? { opacity: 0, y: 20 } : false} ... />

initial: false disables the animation's starting state on the server and on the client's first render. The element is served opaque. Once the hook's useEffect marks mounted = true, the component re-renders with an animatable initial state — but whileInView starts from an element that was already on screen. The visitor sees exactly the same animation; the served HTML, however, defends itself.

useMounted runs 26 lines, comments included. Small abstraction, and it exists so the next component does not repeat the mistake.

The gate landed in 8 files: GlassCard (27 cards), ProjectHangar (cards and the section h2), BlogSection (article and title), SkillsCompact, TimelineItem, the theme and language toggles, the journey buttons and ProfileSection. Total: 67 lines added, 22 removed.

Validation happened on the HTML, not in the browser: serving the page without JavaScript, content elements with opacity below 1 dropped from roughly 50 to zero, with 435/435 tests green and a clean build.

The side effect the gate created

Changing the render cycle has consequences. GameShowcase registered a click listener on every game button inside a useEffect that ran once. With the gate applied to GlassCard, the card started re-rendering on mount — and the button node was replaced. The old listeners stayed orphaned on the old node, outside the DOM. The games stopped responding to clicks.

The diagnosis came from node identity: comparing the element reference before and after mount showed two different objects. The cure was to stop binding listeners to nodes that can be swapped — the click moved to delegation on the container, which survives re-renders:

const btn = (e.target as HTMLElement).closest("[data-game-btn]");
if (!btn) return;

Fewer listeners, more robust. Container delegation is the right answer whenever a child can be remounted.

Why it matters

The practical difference is between a page that needs JavaScript to exist and one that needs it to look good. Search crawlers, link previews, feed readers, browsers with script blocking and connections where the bundle takes its time all read the same served HTML. Before this, nearly half the page was a placeholder.

Worth recording the real state: this work is not finished. The hero layer fix shipped through PR #142 on 10/19 at 02:03. The gate across the whole component tree lives in PR #146, still open, with 435/435 tests green. Until it lands, the production repository still carries 52 raw initial={{ opacity: 0 occurrences.

Next step

Merge PR #146 and re-measure the HTML in production. The target is objective: the count needs to drop close to the 60 decorative layers, which are invisible on purpose. If it does not drop, the gate leaked in some component — and that means the family has a fourth episode waiting.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/yurumi-the-dry-run-that-wrote-and-the-error-that-hid-its-own-name-4h7m

git log --oneline --grep="SSR" -- src/components/ProfileSection.tsx
grep -rc "initial={{ opacity: 0" src/components/*.tsx | grep -v ':0'
curl -s https://portifolio.seu.pet | grep -o 'opacity:0' | wc -l

Se o problema é o teste visual que passa num dia e falha no outro, o
Visual Regression Gates cobre o que fixar (dado, não pixel) e como barrar o
diff que não é regressão.

See the Visual Regression Gates skill
See all skills

The cron runs, says “completed” and the message never arrives

SAMUELFMEDEIROS — Mon, 19 Oct 2026 01:43:30 +0000

A scheduled job has two possible outcomes: it ran and delivered; or it ran, said
“completed” and nobody received anything. The second is the common one — and the hardest to see,
because the status is green.

What makes a job “complete” without delivering

Platform not configured in the processYou enable the channel in the config, but the
delivering process was already running and read the old config. The job finishes with “platform not
configured” and a success status.
Manual run ≠ scheduled runRunning the job by hand uses a different delivery path
than the scheduler's. The manual test is green and the scheduled one never delivers.
Output file instead of the channelThe job writes the text to a file instead of
talking to the channel's API. It looks like delivery; it is a log.
Token in the wrong placeThe credential exists in your shell's environment, not in
the scheduler's — and the error shows up as “no permission”, not “no token”.

The proof that does not lie

There is exactly one proof of delivery: the identifier the channel returned when it
accepted the message. Store it and show it in the job report.

OK sendMessage message_id=48293 chat=-100...
Job status, exit code and a “success” log are all compatible with the message never leaving.
The id is not.

How to actually test it

Force the delivery conditionA job that “has nothing to do” tests nothing. Run it
once with guaranteed content.
Read the result from the channel's sideConfirm on the channel (or via its API)
that the message arrived — not in the scheduler's log.
Log which path was used“Run by the scheduler” and “run by hand” must appear in the
log: without that, you are testing the wrong path.

If the job is silent when there is nothing to do

Silence by design needs proof that the job ran: one log line per execution. Without it,
“I received nothing” and “the job did not run” are indistinguishable — and you find out weeks
later.

Next in this series (the one after this): https://dev.to/samuelfmedeiros/it-passes-on-your-machine-and-breaks-in-ci-the-causes-that-are-not-your-code-4on7

See the complete pack
See all skills

Want this wired into your project? Guided setup from
R$ 1.500, with the first cycle run together.

← all skills

DEV Community: SAMUELFMEDEIROS

Dois checkouts na mesma página: como eu unifiquei o funil do meu produto de pet

Como um funil quebra sem fazer barulho

O que eu troquei, e por quê

O erro que aprendi a não repetir

O que isso ensina sobre "publicar" produto digital

O detalhe que quase passa

Seu agente disse 'feito' e não era: o gate que eu instalo em um dia

O que eu mudo: quem escreve não é quem certifica

O teste que eu rodo para saber se o gate é real

Onde isso costuma quebrar na vida real

Como testar em 10 minutos, sem pagar nada

Se você não quer montar isso sozinho

Twenty checkout sessions, zero sales — and every one of them was mine

The number that gave it away

Why the dashboard could not tell me

The class of bug that keeps paying me visits

What the real funnel looks like now

The rule I keep

Five open issues, one bug: your MCP OAuth refresh token is being replayed after rotation

Five open issues, one bug: your MCP OAuth refresh token is being replayed after rotation

Five symptoms, one mechanism

The bare except that hides the death

The rotation race

Three checks that catch it

Why this is hard to see in production

What I packaged from this

The flag file my watchdog wrote was 0 bytes, so the alert fired for 8 days

The design that looked fine

What actually broke

The three rules I extracted

Why I keep finding these

The part that actually costs the time

O agente que escreve o código não pode ser o que o certifica

Toda demo de agente termina igual

Três falhas, uma causa

O gate cego

A regra de ouro do laço

O que é preciso para confiar no testador

Onde está hoje

The Agent That Writes the Code Cannot Be the One That Certifies It

Every agent demo ends the same way

Three failures, one root cause

The held-out gate

The golden rule of the loop

What it takes to trust the tester

Where it stands

Make your AI agent prove it: a deterministic delivery gate

Make your AI agent prove it: a deterministic delivery gate

The agent said it was done. The gate disagreed.

Why the same context lies

The gate, step by step

Four ways a green loop lies

Install it now

Yurumi: the dry run that wrote and the error that hid its own name

The tool that always said "ok"

The error that lied about its own name

The number that surfaced once the dry run was honest

The green that belonged to another commit

What changes

Next step

The 302 that pretended to be a 200

The error that was not in the form

Two traps stacked on one path

Why the diagnosis took so long

The cure was infrastructure, not code

What stays

Next step

The 129 elements that only existed once JavaScript loaded

The page that arrived empty

The pattern that kept repeating

The cure: born visible, animated later

The side effect the gate created

Why it matters

Next step

The cron runs, says “completed” and the message never arrives

What makes a job “complete” without delivering

The proof that does not lie

How to actually test it

If the job is silent when there is nothing to do

The bare `except` that hides the death