✅ Code That Works: TDD + Diagnose

An agent is a terrible verifier of its own work. It reads the code it just generated and sees that "looks right", and declares victory. Without a test run, “looks right” is just an opinion—and the agent’s opinion is biased by the code it wrote itself.

TDD solves this by turning things around: the test comes first, fails first, and only then is the code written to make the test pass. The agent can’t fool itself: either the test passes or it doesn’t.

The command /tdd puts the agent in a disciplined three-step loop. Each step has a single goal — don't skip, combine, or optimize prematurely.

# você
/tdd implementa função slugify(texto) — minúsculas, espaço vira "-",
remove acentos, remove caracteres especiais

# agente
🔴 Red: escrevi 4 testes em test_slugify.py
  - "Olá Mundo" → "ola-mundo"
  - "  Espaço extra  " → "espaco-extra"
  - "Já!!" → "ja"
  - "" → ""
rodando pytest... 4 failed (módulo slugify não existe) ✓ esperado

🟢 Green: criando slugify.py com unicodedata + re.sub
rodando pytest... 4 passed ✓

♻️ Refactor: extraindo etapas em funções nomeadas
  _strip_accents(s), _to_kebab(s)
rodando pytest após cada mudança... 4 passed ✓
pronto.

When a feature touches several layers (UI, API, DB), there are two ways to tackle it: horizontally (builds the entire DB, then the entire API, then the entire UI) or vertically (one feature end to end, then the next). With an agent, vertical slices always win.

Vertical slice = you can run it and see it working at the end of each slice. Horizontal = you only discover that everything is wrong when you put it all together at the end.

VERTICAL (recomendado)              HORIZONTAL (evitar)
┌──────┬──────┬──────┐               ┌──────────────────┐
│  UI  │  UI  │  UI  │               │       UI         │  ← slice 3
├──────┼──────┼──────┤               ├──────────────────┤
│ API  │ API  │ API  │               │       API        │  ← slice 2
├──────┼──────┼──────┤               ├──────────────────┤
│  DB  │  DB  │  DB  │               │       DB         │  ← slice 1
└──────┴──────┴──────┘               └──────────────────┘
 feat1  feat2  feat3                   tudo de uma vez

cada slice roda           só roda no fim de tudo
end-to-end                (e geralmente quebra)

TDD works well for new work. But bugs in existing code—especially intermittent ones, ones that only happen in production, ones no one understands—call for a different approach. The /diagnose is a six-step loop designed for this.

The most costly debugging mistake is skipping the reproduction step. The agent reads the stack trace, sees a familiar name, and starts writing a fix. Sometimes it works—but when it doesn’t, no one notices, because no one set up the scenario to verify it.

A bug that came back is the most frustrating of all — because it has already been fixed once. The rule is simple: every fixed bug becomes a regression test. If you don’t have a test for the case, it will come back.

The best time to write this test is right after you’ve fixed the bug—the scenario is fresh, you know exactly what was failing, and the reproduction already exists (you used it in /diagnose).

# Bug reportado em produção: "comentário com emoji 🎉 quebrava a API"
# Causa encontrada via /diagnose: encoding latin-1 num middleware antigo
# Fix aplicado: trocar pra utf-8
# Teste de regressão (commit junto com o fix):

def test_comentario_com_emoji_nao_quebra_api():
    """Regression: bug #482 — emoji no body causava UnicodeDecodeError."""
    payload = {"texto": "Show de bola 🎉🚀"}

    response = client.post("/api/comentarios", json=payload)

    assert response.status_code == 201
    assert response.json()["texto"] == "Show de bola 🎉🚀"

# Anote no docstring: número do bug, causa raiz. Quando o teste falhar
# de novo em 6 meses, quem ler vai entender o porquê de existir.

The two loops don't compete—they work together. /tdd is for new work when you know what you want. /diagnose is for understanding why something existing isn't doing what it should. Complex bugs almost always involve both.

Pick an open bug in your project — any one, preferably one you've been avoiding because "it's weird." Run /diagnose and document each step. By the end, you'll have the bug fixed AND review material to understand how agents handle bugs.