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.
This commit is contained in:
Marcos Paulo
+247
-27
@@ -82,6 +82,31 @@ const labels = {
|
|||||||
source: { en: 'GITHUB SOURCE ↗', pt: 'FONTE NO GITHUB ↗' },
|
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 = {
|
const selectorData = {
|
||||||
phases,
|
phases,
|
||||||
workers,
|
workers,
|
||||||
@@ -690,7 +715,16 @@ const base = import.meta.env.BASE_URL;
|
|||||||
></small
|
></small
|
||||||
></button
|
></button
|
||||||
><button class="active" data-effort="medium" role="tab" aria-selected="true"
|
><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"
|
><button data-effort="high" role="tab" aria-selected="false"
|
||||||
><b
|
><b
|
||||||
><span data-language-content="en">HIGH</span><span data-language-content="pt" hidden
|
><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>
|
</div>
|
||||||
</article>
|
</article>
|
||||||
</div>
|
</div><pre><code>name: review-ui · check focus, mobile, reduced motion · run verification · return evidence</code></pre>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section class="skill-builder" id="create-skill">
|
<section class="skill-builder" id="create-skill">
|
||||||
<div class="section-label">
|
<div class="section-label">
|
||||||
<span>Create a skill</span><span>repeatable pain → reusable judgment</span>
|
<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">
|
</div><div class="builder-workbench">
|
||||||
<nav class="builder-steps" role="tablist" aria-label="Skill creation workflow">
|
<nav class="builder-steps" role="tablist" aria-label="Skill creation workflow">
|
||||||
{
|
{
|
||||||
Object.values(skillWorkflow).map((step) => (
|
['observe', 'trigger', 'scaffold', 'write', 'validate'].map((id) => {
|
||||||
<button
|
const step = skillWorkflow[id];
|
||||||
class:list={{ active: step.id === 'observe' }}
|
return (
|
||||||
data-skill-step={step.id}
|
<button
|
||||||
role="tab"
|
class:list={{ active: step.id === 'observe' }}
|
||||||
aria-selected={step.id === 'observe'}
|
data-skill-step={step.id}
|
||||||
>
|
role="tab"
|
||||||
<>
|
aria-selected={step.id === 'observe'}
|
||||||
<b>{step.number}</b>
|
>
|
||||||
<span>{step.title.en}</span>
|
<>
|
||||||
</>
|
<b>{step.number}</b>
|
||||||
</button>
|
<>
|
||||||
))
|
<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">
|
</nav><article class="builder-detail" id="builder-detail" aria-live="polite">
|
||||||
<header>
|
<header>
|
||||||
@@ -819,7 +893,39 @@ const base = import.meta.env.BASE_URL;
|
|||||||
>
|
>
|
||||||
</div>
|
</div>
|
||||||
</footer>
|
</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>
|
</div>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
@@ -955,14 +1061,38 @@ const base = import.meta.env.BASE_URL;
|
|||||||
</div><div>
|
</div><div>
|
||||||
<p>
|
<p>
|
||||||
Start with a deliberately incomplete static task board. Run one prompt as written,
|
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">
|
</p><div class="starter-links">
|
||||||
<a href={`${base}hands-on/starter/`} class="starter-link">Open the starter →</a><a
|
<div class="starter-link-group">
|
||||||
href={`${base}hands-on/rules/`}
|
<a href={`${base}hands-on/starter/`} class="starter-link">Open the starter →</a><a
|
||||||
class="starter-link">Open the rules lab →</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>
|
||||||
|
</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">
|
</div><div class="prompt-compare">
|
||||||
<article class="prompt-card">
|
<article class="prompt-card">
|
||||||
<header>
|
<header>
|
||||||
@@ -981,6 +1111,33 @@ const base = import.meta.env.BASE_URL;
|
|||||||
Same contract · explicit working methods · stronger proof
|
Same contract · explicit working methods · stronger proof
|
||||||
</footer>
|
</footer>
|
||||||
</article>
|
</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>
|
</div><p class="copy-status" id="copy-status" role="status" aria-live="polite"></p>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
@@ -1017,21 +1174,84 @@ const base = import.meta.env.BASE_URL;
|
|||||||
<section class="verification" id="verification">
|
<section class="verification" id="verification">
|
||||||
<div class="section-label">
|
<div class="section-label">
|
||||||
<span>Verification</span><span>run each gate separately</span>
|
<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">
|
</div><div class="verify-layers">
|
||||||
<article>
|
<article>
|
||||||
<span>01 · STATIC</span><h3>Lint and types</h3><p>
|
<span>01 · STATIC</span><h3>Lint and types</h3><p>
|
||||||
Format, lint, type-check. Fast and scoped to one file.
|
Format, lint, type-check. Fast and scoped to one file. Run on every save.
|
||||||
</p><code>pnpm lint; echo "lint=$?"</code>
|
</p><code>pnpm lint; echo "lint=$?" pnpm typecheck; echo "typecheck=$?"</code>
|
||||||
</article><article>
|
</article><article>
|
||||||
<span>02 · BEHAVIOR</span><h3>Unit and contract</h3><p>
|
<span>02 · BEHAVIOR</span><h3>Unit and contract</h3><p>
|
||||||
Tests that repeat. Run before claiming done.
|
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>
|
</article><article>
|
||||||
<span>03 · INTEGRATION</span><h3>Real UI and API</h3><p>
|
<span>03 · INTEGRATION</span><h3>Real UI and API</h3><p>
|
||||||
Drive the actual UI, API, or browser.
|
Drive the actual UI, API, or browser. Slower and flakier — only this catches mobile
|
||||||
</p><code>pnpm check:ui; echo "ui=$?"</code>
|
overflow and a missing 404.
|
||||||
|
</p><code>pnpm check:ui; echo "ui=$?" TURBO_FORCE=true pnpm e2e</code>
|
||||||
</article>
|
</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>
|
||||||
<section class="sources">
|
<section class="sources">
|
||||||
<div class="section-label">
|
<div class="section-label">
|
||||||
|
|||||||
Reference in New Issue
Block a user