netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(full-guide): restore omitted guide sections

Browse Source 
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.
This commit is contained in:
Marcos Paulo
2026-09-06 00:02:51 +00:00
parent a1eb1e79ea
commit 8f82304758
1 changed files with 247 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pages/full-guide.astro
+247 -27
View File
@@ -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;
></small
></button
><button class="active" data-effort="medium" role="tab" aria-selected="true"
>MEDIUM</button
><b
><span data-language-content="en">MEDIUM</span><span data-language-content="pt" hidden
>MÉDIO</span
></b
><small
><span data-language-content="en">default start</span><span
data-language-content="pt"
hidden>ponto inicial</span
></small
></button
><button data-effort="high" role="tab" aria-selected="false"
><b
><span data-language-content="en">HIGH</span><span data-language-content="pt" hidden
@@ -778,28 +812,68 @@ const base = import.meta.env.BASE_URL;
>
</div>
</article>
</div>
</div><pre><code>name: review-ui · check focus, mobile, reduced motion · run verification · return evidence</code></pre>
</section>
<section class="skill-builder" id="create-skill">
<div class="section-label">
<span>Create a skill</span><span>repeatable pain → reusable judgment</span>
</div><div class="builder-intro">
<div>
<p class="eyebrow">
<span data-language-content="en">The skill forge</span><span
data-language-content="pt"
hidden>A forja de skills</span>
</p><h2>
<span data-language-content="en"
>Teach the decision.<br />Keep the context <em>light.</em></span
><span data-language-content="pt" hidden
>Ensine a decisão.<br />Mantenha o contexto <em>leve.</em></span>
</h2>
</div><p>
<span data-language-content="en"
>Do not package everything you know. Capture the non-obvious choices that repeatedly
improve an outcome, then prove the skill changes behavior.</span
><span data-language-content="pt" hidden
>Não empacote tudo o que você sabe. Capture as escolhas não óbvias que melhoram
resultados repetidamente e prove que a skill muda o comportamento.</span>
</p>
</div><div class="builder-workbench">
<nav class="builder-steps" role="tablist" aria-label="Skill creation workflow">
{
Object.values(skillWorkflow).map((step) => (
<button
class:list={{ active: step.id === 'observe' }}
data-skill-step={step.id}
role="tab"
aria-selected={step.id === 'observe'}
>
<>
<b>{step.number}</b>
<span>{step.title.en}</span>
</>
</button>
))
['observe', 'trigger', 'scaffold', 'write', 'validate'].map((id) => {
const step = skillWorkflow[id];
return (
<button
class:list={{ active: step.id === 'observe' }}
data-skill-step={step.id}
role="tab"
aria-selected={step.id === 'observe'}
>
<>
<b>{step.number}</b>
<>
<span>
<>
<span data-language-content="en">{builderSteps[step.id].title.en}</span>
<span data-language-content="pt" hidden>
{builderSteps[step.id].title.pt}
</span>
</>
</span>
<small>
<>
<span data-language-content="en">{builderSteps[step.id].tagline.en}</span>
<span data-language-content="pt" hidden>
{builderSteps[step.id].tagline.pt}
</span>
</>
</small>
</>
</>
</button>
);
})
}
</nav><article class="builder-detail" id="builder-detail" aria-live="polite">
<header>
@@ -819,7 +893,39 @@ const base = import.meta.env.BASE_URL;
>
</div>
</footer>
</article>
</article><aside class="builder-artifact">
<div class="artifact-head">
<span
><span data-language-content="en">OUTPUT / SKILL PACKAGE</span><span
data-language-content="pt"
hidden>SAÍDA / PACOTE DE SKILL</span
></span
><i></i>
</div><pre
aria-label="Example skill structure"><code>review-ui/<br />├── SKILL.md<br />├── agents/<br />│ └── openai.yaml<br />├── references/<br />│ └── accessibility.md<br />└── scripts/<br /> └── verify.mjs</code></pre><div
class="artifact-command"
>
<span
><span data-language-content="en">VALIDATE</span><span
data-language-content="pt"
hidden>VALIDAR</span
></span
><code>quick_validate.py ./review-ui</code>
</div>
</aside>
</div><div class="builder-loop">
<span
><span data-language-content="en">AFTER REAL USE</span><span
data-language-content="pt"
hidden>APÓS USO REAL</span
></span
><div data-language-content="en">
<b>observe failure</b><i>→</i><b>sharpen one rule</b><i>→</i><b>retest behavior</b><i>→</i
><b>keep it narrow</b>
</div><div data-language-content="pt" hidden>
<b>observar falha</b><i>→</i><b>refinar uma regra</b><i>→</i><b>retestar comportamento</b
><i>→</i><b>manter estreita</b>
</div>
</div>
</section>
@@ -955,14 +1061,38 @@ const base = import.meta.env.BASE_URL;
</div><div>
<p>
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.
</p><div class="starter-links">
<a href={`${base}hands-on/starter/`} class="starter-link">Open the starter →</a><a
href={`${base}hands-on/rules/`}
class="starter-link">Open the rules lab →</a
>
<div class="starter-link-group">
<a href={`${base}hands-on/starter/`} class="starter-link">Open the starter →</a><a
href="https://git.marcospaulo.dev.br/netcracker/ai-for-dummies/src/branch/pages/hands-on/starter"
class="starter-link starter-link-source">Clone from Gitea →</a>
</div><div class="starter-link-group">
<a href={`${base}hands-on/rules/`} class="starter-link">Open the rules lab →</a><a
href="https://git.marcospaulo.dev.br/netcracker/ai-for-dummies/src/branch/pages/hands-on/rules"
class="starter-link starter-link-source">Clone from Gitea →</a>
</div>
</div>
</div>
</div><div class="exercise-brief">
<span
><span data-language-content="en">THE MISSING FEATURE</span><span
data-language-content="pt"
hidden>A FEATURE AUSENTE</span
></span
><strong
><span data-language-content="en"
>Add All / Open / Done filters that survive reload and browser navigation.</span
><span data-language-content="pt" hidden
>Adicione filtros Todos / Abertos / Concluídos que sobrevivem reload e navegação.</span
></strong
><div>
<span data-language-content="en"
><b>STACK</b> HTML · CSS · JavaScript <b>DEPENDENCIES</b> none <b>FILES</b> 3</span
><span data-language-content="pt" hidden
><b>STACK</b> HTML · CSS · JavaScript <b>DEPENDÊNCIAS</b> nenhuma <b>ARQUIVOS</b> 3</span>
</div>
</div><div class="prompt-compare">
<article class="prompt-card">
<header>
@@ -981,6 +1111,33 @@ const base = import.meta.env.BASE_URL;
Same contract · explicit working methods · stronger proof
</footer>
</article>
</div><div class="comparison-strip">
<span
><span data-language-content="en">COMPARE THE RUNS</span><span
data-language-content="pt"
hidden>COMPARE AS EXECUÇÕES</span
></span
><div>
<b>01</b>
<span data-language-content="en">Files changed</span><span
data-language-content="pt"
hidden>Arquivos alterados</span>
</div><div>
<b>02</b>
<span data-language-content="en">New dependencies</span><span
data-language-content="pt"
hidden>Novas dependências</span>
</div><div>
<b>03</b>
<span data-language-content="en">Checks actually run</span><span
data-language-content="pt"
hidden>Checks executados</span>
</div><div>
<b>04</b>
<span data-language-content="en">Evidence returned</span><span
data-language-content="pt"
hidden>Evidências retornadas</span>
</div>
</div><p class="copy-status" id="copy-status" role="status" aria-live="polite"></p>
</section>
@@ -1017,21 +1174,84 @@ const base = import.meta.env.BASE_URL;
<section class="verification" id="verification">
<div class="section-label">
<span>Verification</span><span>run each gate separately</span>
</div><div class="verify-intro">
<div>
<p class="eyebrow">Checks become evidence</p><h2>
Three layers.<br />Run each one alone.
</h2>
</div><p>
Run a gate on its own line, print its exit code, attach the output. The result is the
deliverable.
</p>
</div><div class="verify-layers">
<article>
<span>01 · STATIC</span><h3>Lint and types</h3><p>
Format, lint, type-check. Fast and scoped to one file.
</p><code>pnpm lint; echo "lint=$?"</code>
Format, lint, type-check. Fast and scoped to one file. Run on every save.
</p><code>pnpm lint; echo "lint=$?" pnpm typecheck; echo "typecheck=$?"</code>
</article><article>
<span>02 · BEHAVIOR</span><h3>Unit and contract</h3><p>
Tests that repeat. Run before claiming done.
</p><code>pnpm test; echo "test=$?"</code>
</p><code>pnpm test; echo "test=$?" cd services/api && go test ./...</code>
</article><article>
<span>03 · INTEGRATION</span><h3>Real UI and API</h3><p>
Drive the actual UI, API, or browser.
</p><code>pnpm check:ui; echo "ui=$?"</code>
Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile
overflow and a missing 404.
</p><code>pnpm check:ui; echo "ui=$?" TURBO_FORCE=true pnpm e2e</code>
</article>
</div>
</div><div class="verify-antipatterns">
<span>FOUR WAYS A GREEN REPORT IS FALSE</span><div class="ap-grid">
<article>
<b>1</b><div>
<strong>Pipe a gate</strong><p>
tail, grep, or head hide the real exit code — a pipeline returns the last command's
status.
</p>
</div>
</article><article>
<b>2</b><div>
<strong>Swallow a rejection</strong><p>
A silent <code>{'.catch(() => {})'}</code> hides a panic, an upstream limit, or a partial
failure.
</p>
</div>
</article><article>
<b>3</b><div>
<strong>Trust the cache</strong><p>
Turbo caches results. A gate that "passes" may not have run — use <code
>TURBO_FORCE=true</code
>.
</p>
</div>
</article><article>
<b>4</b><div>
<strong>Skip the third layer</strong><p>
Lint and unit can both be green while the page breaks on mobile and the API never
returns 404.
</p>
</div>
</article>
</div>
</div><article class="verify-cta">
<span>RUN IT YOURSELF · two labs, under 10 minutes each</span><div class="verify-cta-grid">
<a href={`${base}hands-on/starter/`} class="verify-card"
><strong>Path A · verification lab</strong><p>
Fill the four-row comparison strip on the starter. Run A naively, Run B with <code
>$gate-discipline</code
> and <code>$webapp-testing</code>.
</p><small>Open the starter →</small><small class="verify-card-source"
>Clone ↗ <span>git.marcospaulo.dev.br/.../src/branch/pages/hands-on/starter</span
></small
></a
><a href={`${base}hands-on/rules/`} class="verify-card"
><strong>Path B · rules lab</strong><p>
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.
</p><small>Open the starter →</small><small class="verify-card-source"
>Clone ↗ <span>git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules</span
></small
></a>
</div>
</article>
</section>
<section class="sources">
<div class="section-label">