docs: add task 15f to restore the content 15d dropped
This commit is contained in:
Marcos Paulo
@@ -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
|
||||||
Reference in New Issue
Block a user