diff --git a/GATES.md b/GATES.md index dd79756..e05c9c1 100644 --- a/GATES.md +++ b/GATES.md @@ -1,23 +1,27 @@ -# Gates: AI For Dummies standalone presentation +# Gates: Rules and enforcement case study -OWNS: index.html, styles.css, app.js, docs/references/**, scripts/** +OWNS: rules/**, index.html, README.md, docs/operations-guide.md, scripts/verify.mjs -Scope: Deliver a standalone presentation teaching skills, model routing, subagents, and worktrees. +Scope: Add a concise bilingual page that explains how `netcracker/interview` +combines agent context, reusable skills, CLI checks, Husky hooks, and PR review. -- [ ] G1: bundled research references and required lesson topics exist +- [ ] G1: separate rules page presents repository-grounded summary and examples CHECK: node scripts/verify.mjs - EXPECT: content verification passed + EXPECT: rules content verification passed EVIDENCE: pending -- [ ] G2: the standalone presentation has working phase interaction +- [ ] G2: pipeline, skill examples, language switch, and copy controls work CHECK: node scripts/verify.mjs - EXPECT: interaction verification passed + EXPECT: rules interaction verification passed EVIDENCE: pending -- [ ] G3: the document is valid and has no external runtime dependency +- [ ] G3: page is dependency-free and linked from the main presentation CHECK: node scripts/verify.mjs - EXPECT: standalone verification passed + EXPECT: rules standalone verification passed EVIDENCE: pending -- [ ] G4: responsive and accessibility presentation review +- [ ] G4: mobile, Full HD, and 4K browser checks pass without overflow or errors + EVIDENCE: pending + +- [ ] G5: main and pages point to one commit and the live rules endpoint serves it EVIDENCE: pending diff --git a/app.js b/app.js index 0f69dec..919de04 100644 --- a/app.js +++ b/app.js @@ -208,7 +208,7 @@ const translations = { '.failure-map .section-label span:nth-child(1)': 'Por que a fronteira importa', '.failure-map .section-label span:nth-child(2)': 'uma tarefa vaga / três falhas previsíveis', '.failure-grid article:nth-child(1) strong': 'Sopa de contexto', '.failure-grid article:nth-child(1) p': 'Cada worker lê tudo. Ninguém sabe quais fatos são essenciais.', '.failure-grid article:nth-child(2) strong': 'Colisão de branches', '.failure-grid article:nth-child(2) p': 'Dois agentes usam o mesmo checkout. O caminho mais rápido vira resolução de conflitos.', '.failure-grid article:nth-child(3) strong': 'Desvio confiante', '.failure-grid article:nth-child(3) p': 'O diff parece ótimo, mas ninguém verifica se resolveu o problema original.', '.workflow .eyebrow': 'O ciclo de subagentes', '#workflow-title': 'Clique em uma fase.
Veja a passagem.', '.workflow .copy > p:last-child': 'Delegar é mover uma tarefa delimitada para um contexto menor — não abrir mão da responsabilidade.', '.handoff .section-label span:nth-child(1)': 'O que atravessa contextos', '.handoff .section-label span:nth-child(2)': 'brief → diff → evidência', '.handoff thead th:nth-child(1)': 'Pacote', '.handoff thead th:nth-child(2)': 'Contém', '.handoff thead th:nth-child(3)': 'Por que importa', '.worktrees .eyebrow': 'Git worktrees', '.worktrees h2': 'Uma branch
por mão.', '.worktree-intro > p:nth-of-type(2)': 'Um worktree é outro diretório ligado ao mesmo repositório. Cada agente recebe seu próprio checkout e índice; o histórico continua compartilhado.', '.worktree-intro .interaction-hint': 'Selecione um nó para inspecionar checkout, responsável e próxima ação.', '.tree-toolbar > span:first-child': 'topologia do repositório', '.tree-live': ' 4 checkouts', '.tree-node.root span': 'RAIZ', '.tree-node.ui span': 'AGENTE DE UI', '.tree-node.tests span': 'AGENTE DE TESTES', '.tree-node.docs span': 'AGENTE DE DOCS', '.tree-node.root small': '● limpo', '.tree-node.ui small': '3 arquivos · trabalhando', '.tree-node.tests small': '8 verificações · pronto', '.tree-node.docs small': '2 páginas · revisão', '.routing .eyebrow': 'Roteamento de modelos', '.routing h2': 'Não pague por
raciocínio onde precisa
de ritmo.', '.routing .interaction-hint': 'Escolha um trabalho para entender por que o perfil do modelo muda.', '.route-table .head span:nth-child(1)': 'Trabalho', '.route-table .head span:nth-child(2)': 'Perfil', '.route-table .head span:nth-child(3)': 'Formato do prompt', '.route-table [data-route="plan"] strong': 'Planejar', '.route-table [data-route="build"] strong': 'Construir', '.route-table [data-route="explore"] strong': 'Explorar', '.route-table [data-route="review"] strong': 'Revisar', '.skills .eyebrow': 'Skills', '.skills h2': 'Escreva do jeito certo
uma vez.', '.skills > div:first-child > p': 'Uma skill é um procedimento reutilizável. Ela pode carregar instruções, referências, scripts e assets. Não é memória mágica e não substitui critérios de aceitação.', - '.skill-principles span:nth-child(1)': '01 / defina o gatilho', '.skill-principles span:nth-child(2)': '02 / carregue detalhes sob demanda', '.skill-principles span:nth-child(3)': '03 / devolva evidências', '.skill-package > span': 'PACOTE DE SKILL', '.skill-catalog .section-label span:nth-child(1)': 'Skills comuns', '.skill-catalog .section-label span:nth-child(2)': 'escolha o comportamento antes do modelo', '.catalog-intro .eyebrow': 'O kit de campo', '.catalog-intro h2': 'Trabalhos diferentes.
Instintos diferentes.', '.catalog-intro > p': 'Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para inspecionar sua regra operacional.', '[data-common-skill="ponytail"] span': 'SIMPLIFICAR', '[data-common-skill="ponytail"] small': 'código mínimo que funciona', '[data-common-skill="caveman"] span': 'COMUNICAR', '[data-common-skill="caveman"] small': 'sinal sem excesso', '[data-common-skill="unlazy"] span': 'CONCLUIR', '[data-common-skill="unlazy"] small': 'gates e evidências', '[data-common-skill="research"] span': 'INVESTIGAR', '[data-common-skill="research"] small': 'fontes primárias primeiro', '[data-common-skill="debug"] span': 'DIAGNOSTICAR', '[data-common-skill="debug"] small': 'ciclo curto de feedback', '[data-common-skill="review"] span': 'REVISAR', '[data-common-skill="review"] small': 'padrões × especificação', '[data-common-skill="tokens"] span': 'ECONOMIZAR', '[data-common-skill="tokens"] small': 'comprima saídas ruidosas', '.skill-loadout > span': 'UM LOADOUT PRÁTICO', '.skill-loadout > div': 'PLANEJAR unlazy CONSTRUIR ponytail-lite DIAGNOSTICAR diagnosing-bugs REPORTAR caveman', '.rule span': 'O PAPEL HUMANO', '.rule strong': 'O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.', '.callout span': 'COMECE AQUI', '.callout strong': 'Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.', '.sources .section-label span:nth-child(1)': 'Continue aprendendo', '.sources .section-label span:nth-child(2)': '12 novas leituras + documentação primária', '.sources p': 'Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes. Referências primárias → Trilha com 12 leituras →' + '.skill-principles span:nth-child(1)': '01 / defina o gatilho', '.skill-principles span:nth-child(2)': '02 / carregue detalhes sob demanda', '.skill-principles span:nth-child(3)': '03 / devolva evidências', '.skill-package > span': 'PACOTE DE SKILL', '.skill-catalog .section-label span:nth-child(1)': 'Skills comuns', '.skill-catalog .section-label span:nth-child(2)': 'escolha o comportamento antes do modelo', '.catalog-intro .eyebrow': 'O kit de campo', '.catalog-intro h2': 'Trabalhos diferentes.
Instintos diferentes.', '.catalog-intro > p': 'Uma skill muda como o agente aborda o trabalho. Algumas moldam a comunicação. Outras impõem pesquisa, diagnóstico, revisão ou disciplina de conclusão. Selecione uma para inspecionar sua regra operacional.', '[data-common-skill="ponytail"] span': 'SIMPLIFICAR', '[data-common-skill="ponytail"] small': 'código mínimo que funciona', '[data-common-skill="caveman"] span': 'COMUNICAR', '[data-common-skill="caveman"] small': 'sinal sem excesso', '[data-common-skill="unlazy"] span': 'CONCLUIR', '[data-common-skill="unlazy"] small': 'gates e evidências', '[data-common-skill="research"] span': 'INVESTIGAR', '[data-common-skill="research"] small': 'fontes primárias primeiro', '[data-common-skill="debug"] span': 'DIAGNOSTICAR', '[data-common-skill="debug"] small': 'ciclo curto de feedback', '[data-common-skill="review"] span': 'REVISAR', '[data-common-skill="review"] small': 'padrões × especificação', '[data-common-skill="tokens"] span': 'ECONOMIZAR', '[data-common-skill="tokens"] small': 'comprima saídas ruidosas', '.skill-loadout > span': 'UM LOADOUT PRÁTICO', '.skill-loadout > div': 'PLANEJAR unlazy CONSTRUIR ponytail-lite DIAGNOSTICAR diagnosing-bugs REPORTAR caveman', '.rule span': 'O PAPEL HUMANO', '.rule strong': 'O agente pode ser autônomo na execução. Intenção, limites e evidências continuam sendo seus.', '.callout span': 'COMECE AQUI', '.callout strong': 'Comece com um agente e uma skill. Adicione paralelismo apenas quando as tarefas forem realmente independentes.', '.sources .section-label span:nth-child(1)': 'Continue aprendendo', '.sources .section-label span:nth-child(2)': '12 novas leituras + documentação primária', '.sources p': 'Aprofunde com documentação oficial, casos de produção, Medium e fluxos de praticantes. Estudo de caso sobre regras e enforcement → Referências primárias → Trilha com 12 leituras →' } }; diff --git a/index.html b/index.html index 1fbb68a..726e9c3 100644 --- a/index.html +++ b/index.html @@ -25,12 +25,12 @@

Skills

Write the right way
once.

A skill is a reusable procedure. It can carry instructions, references, scripts, and assets. It is not magical memory, and it does not replace acceptance criteria.

01 / trigger clearly02 / load detail on demand03 / return evidence
SKILL PACKAGE
name: review-ui · check focus, mobile, reduced motion · run verification · return evidence
Create a skillrepeatable pain → reusable judgment

The skill forge

Teach the decision.
Keep the context light.

Do not package everything you know. Capture the non-obvious choices that repeatedly improve an outcome, then prove the skill changes behavior.

AFTER REAL USE
observe failuresharpen one ruleretest behaviorkeep it narrow
Common skillschoose behavior before model

The field kit

Different jobs.
Different instincts.

A skill changes how an agent approaches work. Some shape communication. Others enforce research, debugging, review, or completion discipline. Select one to inspect its operating rule and verified source.

ONE PRACTICAL LOADOUT
PLAN unlazy BUILD ponytail-lite DEBUG diagnosing-bugs REPORT caveman
INSTALL PACKAsk your coding agent to verify, install, and validate the skills.
-
Hands-on10 minutes / one missing feature

Tiny Tasks lab

Same task.
Better operating system.

Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.

THE MISSING FEATUREAdd All / Open / Done filters that survive reload and browser navigation.
STACK HTML · CSS · JavaScript DEPENDENCIES none FILES 3
RUN AGood prompt
Clear context · constraints · acceptance · evidence
RUN BGood prompt + skills
Same contract · explicit working methods · stronger proof
COMPARE THE RUNS
01 Files changed
02 New dependencies
03 Checks actually run
04 Evidence returned

+
Hands-on10 minutes / one missing feature

Tiny Tasks lab

Same task.
Better operating system.

Start with a deliberately incomplete static task board. Run one prompt as written, reset, then run the skill-enabled version. Compare diff size, verification evidence, and unnecessary complexity.

THE MISSING FEATUREAdd All / Open / Done filters that survive reload and browser navigation.
STACK HTML · CSS · JavaScript DEPENDENCIES none FILES 3
RUN AGood prompt
Clear context · constraints · acceptance · evidence
RUN BGood prompt + skills
Same contract · explicit working methods · stronger proof
COMPARE THE RUNS
01 Files changed
02 New dependencies
03 Checks actually run
04 Evidence returned

Verificationrun each gate separately

Checks become evidence

Three layers.
Run each one alone.

Run a gate on its own line, print its exit code, attach the output. The result is the deliverable.

01 · STATIC

Lint and types

Format, lint, type-check. Fast and scoped to one file. Run on every save.

pnpm lint; echo "lint=$?" pnpm typecheck; echo "typecheck=$?"
02 · BEHAVIOR

Unit and contract

Tests that repeat. Run before claiming done.

pnpm test; echo "test=$?" cd services/api && go test ./...
03 · INTEGRATION

Real UI and API

Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile overflow and a missing 404.

pnpm check:ui; echo "ui=$?" -TURBO_FORCE=true pnpm e2e
FOUR WAYS A GREEN REPORT IS FALSE
1
Pipe a gate

tail, grep, or head hide the real exit code — a pipeline returns the last command's status.

2
Swallow a rejection

A silent .catch(() => {}) hides a panic, an upstream limit, or a partial failure.

3
Trust the cache

Turbo caches results. A gate that "passes" may not have run — use TURBO_FORCE=true.

4
Skip the third layer

Lint and unit can both be green while the page breaks on mobile and the API never returns 404.

RUN IT YOURSELF · two labs, under 10 minutes each
+TURBO_FORCE=true pnpm e2e
FOUR WAYS A GREEN REPORT IS FALSE
1
Pipe a gate

tail, grep, or head hide the real exit code — a pipeline returns the last command's status.

2
Swallow a rejection

A silent .catch(() => {}) hides a panic, an upstream limit, or a partial failure.

3
Trust the cache

Turbo caches results. A gate that "passes" may not have run — use TURBO_FORCE=true.

4
Skip the third layer

Lint and unit can both be green while the page breaks on mobile and the API never returns 404.

RUN IT YOURSELF · two labs, under 10 minutes each
Path A · verification lab

Fill the four-row comparison strip on the starter. Run A naively, Run B with $gate-discipline and $webapp-testing.

Open the starter →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starter
Path B · rules lab

Toggle every rule off, run the prompt. Toggle every rule on, run it again. Compare diff size, gate invocations, and the names of checks the agent names back.

Open the rules lab →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules
Keep learning12 new readings + primary docs

Go deeper with official documentation, production case studies, Medium, and practitioner workflows. Rules and enforcement case study → Primary references → 12-part reading path →