From 8f8230475882f48b1becf7437942e2ddfe49a5bb Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sun, 6 Sep 2026 00:02:51 +0000 Subject: [PATCH 1/4] fix(full-guide): restore omitted guide sections Restore the builder, hands-on, and verification content lost by task 15d, including the legacy bilingual pairs.\n\nDo not alter legacy files or verification assertions. --- src/pages/full-guide.astro | 274 +++++++++++++++++++++++++++++++++---- 1 file changed, 247 insertions(+), 27 deletions(-) diff --git a/src/pages/full-guide.astro b/src/pages/full-guide.astro index 6c43689..f34ecf1 100644 --- a/src/pages/full-guide.astro +++ b/src/pages/full-guide.astro @@ -82,6 +82,31 @@ const labels = { source: { en: 'GITHUB SOURCE ↗', pt: 'FONTE NO GITHUB ↗' }, }, }; +const builderSteps: Record< + string, + { title: { en: string; pt: string }; tagline: { en: string; pt: string } } +> = { + observe: { + title: { en: 'Observe', pt: 'Observar' }, + tagline: { en: 'find repeated friction', pt: 'encontre atrito repetido' }, + }, + trigger: { + title: { en: 'Define trigger', pt: 'Definir gatilho' }, + tagline: { en: 'route precisely', pt: 'roteie com precisão' }, + }, + scaffold: { + title: { en: 'Choose anatomy', pt: 'Escolher anatomia' }, + tagline: { en: 'only needed files', pt: 'apenas arquivos necessários' }, + }, + write: { + title: { en: 'Write guidance', pt: 'Escrever orientação' }, + tagline: { en: 'decisions, not trivia', pt: 'decisões, não trivialidades' }, + }, + validate: { + title: { en: 'Validate', pt: 'Validar' }, + tagline: { en: 'test real behavior', pt: 'teste comportamento real' }, + }, +}; const selectorData = { phases, workers, @@ -690,7 +715,16 @@ const base = import.meta.env.BASE_URL; >MEDIUMdefault start - )) + ['observe', 'trigger', 'scaffold', 'write', 'validate'].map((id) => { + const step = skillWorkflow[id]; + return ( + + ); + }) }
@@ -819,7 +893,39 @@ const base = import.meta.env.BASE_URL; > -
+ +
+ AFTER REAL USE
+ observe failure→sharpen one rule→retest behavior→keep it narrow +
@@ -955,14 +1061,38 @@ const base = import.meta.env.BASE_URL;

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

- Open the starter →Open the rules lab → +
+ Open the starter →Clone from Gitea → +
+ Open the rules lab →Clone from Gitea → +
+
+ THE MISSING FEATUREAdd All / Open / Done filters that survive reload and browser navigation.
+ STACK HTML · CSS · JavaScript DEPENDENCIES none FILES 3 +
@@ -981,6 +1111,33 @@ const base = import.meta.env.BASE_URL; Same contract · explicit working methods · stronger proof
+
+ COMPARE THE RUNS
+ 01 + Files changed +
+ 02 + New dependencies +
+ 03 + Checks actually run +
+ 04 + Evidence returned +

@@ -1017,21 +1174,84 @@ const base = import.meta.env.BASE_URL;
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. -

pnpm lint; echo "lint=$?" + 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=$?" +

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

Real UI and API

- Drive the actual UI, API, or browser. -

pnpm check:ui; echo "ui=$?" + 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
+ 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/starterPath 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 starter →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules +
+
From 9486188983097302e055a6109f8c5fb66341a6bb Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sun, 6 Sep 2026 00:26:21 +0000 Subject: [PATCH 2/4] fix(full-guide): restore Portuguese guide copy --- src/components/islands/CopyPrompt.astro | 3 +- src/pages/full-guide.astro | 179 ++++++++++++++++++------ 2 files changed, 142 insertions(+), 40 deletions(-) diff --git a/src/components/islands/CopyPrompt.astro b/src/components/islands/CopyPrompt.astro index 5d49f74..be52ea4 100644 --- a/src/components/islands/CopyPrompt.astro +++ b/src/components/islands/CopyPrompt.astro @@ -121,7 +121,8 @@ const { target } = Astro.props; if (!id) return; const target = document.querySelector('#' + id); if (!target) return; - const value = target.textContent || ''; + const visible = target.querySelector(':scope > [data-language-content]:not([hidden])'); + const value = visible?.textContent || target.textContent || ''; if ( typeof navigator !== 'undefined' && diff --git a/src/pages/full-guide.astro b/src/pages/full-guide.astro index f34ecf1..3d1c1ed 100644 --- a/src/pages/full-guide.astro +++ b/src/pages/full-guide.astro @@ -260,7 +260,7 @@ const base = import.meta.env.BASE_URL; @@ -443,7 +443,8 @@ const base = import.meta.env.BASE_URL; data-language-content="pt" hidden>Clique em uma fase.
Veja a passagem. -

+ +

Delegation means moving one bounded task into a smaller context—not giving away responsibility.

- Skills + Skills

Write the right way
once.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. +

01 / trigger clearly
- Create a skillrepeatable pain → reusable judgment + Create a skillrepeatable pain → reusable judgment

The skill forge + hidden>A forja de skills

Teach the decision.
Keep the context light. + >Ensine a decisão.
Mantenha o contexto leve.

+ resultados repetidamente e prove que a skill muda o comportamento.

- INSTALL PACKAsk your coding agent to verify, install, and validate the skills.INSTALL PACKAsk your coding agent to verify, install, and validate the skills.
- 
{install.en}
- Review every source before installation. Existing local skills must be preserved. + 
{install.en}
+ Review every source before installation. Existing local skills must be preserved.

- Hands-on10 minutes / one missing feature + Hands-on10 minutes / one missing feature
-

Tiny Tasks lab

- Same task.
Better operating system. +

+ 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. +

- Open the starter →Open the starter →Clone from Gitea → + class="starter-link starter-link-source" + >Clone from Gitea →
- Open the rules lab →Open the rules lab →Clone from Gitea → + class="starter-link starter-link-source" + >Clone from Gitea →
@@ -1091,24 +1161,45 @@ const base = import.meta.env.BASE_URL; STACK HTML · CSS · JavaScript DEPENDENCIES none FILES 3 + >STACK HTML · CSS · JavaScript DEPENDÊNCIAS nenhuma ARQUIVOS 3
-
RUN AGood prompt
- 
{handsOn.en.basic}
- Clear context · constraints · acceptance · evidence +
+ RUN AGood prompt +
+ 
{handsOn.en.basic}
+ Clear context · constraints · acceptance · evidence
-
RUN BGood prompt + skills
- 
{handsOn.en.skills}
- Same contract · explicit working methods · stronger proof +
+ RUN BGood prompt + skills +
+ 
{handsOn.en.skills}
+ Same contract · explicit working methods · stronger proof
@@ -1121,22 +1212,26 @@ const base = import.meta.env.BASE_URL; 01 Files changed + hidden>Arquivos alterados
02 New dependencies + hidden>Novas dependências
03 Checks actually run + hidden>Checks executados
04 Evidence returned + hidden>Evidências retornadas

@@ -1246,10 +1341,16 @@ const base = import.meta.env.BASE_URL; >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 starter →Open the rules lab →Clone ↗ git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules + > From c9796a3e7f6adb5a853088f4daed6ffd896fe1f8 Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sun, 6 Sep 2026 00:33:44 +0000 Subject: [PATCH 3/4] test: count and order rendered spans, not just their presence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rendered-text diff compared two *sets* of strings, so it stayed at "missing 0 · extra 0" while the built page painted a string a different number of times, or in a different place. That is the same shape of hole that let task 15d ship a full-guide missing a fifth of its content behind a green gate. Three changes: - tally occurrences instead of set membership, so a string the legacy page paints twice has to be painted twice here; - compare the sequences positionally and report the first divergence, which is what caught the Portuguese eyebrow and the reordered skill deck fixed in the next commit; - fail loudly on a non-200 response. A 404 rendered as four spans of python's error page and the diff then reported the entire route as missing, which reads exactly like a real regression. Two robustness fixes behind those: ask the kernel for a free port rather than pinning 4196/4197 (back-to-back runs collided with the previous run's server, which was still holding the port after its staging directory had been deleted), and read the DOM until two consecutive reads agree instead of once after a fixed wait. Co-Authored-By: Claude Opus 5 --- .agents/scripts/rendered-text-diff.mjs | 84 +++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 10 deletions(-) diff --git a/.agents/scripts/rendered-text-diff.mjs b/.agents/scripts/rendered-text-diff.mjs index 870775a..6e239e4 100644 --- a/.agents/scripts/rendered-text-diff.mjs +++ b/.agents/scripts/rendered-text-diff.mjs @@ -21,6 +21,7 @@ import { spawn } from 'node:child_process'; import { cpSync, mkdtempSync, rmSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; +import { createServer } from 'node:net'; import { chromium } from 'playwright'; // `index` is the landing page: it lives at the repository root, not in a @@ -43,9 +44,26 @@ const astroPath = route === 'index' ? '' : `${route}/`; const staging = mkdtempSync(join(tmpdir(), 'af-rtd-')); cpSync('dist', join(staging, 'ai-for-dummies'), { recursive: true }); +// Ask the kernel for a free port rather than pinning one. Back-to-back runs +// used to collide: the previous run's server was still holding the fixed port +// while its staging directory had already been deleted, so every page came +// back as a 404 and the diff reported the whole route missing. +const freePort = () => + new Promise((resolve, reject) => { + const probe = createServer(); + probe.on('error', reject); + probe.listen(0, '127.0.0.1', () => { + const { port } = probe.address(); + probe.close(() => resolve(port)); + }); + }); + +const legacyPort = await freePort(); +const astroPort = await freePort(); + const serve = (dir, port) => spawn('python3', ['-m', 'http.server', String(port), '-d', dir], { stdio: 'ignore' }); -const servers = [serve('.', 4197), serve(staging, 4196)]; +const servers = [serve('.', legacyPort), serve(staging, astroPort)]; const stop = () => { servers.forEach((s) => s.kill()); rmSync(staging, { recursive: true, force: true }); @@ -77,7 +95,13 @@ try { const browser = await chromium.launch(); const grab = async (url) => { const page = await browser.newPage({ viewport: { width: 1400, height: 1000 } }); - await page.goto(url, { waitUntil: 'load' }); + const response = await page.goto(url, { waitUntil: 'load' }); + // A 404 renders as four spans of python's error page and the diff then + // reports the entire route as missing, which reads exactly like a real + // regression. Fail loudly instead. + if (!response || !response.ok()) { + throw new Error(`${url} returned ${response ? response.status() : 'no response'}`); + } // The islands hydrate and render their initial panel on load; without this // every panel's copy reads as missing. await page.waitForTimeout(1200); @@ -87,23 +111,58 @@ try { await toggle.click(); await page.waitForTimeout(1200); } - const spans = await page.evaluate(visibleText); + // Islands hydrate at their own pace, and the language toggle repaints in + // more than one frame. A single read after a fixed wait is flaky, so read + // until two consecutive reads agree. + let spans = await page.evaluate(visibleText); + for (let i = 0; i < 10; i += 1) { + await page.waitForTimeout(300); + const next = await page.evaluate(visibleText); + if (next.length === spans.length && next.every((span, j) => span === spans[j])) { + spans = next; + break; + } + spans = next; + } await page.close(); return spans; }; - const legacy = await grab(`http://localhost:4197/${legacyPath}`); - const astro = await grab(`http://localhost:4196/ai-for-dummies/${astroPath}`); + const legacy = await grab(`http://localhost:${legacyPort}/${legacyPath}`); + const astro = await grab(`http://localhost:${astroPort}/ai-for-dummies/${astroPath}`); await browser.close(); - const rendered = new Set(astro); - const missing = legacy.filter((span) => !rendered.has(span)); + // Count occurrences, not membership. A set comparison reports zero when a + // string the legacy page paints four times is painted three times here -- + // exactly the kind of near-miss that got past the earlier checks. + const tally = (spans) => { + const counts = new Map(); + for (const span of spans) counts.set(span, (counts.get(span) || 0) + 1); + return counts; + }; + + const legacyCounts = tally(legacy); + const astroCounts = tally(astro); + + const missing = []; + for (const [span, count] of legacyCounts) { + const short = count - (astroCounts.get(span) || 0); + for (let i = 0; i < short; i += 1) missing.push(span); + } // Both directions. A string the Astro page paints and the legacy page does // not is just as wrong: it means a translation was invented, or an English // string was left standing where the legacy page swaps it. - const legacySpans = new Set(legacy); - const extra = astro.filter((span) => !legacySpans.has(span)); + const extra = []; + for (const [span, count] of astroCounts) { + const over = count - (legacyCounts.get(span) || 0); + for (let i = 0; i < over; i += 1) extra.push(span); + } + + // Order counts too. Both pages can paint the same strings while a block + // sits in the wrong place -- the Portuguese eyebrow, or a reordered card + // deck -- and a count-only comparison calls that clean. + const firstOutOfOrder = legacy.findIndex((span, i) => astro[i] !== span); const mode = portuguese ? 'pt' : 'en'; console.log( @@ -111,7 +170,12 @@ try { ); for (const span of missing) console.log(` - ${span}`); for (const span of extra) console.log(` + ${span}`); - process.exitCode = missing.length === 0 && extra.length === 0 ? 0 : 1; + if (firstOutOfOrder !== -1) { + console.log(` order diverges at span ${firstOutOfOrder}`); + console.log(` legacy: ${legacy[firstOutOfOrder]}`); + console.log(` astro: ${astro[firstOutOfOrder]}`); + } + process.exitCode = missing.length === 0 && extra.length === 0 && firstOutOfOrder === -1 ? 0 : 1; } finally { stop(); } From 429b4e2e87b7655f798c5264f4b4a4e21974935a Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sun, 6 Sep 2026 00:33:56 +0000 Subject: [PATCH 4/4] fix(full-guide): match the legacy Portuguese order, and pin deck order Two defects the order-sensitive rendered-text diff surfaced. Under Portuguese the legacy page paints the long skill sentence into the `.skills` eyebrow, above the heading, because its `.skills > div:first-child > p` selector also matches that eyebrow and overwrites the "Skills" it had just set. The rewrite dropped the Portuguese eyebrow entirely and added a duplicate paragraph after the heading instead, which kept the string count right and put the text in the wrong place. Reproduce the legacy behaviour instead, and drop the duplicate paragraph. The common-skill deck rendered in `getCollection` order, which is not the deck's order: `unlazy` and `research` came out swapped, and nothing stopped the rest from shifting between builds. Sort by the card number so the tabs stay 01..07 as the legacy page has them. Co-Authored-By: Claude Opus 5 --- src/pages/full-guide.astro | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/src/pages/full-guide.astro b/src/pages/full-guide.astro index 3d1c1ed..514f7e2 100644 --- a/src/pages/full-guide.astro +++ b/src/pages/full-guide.astro @@ -55,6 +55,9 @@ const efforts = toRecord(effortEntries); const skillFiles = toRecord(skillFileEntries); const skillWorkflow = toRecord(workflowEntries); const commonSkills = toRecord(commonSkillEntries); +const sortedCommonSkills = Object.values(commonSkills).sort((a, b) => + a.number.localeCompare(b.number), +); const handsOn = promptEntries.find(({ data }) => data.id === 'tiny-tasks')?.data; const install = installEntries.find(({ data }) => data.id === 'install')?.data; if (!handsOn || !install) throw new Error('full-guide content collections are incomplete'); @@ -766,7 +769,16 @@ const base = import.meta.env.BASE_URL;

- Skills + { + /* Under Portuguese the legacy page paints the long skill sentence + here, not "Skills": its `.skills > div:first-child > p` selector + also matches this eyebrow and overwrites it. Reproduced on + purpose -- see .agents/rules/content-i18n.md. */ + } + Skills

Write the right way
once.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. -

01 / trigger clearly
{ - Object.values(commonSkills).map((skill) => ( + /* getCollection's order is not the deck's order. Sort by the + card number so the tabs stay 01..07 as the legacy page has + them, instead of shifting between builds. */ + sortedCommonSkills.map((skill) => (