The complete plan for patients to keep going with treatment

🦵 The system the plan produces

Scheduling for evaluations, sessions and RPG (postural re-education), no double booking, automatic confirmation and a waitlist. At the center, the treatment plan: planned against completed sessions, with a dropout alert and a re-evaluation alert. Python 3 with the standard library only and SQLite, one clinic per installation.

📦 The kit

A 26-section specification (0 to 25), 98 black-box tests, 21 decisions already proposed, a map to Raio-X, prompts for /goal and for the headless loop, and the guardrails that freeze the contract. An adversarial validator already went through everything and found 9 problems, 3 of which would have blocked an honest implementer.

📈 Source: Raio-X de Margem

No-shows, patients who do not come back and indicated treatment that never starts are the leaks the plan attacks. The system hands eight monthly numbers to the dashboard of Raio-X de Margem, the source of the business rules and of the professional-council guardrail.

🧭 The bot only explains what is prescribed

It explains an exercise only if the physical therapist prescribed it to that patient. Anything else gets "talk to your physical therapist" and a human attendant. It never gives a diagnosis, medication or clinical advice.

🚨 Severe pain and warning signs

Pain from 7 to 10, or a warning word (numbness, tingling, loss of strength, fever, a fall, swelling and others), opens the human queue at high priority and alerts the team on Telegram. The reply names the physical therapist and 192 (the Brazilian emergency number) and never gives advice.

🔒 LGPD and COFFITO

Health data is sensitive: export and erase also cover the plan, the prescription and the adherence and pain records. A campaign only goes to people who consented and passes the COFFITO 424/2013 guardrail, sourced from the Raio-X research. LGPD (the Brazilian data protection law), COFFITO (the Brazilian physical therapy council) and 192 are Brazilian.

Patient

In the chat or on WhatsApp the patient books, confirms with 1 or 2, asks como faço a ponte? (how do I do the bridge; only if it was prescribed), turns on the reminder with lembrete 19:00 (or sem lembrete to turn it off), replies fiz (did it), nao fiz (did not) or dor 5 (pain 5), gets FAQ answers, asks for an attendant and sends "PARAR" (stop) when they want no more messages.

Team on Telegram

Notices for new and cancelled bookings, and the commands /agenda, /alertas, /fila, /responder and /encerrar, also as a direct reply to the patient's message.

The /equipe page

With a token: schedule, patients, plans, prescriptions, adherence and pain, the exercise library, alerts, FAQ, records, blocked time and the human queue.

Treatment plan

A package of sessions per patient: planned, completed and remaining. Two missed sessions in a row (adjustable) become a dropout alert for the team; the patient gets no automatic message, because reaching out again is a human decision. When two sessions remain, a re-evaluation alert. Once the plan is completed, the follow-up is due 30 days after the last session.

Prescribed exercises and reminder

The physical therapist prescribes items (sets, repetitions, times a day, days of the week) and the patient receives the text with the link to each exercise. The daily reminder is opt-in: it only turns on when the patient asks, at the time they choose (default 19:00), and only on the prescribed days.

Adherence and pain

The patient replies fiz, nao fiz or pain from 0 to 10; there is one record per day and the last one wins. Weekly adherence is the days done divided by the days planned, Monday to Sunday, from the start of the prescription until today: 2 done out of 4 planned is 50%. The week's pain is the average of the records.

🎞️ Demo: an exercise animated with CSS only

Each exercise is an SVG animated with CSS only, no script and no SMIL, because the video render can only advance CSS animation. This is the bridge, from the specification's skeleton.

The 12 example exercises

Bridge, hamstring stretch, shoulder rotation with a stick, Codman pendulum, cervical retraction, cat-camel, wall squat, heel raise, side-lying hip abduction, modified plank, bird-dog and ankle mobility.

Each one has a public page /exercicios/<id> (steps, common mistakes, precautions, contraindications and "stop if"). On WhatsApp the patient gets a 4-second MP4 rendered with HyperFrames, a local build step (tools/render-exercicios); without the MP4, the link goes out instead. The movement is checked at level 4 by verificar-independente.py, which prints PULADO (skipped) when the tool is missing.

Python 3.10+ and pytest

The tests use pytest (a development tool). The application itself will have no dependencies.

# check
python3 --version
python3 -m pip install pytest

Claude Code or Codex

On a subscription, no paid API. For the headless loop, clone execucao-longa into ~/projetos.

# check
codex --version   # or: claude --version

Docker, Evolution and Telegram

Docker does the final build and the VPS deploy. An Evolution instance and a Telegram bot only if you want the channels; credentials live in .env.

# check
docker --version

98 acceptance tests

Black-box, over HTTP and the command line, in 12 files.

test_integracoes.py           16
test_agenda.py                12
test_conversa.py              10
test_cadastros.py              9
test_campanhas.py              9
test_lembretes.py              8
test_prescricao.py             8
test_exercicios.py             7
test_basico.py                 6
test_planos.py                 6
test_docker.py                 4
test_lgpd_raiox.py             3

A 26-section specification

docs/ESPECIFICACAO.md, sections 0 to 25: execution, clinica.json, scheduling rules, the HTTP API, a 12-rule conversation, waitlist, confirmation and follow-up, campaigns and the council guardrail, Raio-X, LGPD, records, WhatsApp, Telegram, Docker, treatment plans, the exercise library, prescription and reminders, adherence and pain, team alerts and the MP4 video. Medical records, Pix billing, insurance and claim denials (TISS) and several clinics on one server are explicitly out.

Guardrails against shortcuts

A frozen hash of tests/, pytest.ini, the specification and the verifiers. File scope: the agent only touches the code and its own records. No API key, no external API in the code and no SMIL or script in the SVGs. verificar-limites.sh checks all of this and prints LIMITES OK.

Independent verification

Level 4, hidden from the agent: it looks for fixture values in the code, brings up a clinic never seen, with every argument explicit, checks the SVG movement and the MP4 when the tools exist, and runs docker build and a healthcheck. Only that way does "98 passed" prove general logic.

21 decisions already proposed

Language, channels, the follow-up as a re-evaluation, the dropout alert, the opt-in reminder, adherence logged per day, pain and warning signs, the 12 exercises, CSS-only animation, what the bot explains, the COFFITO guardrail and Raio-X. Only the items marked ⚠ change the contract.

Validated by an adversarial agent

A validator that had not seen the planning checked tests against the specification, redid the arithmetic and tried to get around the guardrails. It found and fixed 9 problems: 3 blocked the run, 4 got in the way and 2 were cosmetic. The full account is in docs/VALIDACAO.md and each fix has a line in FALHAS.md.

The business rules come from Raio-X

No-shows, retention, a treatment plan that never starts and idle hours: docs/MAPA-RAIO-X.md links each leak of the clinica package to a v1 piece or to the reason it stays out. The COFFITO 424/2013 guardrail (price, promotion, free, testimonial, promise of results) is sourced from the Raio-X research. Details in the Raio-X de Margem guide.

Brazilian rules built in

LGPD for health data (confirmation, follow-up, prescription and reminder as health care; campaigns only with consent; export and erase), the COFFITO 424/2013 resolution for advertising and 192 for emergencies. Outside Brazil, swap in your local privacy law, professional council and emergency number.