From a1eb1e79eaa57f57381acb35329380753ce8962d Mon Sep 17 00:00:00 2001 From: Marcos Paulo Date: Sat, 5 Sep 2026 23:47:57 +0000 Subject: [PATCH] docs: add task 15f to restore the content 15d dropped --- .../task-15f-full-guide-restore.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 plans/astro-refactor/task-15f-full-guide-restore.md diff --git a/plans/astro-refactor/task-15f-full-guide-restore.md b/plans/astro-refactor/task-15f-full-guide-restore.md new file mode 100644 index 0000000..f27f6ea --- /dev/null +++ b/plans/astro-refactor/task-15f-full-guide-restore.md @@ -0,0 +1,172 @@ +# Task 15f — Restore the content 15d dropped from /full-guide/ + +**Agent**: `page-migrator` · **Model**: Codex **Depends on**: 15d **Blocks**: +19, 20 **Worktree**: `.agents/scripts/worktree.sh start 15f full-guide-restore` + +## Goal + +`/full-guide/` is missing about a fifth of the page. Put it back, in the right +place, bilingual where the legacy page is bilingual. + +Task 15d assembled the page and passed every check. It also dropped 87 rendered +text spans. One of them — the `.chapter-route` section, the only route out of +the guide to the summary, models, agents and skills chapters — has already been +restored (`c2b35d5`). The remaining 86 are your task. + +Nothing caught this. `scripts/verify.mjs` reads `full-guide/index.html`, the +legacy file, which still has every one of these sections. The gate was green the +whole time. Task 19 is blocked on you: it re-pointed its assertions at `dist/` +and they now fail, correctly, on exactly this content. + +## How to see the gap + +``` +pnpm run build +node .agents/scripts/rendered-text-diff.mjs full-guide +``` + +It walks the live DOM of both pages and prints the text the legacy page paints +and the Astro page does not. It skips hidden nodes, so the Portuguese half of +each bilingual pair does not register as a difference, and it waits for the +islands to hydrate, so the tab panels' injected copy counts as present. + +**This script reaching zero is the task.** Do not edit it to make it pass. + +## What is missing + +Whole blocks, not scattered strings. By CSS class, present in +`full-guide/index.html` and absent from `dist/full-guide/index.html`: + +`verify-intro`, `verify-cta`, `verify-cta-grid`, `verify-card`, +`verify-card-source`, `verify-antipatterns`, `ap-grid`, `comparison-strip`, +`exercise-brief`, `builder-intro`, `builder-loop`, `builder-artifact`, +`artifact-head`, `artifact-command`, `starter-link-group`, `starter-link-source` + +That covers, at minimum: the three-layer verification section and its code +lines, the "four ways a green report is false" grid, the two hands-on lab cards +with both "Clone from Gitea →" links, the exercise brief (stack / dependencies / +files), the four-row comparison strip, and the skill-forge output package tree +with its validate and after-real-use panels. + +The exact 86 spans, in document order: + +``` + - default start + - name: review-ui · check focus, mobile, reduced motion · run verification · return evidence + - 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. + - Observe + - find repeated friction + - Define trigger + - route precisely + - Choose anatomy + - only needed files + - Write guidance + - decisions, not trivia + - Validate + - test real behavior + - OUTPUT / SKILL PACKAGE + - review-ui/ + - ├── SKILL.md + - ├── agents/ + - │ └── openai.yaml + - ├── references/ + - │ └── accessibility.md + - └── scripts/ + - └── verify.mjs + - VALIDATE + - quick_validate.py ./review-ui + - AFTER REAL USE + - observe failure + - sharpen one rule + - retest behavior + - keep it narrow + - 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. + - Clone from Gitea → + - Clone from Gitea → + - THE MISSING FEATURE + - Add All / Open / Done filters that survive reload and browser navigation. + - STACK + - HTML · CSS · JavaScript + - DEPENDENCIES + - none + - FILES + - 3 + - COMPARE THE RUNS + - Files changed + - New dependencies + - Checks actually run + - Evidence returned + - 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. + - Format, lint, type-check. Fast and scoped to one file. Run on every save. + - pnpm lint; echo "lint=$?" pnpm typecheck; echo "typecheck=$?" + - pnpm test; echo "test=$?" cd services/api && go test ./... + - 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 + - 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. + - Clone ↗ + - git.marcospaulo.dev.br/.../src/branch/pages/hands-on/rules +``` + +## Method + +1. Read the legacy source for each block out of `full-guide/index.html`. Copy + the strings; do not retype them. Several contain box-drawing characters + (`├──`, `└──`), `·` separators, and `$`-prefixed skill names. +2. Place each block where the legacy page has it — the section order is part of + the argument the page is making. +3. Bilingual pairs follow `.agents/rules/content-i18n.md`: render the fragment + twice, `data-language-content="en"` visible and `data-language-content="pt"` + hidden. **Check `translations.pt` in `app.js` before assuming a block is + bilingual.** Several of these are English-only on the live site — + `.chapter-route` was — and inventing Portuguese for them is a regression in + the other direction. +4. Reuse the existing blocks in `src/components/blocks/`. If a block does not + exist, this is assembly work that 15d should have done and you may write the + markup inline in the page, as 15d did elsewhere. Do not write a new island. + +## Do not + +- Do not touch `full-guide/index.html`, `app.js`, or any other legacy file. +- Do not weaken or delete an assertion in `scripts/verify.mjs`. +- Do not reformat files you are not restoring content into. 15d ran prettier + across the whole repo on one attempt and it had to be reverted. + +## Done when + +- [ ] `node .agents/scripts/rendered-text-diff.mjs full-guide` reports 0 missing +- [ ] Every restored bilingual block has both `en` and `pt`; every English-only + block is English-only in `translations.pt` too, and you say which is which +- [ ] Section order matches the legacy page +- [ ] `pnpm run gate` green