Before you change anything

Before you change anything

The checklist. In order, and none of it is optional.

1. Know who you are

Claim a named agent identity from agents/. Read its ROLE.md and its MANDATE.md — they tell you which folders you may write in and which gate fails if you stray. If no identity fits what you have been asked to do, that is a message to the editor, not a licence to invent one.

2. Read, in this order

1. index.md and language.md — ten minutes, and they decide most naming questions before you hit them.
2. ../../CLAUDE.md — the seven rules. It outranks everything.
3. Your agent's ROLE.md and MANDATE.md.
4. The newest file in redacao/runs/ — what the last agent did, and what it left open.
5. Every entrada/ folder under redacao/correio/ — somebody may be waiting for you.

3. Find out whether anyone else is working here

More than one agent works in this repository. Before you start:

git fetch origin dev
git log --oneline HEAD..origin/dev      # did dev move while you were away?

If it moved, merge it in and rebuild before doing anything else. Resolve conflicts in generated files by re-running python3 build/tudo.py, never by hand — generated HTML is not a thing to merge.

4. Check the tree is green before you touch it

python3 build/tudo.py --so-portoes

If a gate is red on the tree as you found it, do not fix it. Write to redacao/correio/editor/entrada/ and stop. Fixing work that is not yours makes the next diff unreadable and hides whose failure it was.

5. Do the work

• New gates go in build/gates_artigos.py, never build/gates.py.
• Never hand-edit a generated .html; edit the builder.
• Never weaken a gate to get green. If a gate is wrong, that is a change of its own, with its own reasoning, and the editor sees it.
• Injection-test every gate you add. Break the thing on purpose, watch the gate fail, put it back. A gate that has never failed is a comment. Three of the gates in this repository were themselves buggy and only their own injection tests found it.

6. Build and check

python3 build/tudo.py                  # eleven steps in order, then the three gates
python3 build/tudo.py --render         # add the browser gate if you touched assets/components/

Run the whole thing, not the steps you think you need. build/entidades.py must run before anything that writes a page, because the pass that turns a name in prose into a link reads the file it produces — out of order nothing breaks, the site just quietly has fewer links than it should.

7. Record what you did

Write a run record in redacao/runs/<YYYY-MM-DDTHHMMSSZ>.json. The field names matter: the gates read this file.

{
  "quando": "2026-09-15T01:20:00Z",
  "agente": "foundry",
  "especie": "construcao",
  "modelo": "what you are",
  "pastas_alteradas": ["build/", "dados/"],
  "issues_movidos": [],
  "portoes": true,
  "versao": "v0.8.0"
}

departamento instead of especie if you are doing newsroom work as pesquisa, redacao, verificacao or editor — gate 12 then checks you stayed inside that department's folders. portoes: true means every gate printed OK; if you did not run one, it is not true.

8. Release

Every push to dev is a release.

git fetch origin dev                    # again — it may have moved while you worked

Pick the version number after that fetch, not before. Bump admin/build/version.txt, add a row to admin/versions.html in English saying what changed and why, commit with the subject site vX.Y.Z: <one sentence>, and push.

Never push with a red gate. Never force-push. Never rewrite history. Never push an empty commit.

9. Write a memo if the work was large

A substantial piece of work leaves a document in briefs/memos/ — what was built, what was decided, what was refused and why, and what is left. Not a changelog: the changelog says what changed, the memo says what you now know that the next agent would otherwise have to rediscover.

---

If you are blocked

redacao/correio/editor/entrada/<timestamp>__<agent>__<subject>.md, and stop. A run that stops honestly is a good run. Do not widen your own permissions, do not work around a gate, and do not fetch anything outside the sources you were sent for.

← The principles, and the gate that enforces each one · Releasing, and the four things that go quiet →

This page is rendered from docs/guidance/before-you-change.md by build/guia.py. The markdown is the source; edit that and rebuild. Nobody hand-edits this file.