docs: standardize repo docs and scaffold agentic-coding config #6
No reviewers
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
PCivil/folletos-digitales!6
Loading…
Reference in a new issue
No description provided.
Delete branch "docs/agentic-onboarding"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What this PR does
Prepares the repository for AI-agent-driven work (Matt Pocock skills) by documenting, standardizing, and generalizing the existing information, plus one new policy (item 4 below, flagged explicitly). It does not change the website itself (pages, styles, content) — documentation and configuration only.
Changes
docs/agents/,CLAUDE.md): Forgejo issue tracker, triage labels, domain-doc consumer rules.CONTEXT.md): canonical vocabulary; distinguishes the two content models (BrochurevsEmergencyTopic) and reading-mode vs style-variant.README.md,docs/routes.md): the docs claimed "4 topics / 8 pages"; the real site has 48 routes (1+1+1+6+1+6+8+24).docs/routes.mdis now the single route inventory — its tables were corrected and the obsolete/nuevo-contenido-completorow removed, and the README's duplicate table was dropped in favour of a link to it.CLAUDE.mdrule 5 it creates a binding immutability constraint on the home page, the two topic menus and their 12[topic]children that was never written down before. The rest of this PR records what already existed; this item adds a hard constraint, and it is called out here so no reviewer has to infer it from the diff.Migration context
The repo moved from GitHub to this Forgejo instance (
PCivil/folletos-digitales), now the source of truth. GitHub is kept as an automatic backup mirror. Issues and PRs live here.Language policy
Agent- and contributor-facing docs and all remote-facing artifacts (PRs, issues, comments, commits) are in English; product-facing content (page copy,
docs/design_guide.md) stays in Spanish. SeeCLAUDE.mdrule 4.Follow-up issues (out of scope here)
Monitoring (#1), CI + docs-drift check (#2), deployment docs (#3), content-model consolidation (#4), package.json metadata (#5), orphaned routes (#7), design-guide reconciliation (#8), docs single-sourcing (#9).
Code review — two axes (Standards / Spec)
Automated review of
master...docs/agentic-onboarding(7 files, +287/−64). Two independent axes: Standards (does the change respect the repo's documented standards?) and Spec (does the change do what this PR says it does?). Reported separately on purpose: one axis can pass while the other fails.Summary: Standards — 3 factual contradictions, 4 design smells, 1 disclosure note. Spec — 6 findings. Two findings surfaced on both axes independently (README line 1, and the
/prevencion-escolardata source): those are the highest-confidence fixes.Standards
Factual contradictions with the repo
README.md, line 1 — the headline claim is false:src/pages/index.astrodefines exactly twomenuOptions(/prevencion-escolar,/prevencion-y-gestion-de-riesgo) and nothing else.grep -rnoE "/(sismos|inundaciones|orden-publico|otros-riesgos)-[a-z-]*" src/returns zero hits: the 8/[slug]-[mode]routes are unreachable from any page. The commit message says "realign README with actual site structure"; this is precisely the line that did not get realigned.docs/routes.md+README.md— inconsistent orphan reporting./generalis correctly flagged "currently hidden from the menu", but the 8 general-brochure routes are equally unlinked and carry no such note. Same condition, different treatment, in the file whose entire job is the route inventory.docs/routes.md— the/prevencion-escolarrow lists onlyschoolEmergencyTopicsas its data source.src/pages/prevencion-escolar.astro:86also filtersbrochuresfor the four school planning slugs; the previous version said so explicitly ("4 planning brochures") and the rewrite dropped it.Verified correct: every slug and id in
CONTEXT.mdandREADME.md; the counts 1/1/1/6/1/6/8/24 (4×2 and 4×3×2 in bothgetStaticPaths);SponsorsFooterpresent inLayout.astro; commands vspackage.json.Design smells (judgement calls, not hard violations)
Middle Man —
docs/agents/triage-labels.md. Every row maps a string to itself (needs-triage→needs-triage), the column header names an upstream repo (Label in mattpocock/skills), and the file closes with unedited template boilerplate: "Edit the right-hand column to match whatever vocabulary you actually use."CLAUDE.mdalready states the vocabulary inline; the file delegates and adds nothing.Speculative Generality —
docs/agents/domain.md. It gives instructions forCONTEXT-MAP.md"if it exists" andsrc/<context>/docs/adr/"in multi-context repos", then declares "This is a single-context repo". Its structure block showsdocs/adr/0001-….md;docs/adr/does not exist.Duplicated Code — route/slug tables. The route-pattern table with counts and the
[mode]/[style]legend appear near-verbatim in bothREADME.mdanddocs/routes.md, and the slug/id lists appear a third time inCONTEXT.md. The README links toroutes.mdas the "detailed inventory" and still reproduces it. Three places to drift.Divergent Change —
CLAUDE.md. The new "Agent skills" section restates the tracker host and the full five-label list thatdocs/agents/*already own, and links to those files as well. Index or duplicate, not both.Disclosure
No token was committed:
issue-tracker.mdcorrectly reads from~/.config/forgejo/token. It does, however, commit the following to a repo that is auto-mirrored to a public GitHub remote (GGabrielDev/trabajo-folletos-digitales):git.gaboggamer.onlineis already ingit remote -v, so that part leaks nothing new; the admin SSH host plus the passwordless-sudo note is new reconnaissance detail with no operational need in a repo doc. Recommendation: remove that sentence, or move it to a local, gitignored note.Design-guide tension (pre-existing, not introduced here)
docs/design_guide.md§8 says to vary "únicamente superficies de lectura … sin cambiar paleta ni geometría", whileCONTEXT.mdandroutes.mdnow formalizerounded-glass/timeline-stepas variants that do change geometry.CLAUDE.md(pre-image, untouched) already endorses those three variants, so the repo overrides the guide — but this diff makes the contradiction structural in the glossary without reconciling it.Spec
Verified correct: the diff touches only
CLAUDE.md,CONTEXT.md,README.md,docs/agents/*.mdanddocs/routes.md— the claim "No modifica el sitio web (páginas, estilos, contenido)" holds. Every type name inCONTEXT.mdexists as declared (Brochure/BrochureCard/AlertLevel/BrochureModeinsrc/data/brochures.ts;EmergencyTopic/EmergencyPhase/EmergencyMapNode/EmergencyInfographicItem/EmergencyVisualStepinsrc/data/emergencyTopics.ts), the 8 brochure slugs and 6 topic ids match both data files, and thestyleVariantunion matches./nuevo-contenido-completois genuinely obsolete (page deleted in468dc21, absent from master'ssrc/pages/): removing its row is correct. Tracker labels #6–#9 pluswontfixexist; issues #1–#5 match the declared out-of-scope list.Implemented but wrong
getStaticPathssums 1+1+1+6+1+6+8+24 = 48, anddist/contains 48index.htmlfiles. The tables this very PR ships add up to 48, so the PR body contradicts its own deliverable./prevencion-escolardata-source column is incomplete indocs/routes.md(see Standards).Missing or partial
CLAUDE.md): "Repositorio de contexto único: unCONTEXT.md+docs/adr/en la raíz", anddocs/agents/domain.mddiagramsdocs/adr/0001-….md.docs/adr/does not exist.domain.mdsays to proceed silently when it is absent, so this is tolerable, but the config advertises a path the repo does not have.Out of scope
docs/agents/issue-tracker.mdgoes beyond "tracker Forgejo … operado vía API REST": it adds a "Server-side administration" section naming the VPS host and its passwordless sudo, plus a/wayfindersection. That is infrastructure, not tracker config — and it edges into the territory of issues #1/#3, which this PR declares out of scope.docs/agents/triage-labels.mdstill carries unedited template boilerplate: "Edit the right-hand column to match whatever vocabulary you actually use."Proposed remediations
The spirit of this PR is that an agent should be able to trust these docs without re-reading
src/. Every finding above is a point where that trust breaks. Ordered by value/effort:Blocking before merge (~25 min, text only)
Add an explicit repository-language rule. All PRs, issues, and comments pushed to the remote must be written in English, consistently, even though the site's own content and UI copy are in Spanish. Domain terms that are proper nouns of the product (
prevencion-escolar,Protección Civil, brochure slugs) stay in Spanish as identifiers; the prose around them is English. Suggested home:CLAUDE.md, which is the instruction file agents actually load — the repo has noAGENTS.mdtoday, andCONTEXT.mdis scoped to domain vocabulary rather than process rules. Wording to drop in:Note that this PR's own body is in Spanish and would be the first thing to bring into compliance; rewriting it in English also gives a clean place to fix the route count in item 4 below.
Fix
README.mdline 1. Wording that actually matchesindex.astro: "The home page is a central dashboard with two topic menus (/prevencion-escolar,/prevencion-y-gestion-de-riesgo). The general brochures are reached via/general, which is currently not linked from the home page." This clears both Spec finding #2 and the main Standards violation at once.Add
brochuresto the/prevencion-escolarrow indocs/routes.md(schoolEmergencyTopics+brochures, with a note naming the 4 planning slugs). One of only two findings flagged by both axes.Fix the PR body: 41 → 48 routes. If 41 deliberately excluded something (the
[style]routes, say), state what it excludes.Remove the VPS host + passwordless-sudo sentence from
docs/agents/issue-tracker.md. The repo has a public mirror; that detail adds no operational value to the doc and does add reconnaissance surface. If it is needed to operate, it belongs in a local, gitignored note.Finish the work this PR started (~30 min)
docs/agents/triage-labels.md: drop the boilerplate and the "Label in mattpocock/skills" column that maps every value to itself. Keep only thelabel → when it is applied → who removes ittable, which is what a triage agent actually needs.docs/agents/domain.md: the file itself declares this a single-context repo. Delete the conditionals; keep the rule that applies.docs/adr/: either create the directory with a real0001-(natural candidate: "Forgejo as source of truth, GitHub as backup mirror" — already a decision made in this very PR, currently living only in prose), or drop the path fromCLAUDE.mdanddomain.md. As it stands, the config promises something that does not exist.docs/routes.mdis the inventory; haveREADME.mdlink to it and keep only a one-sentence summary with no counts. Same forCLAUDE.md, which should indexdocs/agents/*rather than restate their contents. Three copies of the same fact is exactly how a doc becomes a lie in three months.Follow-up (separate issue, not this PR)
/[slug]-[mode]routes are not linked from any page. The inventory now makes this visible, which is to this PR's credit — but it is a product finding, not a docs finding: either link them from/generalor from the home page, or delete them. Deserves its own issue.docs/routes.mdagainstgetStaticPathsand fails in CI. That is the only way these fixes stay in sync; it fits naturally into issue #2 (CI).Items 1–5 close everything both axes flagged as incorrect. Items 6–9 are what make the PR live up to its own premise of "documentar, estandarizar y generalizar" instead of leaving half-edited templates behind.
🤖 Review generated with Claude Code
Remediation 1 (language policy) — done.
Added to
CLAUDE.mdas rule 4 under Reglas de Desarrollo y Estilo, commitc53cdeaondocs/agentic-onboarding(pending push at the time of writing):Two notes on placement and wording:
CLAUDE.mdrather thanCONTEXT.md: this is a process rule, andCONTEXT.mdis scoped to domain vocabulary perdocs/agents/domain.md. There is noAGENTS.mdin this repo.CLAUDE.mdis repository content, not one of the remote-facing artifacts (PRs, issues, comments, commit messages) the rule governs.Still open from the review: this PR's own title and body are in Spanish and should be rewritten in English to comply — that rewrite is also the right place to correct the route count from 41 to 48 (remediation 4).
Follow-up to the previous comment: the language boundary is drawn in the wrong place.
The rule as committed in
c53cdeasplits by location — repository files in Spanish, remote-facing artifacts (PRs, issues, comments, commit messages) in English — and the previous comment justified keepingCLAUDE.mditself in Spanish on that basis. That justification does not survive a look at what the repo actually contains:README.md,CONTEXT.md,docs/agents/*.md,docs/routes.mdCLAUDE.md,docs/design_guide.mdEvery other document an agent loads to work on this repo is already in English.
CLAUDE.md— the entry point, the one file every agent reads first — is the odd one out, and this PR is what created that inconsistency by adding four English docs around it.The better split is by audience, not by location:
CLAUDE.md,CONTEXT.md,docs/agents/*,README.md,docs/routes.md, plus PR titles and bodies, issue titles and bodies, review comments, and commit messages.docs/design_guide.md(a visual reference for the team, not an agent process doc).That line needs no carve-out, matches what the repo already does in 5 of 7 agent-facing files, and has a practical upside: instruction files in English are followed slightly more reliably by models, and
CLAUDE.mdis the highest-leverage file in the repo for that.Suggested work, for whoever picks this up:
CLAUDE.mdto English in full (~34 lines).c53cdea.docs/design_guide.mdin Spanish — deliberately, and say so in rule 4 so the exception is documented rather than accidental.Not done in this PR; raised here so the decision is recorded rather than silently inherited.
Review addressed — remediation summary
Thanks for the two-axis review. I verified every factual claim against
src/before acting; all held (twomenuOptionsinindex.astro, no page links the/[slug]-[mode]routes,prevencion-escolar.astro:85filtersbrochures,getStaticPathssums to 48,dist/has 48index.html, nodocs/adr/). Changes are in commits1cc3c4eand9da901b.Blocking (1–5)
CLAUDE.mdfully translated to English, rule 4 reworded by audience,docs/design_guide.mddocumented as the Spanish exception.index.astro: two topic menus; general brochures via/general, not linked from home./prevencion-escolardata source — nowschoolEmergencyTopics+brochures, with the 4 planning slugs named.docs/routes.mdnow states the total and its arithmetic.issue-tracker.md; replaced with a pointer to a local, gitignored operator note.Finish the work (6–9)
triage-labels.md— dropped the self-mapping column and boilerplate; kept a label / when-applied / when-removed table.domain.md— multi-context conditionals pruned; single-context only.docs/adr/— created, with ADR-0001 (Forgejo as source of truth). Also added ADR-0002 (frozen legacy routes).README.mdnow links todocs/routes.mdwith a one-line summary and no counts;CLAUDE.mdindexesdocs/agents/*instead of restating the host and label list.Follow-up (separate issues)
/generaland/[slug]-[mode]only; the home page and the two menus (+ children) are frozen legacy routes pinned by deployed QR codes (ADR-0002) and must not change.Not fixed (acknowledged)
design_guide.md§8 vsrounded-glass/timeline-steptension is pre-existing and product-facing;CLAUDE.mdalready endorses the three variants, so the repo overrides the guide. Left for a design-doc reconciliation rather than this docs PR.Code review round 2 — two axes (Standards / Spec)
Re-review of
master...docs/agentic-onboardingat9da901b(9 files, +363/−78), after commits1cc3c4eand9da901b. 10 of 15 prior findings are closed. Details below, but one correction comes first because it changes what still needs doing.Correction to round 1 — my earlier finding was wrong
Round 1 claimed the 8
/[slug]-[mode]routes were "unreachable from any page", citing a grep that returned zero hits. That grep was wrong. It matched literal slugs, so it could not see a template literal. The real link exists:The full set of link targets in the repo (
grep -rn 'href={resolvePath' src/) is:/,/${brochure.slug}-{light,dark},/prevencion-escolar/${topic.id},/prevencion-y-gestion-de-riesgo/${topic.id}. Nothing else. So the actual reachability graph is:/, two topic menus/prevencion-escolar/[topic],/prevencion-y-gestion-de-riesgo/[topic]/[slug]-[mode]/general— linked, contrary to round 1/general/[slug]-[style]-[mode]Apologies for the bad steer. Two things follow from it:
docs/routes.mdis now inverted, and this PR introduced the inversion. Line 17 says/[slug]-[mode]is "not linked from any page" — false,general.astrolinks all 8. Line 18 says/[slug]-[style]-[mode]is "reached from/prevencion-escolar" — also false: the onlyhref=inprevencion-escolar.astroare lines 161 and 215, both to/prevencion-escolar/${topic.id}; the school brochures open as in-page<dialog>modals (lines 538-656), and nohrefanywhere in the repo containsrounded-glassortimeline-step. So 24 routes the doc calls reachable are orphans, and 8 orphans it names are reachable. The "Total: 48" arithmetic is correct./general+ the 8/[slug]-[mode]. The correct orphan set is/general(which subtends the 8) and the 24/[slug]-[style]-[mode]routes — 25 pages, not 9. The 24 are the larger and more interesting decision: an entire style-variant matrix that nothing reaches.README.mdline 1, by contrast, is now correct as written — "the general brochures are reached via/general" is true, and/generalbeing itself unlinked is stated separately. That fix stands.Standards
Prior findings
menuOptionsexactly (index.astro:12-28)/prevencion-escolardata sourceschoolEmergencyTopics + brochures, four slugs named, matchesprevencion-escolar.astro:85-87triage-labels.mddomain.mddocs/adr/existsCLAUDE.mdrule 5,docs/routes.md§Frozen legacy routes, and ADR-0002CLAUDE.md1cc3c4e, grep clean, but still reachable atd875618, andgit remote -vconfirms a live public push-mirrordesign_guide.md§8 tensionOn #6 (judgement call): net duplication is unchanged — editing one frozen route now means touching three files (Shotgun Surgery). ADR-0002 is the natural owner;
CLAUDE.mdrule 5 anddocs/routes.mdshould link to it rather than restate the list.On #9 (judgement call): the dismissal is weaker than it was. This PR built the grandfathering mechanism (rule 5 + ADR-0002) and then declined to apply it to the one known standards conflict in the repo. Also, rule 4's stated reason for keeping
design_guide.mdin Spanish is that it is "not an agent process doc" — but its §7 is titled "INSTRUCCIÓN DIRECTA PARA EL AGENTE" and §9 is an agent checklist. The exception may still be right; the justification given for it is not.New material
HARD violation of this PR's own
CLAUDE.mdrule 4. The rule reads:CONTEXT.md, added by this PR, is entirely in Spanish (# CONTEXT.md — Glosario de dominio).README.md, rewritten by this PR, still carries### Configuración de Ruta Base (Despliegue tras Proxy Reverso)at line 103 and its Spanish body. The rule is unobeyed at birth, in the same commit range that introduced it, by two of the six files it names.ADRs — format is clean. Both follow Nygard structure (numbered title, Date, Status, Context, Decision, Consequences). ADR-0002's frozen list matches
src/pages/exactly. ADR-0001's remote claims check out againstgit remote -v.Unrelated dead code spotted (pre-existing, not introduced here, no action needed in this PR):
prevencion-escolar.astro:710-717runs an auto-theme script overa[data-theme-link="auto"], a selector that page never renders.No new secrets. No broken doc paths.
Spec
Prior findings
find dist -name index.html | wc -l= 48; tables agree/prevencion-escolardata sourcedocs/adr/advertised but absentdomain.mdtree matchesissue-tracker.mdscope creep/wayfinder,wayfinder:map), and line 4's "self-hosted on the project owner's VPS (server-side changes are possible when needed)"triage-labels.mdboilerplateMissing or partial
CONTEXT.mdand README §Configuración de Ruta Base, as above. This is the same finding the Standards axis reached independently.docs/structure tree omitsdocs/adr/entirely. The ADRs are advertised inCLAUDE.md,domain.mdandroutes.md, but invisible in the README map a new contributor reads first.Scope creep
/wayfinderand server-administration sections remain outside "Forgejo issue tracker" config.Implemented but wrong
CLAUDE.mdrule 5 anddocs/routes.md, and cited as binding in issue #7. An unsourced claim now carries the weight of a hard constraint across four places, and a future agent can neither confirm it nor safely challenge it. ADR-0002's Context should name the source: who distributed the codes, when, and which print run.Suggested next steps
Blocking:
docs/routes.mdlines 17-18 (/[slug]-[mode]is linked from/general; the 24/[slug]-[style]-[mode]are the orphans)./generalplus the 24 style routes, 25 pages.CONTEXT.mdto English and the README §Configuración de Ruta Base, or amend rule 4 — but "No exceptions" plus two exceptions in the same commit range cannot both stand.Non-blocking:
5. Make ADR-0002 the single owner of the frozen-route list; have rule 5 and
routes.mdlink to it.6. Drop or relocate the "Server-side administration" and "Wayfinding operations" sections in
issue-tracker.md.7. Add
docs/adr/to the READMEdocs/tree.8. Either re-justify the
design_guide.mdSpanish exception on grounds that survive its §7/§9 being agent instructions, or fold it into the English set.9. Decide whether the
d875618disclosure in history warrants a squash, given the live public mirror.Summary — Standards: 10 findings, 5 closed, 2 partial, 2 open, 1 new hard violation; worst =
docs/routes.mdreachability is inverted, and this PR introduced it. Spec: 10 findings, 5 closed, 1 partial, 4 new; worst = the language rule this PR writes is broken by two of the six files it names.🤖 Review generated with Claude Code
9da901bb5dtob2cfdcb0bfRound 2 addressed — remediation summary
Thanks for the round-2 review, and for catching your own round-1 grep error. I re-verified reachability against
grep -rn 'href={resolvePath' src/before acting: confirmedgeneral.astro:80-83links all 8/[slug]-[mode]routes, nohrefanywhere references a[style]route (the school brochures open as<dialog>modals), and/generalis itself unlinked. Fixes are in commits through2b22cdf.Blocking
docs/routes.md— fixed./[slug]-[mode]is now "linked from/general(only)"; the 24/[slug]-[style]-[mode]are marked orphaned (in-page dialogs, nohrefreferences them). The Total line now spells out the actual reachability graph./generalplus the 24/[slug]-[style]-[mode]routes (25 pages), not the 8. The 8/[slug]-[mode]are noted as reachable via/generaland not frozen.CONTEXT.mdfully translated to English; README'sConfiguración de Ruta Basesection translated. The six files rule 4 names are now all English.Non-blocking
CLAUDE.mdrule 5 anddocs/routes.mdlink to it instead of restating the list.issue-tracker.mdscope creep — dropped the "server-side changes possible" clause from the connection note and collapsed the server-administration section into a one-line "out of scope, see local operator note". Kept the brief Wayfinding-operations note, since that is how/wayfinderuses this tracker and it ships with the tracker-config template; happy to cut it if you'd rather.docs/adr/missing from README tree — added.design_guide.mdSpanish justification — reworded rule 4: it no longer claims the guide is "not an agent doc". It now acknowledges §7/§9 address the agent as a legacy tension and points at a new follow-up, issue #8, to reconcile both that and the §8-vs-style-variants conflict.gabogg@ssh.gaboggamer.online+ passwordless-sudo line was redacted from every commit inmaster..HEADvia a history rewrite (final tree byte-identical;masteruntouched). Branch force-pushed and the public GitHub mirror re-synced; no ref now points at the old commit. Both GitHub PRs (#6, #17) were closed. Caveat: GitHub may retain the unreachable object by direct SHA until it garbage-collects.Ready for re-review / merge.
Code review round 3 — two axes, plus corrections applied
Re-review of
master...docs/agentic-onboardingat2b22cdf, after the round-2 remediations. Every prior finding was re-verified againstsrc/,dist/andgit, not taken from the remediation comment.Result: 15 of 22 prior findings genuinely closed. Two blocking items remained; both were text-only and have been fixed in this round — commit
9dec5c6and an edit to issue #7. Details below, then what is left as follow-up.Fixed in this round
1.
docs/routes.mdand ADR-0002 asserted a fact the build disprovesBoth said the 24
/[slug]-[style]-[mode]routes are "linked from no page", androutes.md:18justified it with:That grep is not empty, and two
hrefbuilders do produce style routes — both as template literals, which is the exact literal-vs-template-literal error round 2 corrected in round 1:Proof in the shipped build:
dist/brigadas-escolares-default-dark/index.htmlcontainshref="/brigadas-escolares-default-light", andgrep -rlE 'href="[^"]*-(default|rounded-glass|timeline-step)-(dark|light)"' dist/returns 24 files.The conclusion survives — nothing outside the set links into it — but for a reason the docs never stated:
BrochurePage.astro:33gatesStyleSwitchonprocess.env.VERCEL_ENV === 'preview', so the style matrix is preview-only, and the mode links are internal to the set. That is the material fact the inventory was missing.9dec5c6rewrites the rationale indocs/routes.md(route row, Total line, frozen-routes note) anddocs/adr/0002-frozen-legacy-routes.md, names the preview gate, and warns the next reader not to grep for the literal style ids.2. Issue #7's title still carried the pre-correction scoping
Body said the 8
/[slug]-[mode]routes are reachable and the 24 are the orphans; the title still said the opposite. Titles are what triage reads. Retitled to "Orphaned routes: /general and the 24 /[slug]-[style]-[mode] pages have no entry point", and the body now carries the preview-gate detail and the decision it implies (promote the style switch to production, or drop the matrix).Standards
Prior findings
README.md:3↔index.astro:11-289dec5c6/prevencion-escolardata sourceroutes.md:13↔prevencion-escolar.astro:85-87triage-labels.mddomain.mddomain.md:5,16-22single-context; tree matchesdocs/adr/adr/0002:25-27;CLAUDE.md:23androutes.md:26link to itCLAUDE.mdCLAUDE.md:25-31is a genuine indexdesign_guide.mdtensionCLAUDE.md:21re-justifies but cites an unnumbered "design-guide follow-up issue" (it is #8)issue-tracker.mdscope creep:58-64still carries Wayfinding + a server-admin pointerdocs/adr/in README treeREADME.md:81All relative links in the new docs resolve. ADR format is clean (Nygard). Route count re-verified independently: 1+1+1+6+1+6+8+24 = 48, and
dist/has 48index.html.On finding 8 — the history scrub, stated precisely
The remediation said "no ref now points at the old commit". Remotely that is true; locally it is not.
git grep 'ssh.gaboggamer.online' $(git rev-list master..HEAD)— clean.git ls-remote originandgit ls-remote github— both putdocs/agentic-onboardingat the rewritten history, and norefs/pull/*on the GitHub mirror reaches any of the five pre-rewrite commits (d875618,f0a750c,d3425cd,e560569,c53cdea). The public surface is clean; the author's GC caveat about unreachable objects by direct SHA stands.refs/original/refs/heads/docs/agentic-onboarding(thefilter-branchbackup, never deleted) and the stale tracking refrefs/remotes/github/docs/agentic-onboarding.Local hygiene, not a disclosure. To finish it:
Remaining, non-blocking
routes.md:20,routes.md:27-28andadr/0002:37-40. The frozen list was de-duplicated; its inverse was duplicated in the same edit, which is why9dec5c6had to touch three places to correct one fact. ADR-0002 is the natural owner of the carve-out too.docs/agents/issue-tracker.md:46-48: "PRs as a request surface: no. (Set toyesif this repo treats external PRs as feature requests…)" — the same unedited-template smell that was cleaned out oftriage-labels.md, missed here.routes.md:20andCLAUDE.md:21both defer to a "follow-up issue" with no number (#7 and #8 respectively);adr/0002cites none. Not resolvable from the repo alone.Spec
Prior findings
routes.md:20,getStaticPathsanddist/all agreeREADME.md:3↔index.astro:10-27/prevencion-escolardata sourcedocs/adr/advertised but absentdomain.md:16-22andREADME.md:81matchissue-tracker.mdscope creeptriage-labels.mdboilerplateCONTEXT.mdandREADME.md:104-120now Englishadr/0002:17-18names source, date and holder9dec5c6Verified clean: "documentation and configuration only" holds — 9 files, all
*.md, nothing undersrc/. ADR-0001's remote claims matchgit remote -vexactly. ADR-0002's frozen list matchessrc/pages/one for one.Remaining, non-blocking
CLAUDE.mdrule 5 + ADR-0002 create an immutability constraint that was never written down before. Legitimate work for an ADR — the issue is that the Changes list presents it alongside the realignment, so a reviewer skimming the body would not notice a hard constraint being introduced. Worth one line in the PR body flagging item 4 as new policy.CLAUDE.md:21refers to anonymously.Summary — Standards: 12 prior findings, 9 closed, 2 partial, 1 closed this round; 3 non-blocking judgement calls remain. Spec: 11 prior findings, 9 closed, 1 partial, 1 open; 2 non-blocking items remain.
Both blocking items are fixed and pushed. Nothing outstanding blocks the merge: what is left is three judgement calls (duplication, template residue, unnumbered issue references), two PR-body edits, and one local
gitcleanup — none of which changes a factual claim in the docs.🤖 Review generated with Claude Code
Code review round 4 — two axes, with the remaining items applied
Re-review of
master...docs/agentic-onboardingat9dec5c6, after the round-3 remediations. Every prior finding from all three rounds was re-verified againstsrc/,dist/,gitand the Forgejo API — none of it taken from the remediation comments. Prior rounds twice drew a wrong conclusion by grepping literal slugs where the code buildshrefs from template literals, so every reachability claim below was re-derived fromgrep -rn 'href=' src/and cross-checked against the shipped build.Result: all prior blocking findings are genuinely closed. What remained was one factual overstatement, three cosmetic/hygiene items and two PR-body edits — all applied in this round, commit
dc5cc1eplus an edit to the PR body. Nothing blocks the merge.Independently re-verified
getStaticPathsgives 4 general slugs × 2 modes = 8 and 4 school slugs × 3 styles × 2 modes = 24; plus/,/general, the two menus, and their 6+6[topic]children = 48.find dist -name index.html | wc -l= 48. PR body,docs/routes.mdand the build all agree.git diff master...HEAD --name-only= 9 files, every one*.md, nothing undersrc/./,/${brochure.slug}-{light,dark},/prevencion-escolar/${topic.id},/prevencion-y-gestion-de-riesgo/${topic.id}, plusBrochurePage.astro:36-37andStyleSwitch.astro:24./generalis linked by nothing. The style switch is gated onprocess.env.VERCEL_ENV === 'preview'(BrochurePage.astro:33) and so is absent fromdist/; the only inboundhrefs to the 24 style routes come from inside the set.docs/routes.md:17-20andadr/0002:37-41state this correctly.CONTEXT.md:28,44-45,README.md:7,CLAUDE.md:22) is proper-noun identifiers, which bullet 3 of the rule permits.adr/0002:11-18names the press team, the first campaign (September 2026), the maintainer directive (2026-09-19) and the off-repo location of the print artifact./generalplus the 24/[slug]-[style]-[mode]pages — and carry the preview-gate detail.git log --all -S'ssh.gaboggamer.online'now returns nothing;git ls-remoteputsdocs/agentic-onboardingat the rewritten history on bothoriginand the GitHub mirror.Also checked and true today: ADR format (Nygard) on both records, every relative link resolves, Astro 6,
node >=22.12.0, the component and page lists,pdf_content.txt, the four<dialog>modals, and ADR-0002's frozen list againstsrc/pages/one for one.Standards
Prior findings
README.md:3↔index.astro:11-28/prevencion-escolardata sourceroutes.md:13↔prevencion-escolar.astro:85-87triage-labels.mddomain.mddocs/adr/adr/0002:25-27only)CLAUDE.mdCLAUDE.md:25-31is a genuine indexdesign_guide.mdtensionissue-tracker.mdscope creepissue-tracker.mdApplied this round
1.
docs/routes.md:17overstated the reachability of the 8/[slug]-[mode]routes. The row read "linked from/general(only)", which quietly applied a looser criterion than the one the very next row uses to call the 24 style routes orphaned.general.astro:80emits a statichrefonly to/${slug}-light; the four-darkroutes are reached from the same cards throughdata-dark-href(general.astro:83), swapped by the inline theme script, and through the in-set mode switch — the same in-set mechanism that makes the style matrix orphaned. One inventory should not grade two route families on two criteria. The row and the Total line now spell out both paths.2. Two dangling follow-up pointers, now numbered.
CLAUDE.md:21deferred to "the design-guide follow-up issue" androutes.md:20to "the follow-up issue", neither resolvable from the repo alone. They now cite #8 and #7.3. Residual template boilerplate,
docs/agents/issue-tracker.md:46-48— the same unedited-template smell that was cleaned out oftriage-labels.md, missed there:Replaced with the decision it encodes, keeping the Forgejo-specific rule that skills actually need (issues and PRs share one index space, so
#Nresolves through"$API/pulls/<index>"first).4. Local
githygiene, finding 8. Round 3 reported that the scrub was complete remotely but not locally, and it still was not:refs/original/refs/heads/docs/agentic-onboarding(thefilter-branchbackup) still pointed at59ad8829, and the stale tracking refrefs/remotes/github/docs/agentic-onboardingstill pointed atd3425cd, whose tree contains the redacted line atissue-tracker.md:66. Both refs are gone — backup ref deleted, mirror re-fetched with--prune.git log --all -S'ssh.gaboggamer.online'is now empty. No remote surface was ever affected by this; it was local only, and the earlier caveat about GitHub retaining an unreachable object by direct SHA until it garbage-collects still stands.Left open, deliberately
issue-tracker.md:58-64— "Wayfinding operations" and the server-administration pointer. Flagged since round 1, disclosed and defended by the author in round 2 ("that is how/wayfinderuses this tracker and it ships with the tracker-config template"). That is a reasonable call: the section is one paragraph, it documents tracker API surface rather than infrastructure, and the actual scope-creep content (the VPS host, the passwordless-sudo note) is gone. Recorded as accepted, not outstanding.CLAUDE.md:23,routes.md:24-25andadr/0002:22-23, and the orphan carve-out atroutes.md:20,routes.md:27-29andadr/0002:37-41. That is why correcting one fact took three edits in9dec5c6. ADR-0002 is the natural owner of the carve-out too. Not worth another churn round on a docs PR that is otherwise ready; worth folding into the docs-drift check in #2.design_guide.md§8 vs the style variants, and its §7/§9 addressing the agent. Pre-existing, product-facing, now tracked in #8 and cited by number fromCLAUDE.md:21.Spec
Prior findings
/prevencion-escolardata sourcedocs/adr/advertised but absentdomain.mdtree andREADME.md:81matchissue-tracker.mdscope creeptriage-labels.mdboilerplateApplied this round — both in the PR body
5. ADR-0002 was presented as documentation. The body opens with "documenting, standardizing, and generalizing the existing information", and Changes item 4 listed ADR-0002 beside the realignment work. But
CLAUDE.mdrule 5 + ADR-0002 create an immutability constraint that existed nowhere before — legitimate work for an ADR, and the decision itself is sound, but a reviewer skimming the body would not have seen a hard constraint being introduced. The opening sentence now says "plus one new policy", and item 4 carries an explicit call-out naming what the constraint binds.6. Follow-up list omitted #8. The body listed #1–#5 and #7; #8 (design-guide reconciliation) was created during this review and is the issue
CLAUDE.md:21now cites. Added.No scope creep beyond the accepted R1-5. Nothing implemented-but-wrong this round.
Summary — Standards: 11 prior findings, 9 closed, 1 accepted by decision, 1 deferred to #2 as a judgement call; 4 items applied in
dc5cc1e, worst = the/[slug]-[mode]reachability row graded two route families on two criteria. Spec: 12 prior findings, all closed; 2 items applied to the PR body, worst = a new binding constraint presented as documentation of an existing one.No finding outstanding on either axis. Ready to merge.
🤖 Review generated with Claude Code
Code review round 5 — two axes, verification pass
Re-review of
master...docs/agentic-onboardingatdc5cc1e(merge-base8382752, 9 files, all*.md). This round's brief was verification, not fresh discovery: every finding from rounds 1–4 was re-derived fromsrc/,dist/,gitand the Forgejo API, with the remediation comments treated as claims to test rather than as evidence.Both axes independently confirm
dist/is in sync (find src -newer dist -type fempty, 48index.html), so reachability was checked against the shipped build rather than against greps alone.Result: no blocking finding survives on either axis. Three prior findings were marked closed more confidently than the tree supports, and one agent-facing file states something that is false today. Details below.
Standards
Correction to this round, applied before anything below
This review first reported that
docs/agents/domain.md:12was false because/grill-with-docsand/improve-codebase-architecture"do not exist". That was wrong, and it is the same class of error as the round-1 and round-3 greps: the right lookup was never run. The check went to~/.claude/plugins/installed_plugins.json— user-level plugins — and never looked at the project's own.claude/skills/, which symlinks into.agents/skills/and carries all of them.Both skills exist, and
domain.md:12's navigation claim is accurate on its own terms:.agents/skills/grill-with-docs/SKILL.md:7— "Call the Skill tool twice, forgrillinganddomain-modeling.".agents/skills/improve-codebase-architecture/SKILL.md:66— calls the Skill tool withdomain-modelingto keep the domain model current.The same correction voids the follow-on remark about
CLAUDE.md:27andissue-tracker.md:60:/triage,/to-tickets,/to-spec,/implementand/wayfinderare all present in.claude/skills/too. No agent-facing file in this PR names a skill that does not exist. Finding 5 is CLOSED, not PARTIAL, and nothing is recommended before merge on this axis. The table and the verdict below are corrected accordingly.Prior findings
README.md:3↔index.astro:11-28(exactly twomenuOptions)href="/general"indist/→ 0 hits; the 24-[style]-hrefs indist/all sit inside the style set;Selector de estiloindist/→ 0, confirming the preview gate atBrochurePage.astro:33/prevencion-escolardata sourceroutes.md:13↔prevencion-escolar.astro:85-87triage-labels.mdtriage-labels.md:6-15; the 5 labels match the tracker exactlydomain.md:16-22matchesdocs/adr/;domain.md:12's skill references all resolve in.claude/skills/(see correction above)CLAUDE.mdCLAUDE.md:25-31is a pure indexgit log --all -S'ssh.gaboggamer.online'empty; norefs/original/*;refs/remotes/github/docs/agentic-onboarding=9dec5c6, an ancestor of HEADdesign_guide.md§8 tensionCLAUDE.md:21cites #8; issue #8 exists with a matching title. The tension is real (design_guide.md:97"sin cambiar … geometría" vsBrochurePage.astro:40pc-rounded … backdrop-blur)issue-tracker.mdscope creep:60-66still carries Wayfinding ops + the server-admin pointerissue-tracker.md:46-50now states the decisionroutes.md:20,routes.md:27-29,adr/0002:37-41. Round 3 raised it; round 4's table has no row for itroutes.md:17reachability criteriongeneral.astro:80,83:46-48githygieneAlso re-verified true: ADR Nygard format on both records; every relative link resolves; all
CONTEXT.mdtype names exist (brochures.ts:1,3,21,27;emergencyTopics.ts:1,7,12,17,24); 8 slugs and 6 ids match both data files;SponsorsFooterinLayout.astro:3,28; Astro^6.1.2, node>=22.12.0; 48 = 1+1+1+6+1+6+8+24; ADR-0002's frozen list matchessrc/pages/one for one.One methodological note for future rounds: a plain
grep -rn 'href' src/still missesBrochurePage.astro:36-37, where the builders are nameddarkHref/lightHref. That is a third variant of the literal-vs-template-literal trap that caught rounds 1 and 3 — a case-sensitive sweep forHrefis needed too.Marked closed but not closed
Finding 6 was closed on a narrower reading than it was filed. The frozen-route list was genuinely de-duplicated (
adr/0002:25-27is now its sole owner). But round 1's finding also said "the slug/id lists appear a third time inCONTEXT.md", and that half is untouched: general + school slugs atCONTEXT.md:17-19,README.md:15androutes.md:35-36(the four school slugs a fourth time atroutes.md:13); topic ids atCONTEXT.md:25-26,README.md:16androutes.md:37. Rounds 3 and 4 both reported this CLOSED.The round-3 orphan-set duplication is still open and disappeared from round 4's verdict table without being resolved or accepted.
New findings
1. Duplicated Code, intra-file (judgement call).
docs/routes.md:31-36("Parameter values") anddocs/routes.md:56-61("Style / reading variants") state the same two axes and the same value sets twice in one file, both rewritten by this diff;CONTEXT.md:34-40is a third statement. No prior round flagged this pair.2. Minor wording residue (judgement call).
README.md:3says/general"is currently not linked from the home page", which implies something else links it.routes.md:12correctly says "not linked from any page (orphaned)", anddist/confirms zero inbound links.Standards verdict
Nothing blocks merge, and nothing is recommended before merge. No hard violation of a documented standard survives: rule 4 (language) holds, rule 5 / ADR-0002 is coherent and single-sourced, the disclosure is scrubbed locally and remotely. What remains is duplication — the slug/id triplication that finding 6 left open, the orphan-set triplication from round 3, and the intra-file pair above. All three are judgement calls and all three are drift risks, which is exactly what the docs-drift check in #2 is for; fold them there rather than hold the PR.
Spec
Prior findings
getStaticPaths: 4×2=8 and 4×3×2=24; 6 ids per topic file → 12; +4 singles = 48.dist/= 48index.htmlREADME.md:3↔index.astro:11-28; nohrefto/generalinsrc/ordist//prevencion-escolardata sourceroutes.md:13↔prevencion-escolar.astro:85-87docs/adr/advertised but absentdomain.mdtree and the READMEdocs/tree both carry themissue-tracker.mdscope creeptriage-labels.mdboilerplateneeds-info,needs-triage,ready-for-agent,ready-for-human,wontfixCLAUDE.md:22bullet 3adr/0002:11-18names the press team, the September 2026 campaign, the maintainer directive dated 2026-09-19 and the off-repo artifact/,/${slug}-{light,dark}(general.astro:80,83), the two/<menu>/${id}families, plusBrochurePage.astro:36-37andStyleSwitch.astro:24. Indist/, every file carrying a-[style]-href is itself a style route/general+ the 24 style routes (25 pages) and carry the preview-gate detailadr/0002:25-27exactlyVerified clean again: "documentation and configuration only" holds — 9 files, all
*.md, nothing undersrc/./nuevo-contenido-completois genuinely obsolete (present atmaster:docs/routes.md:13, no such page insrc/pages/). The "4 topics / 8 pages" claim the PR corrects is really there atmaster:README.md:3. ADR-0001's remote claims matchgit remote -v.Missing or partial
One cosmetic mismatch, non-blocking. Changes item 3 says:
README's route table was deleted, not corrected —
docs/routes.mdis the single inventory now, which is the round-1 de-duplication remediation working as intended. The outcome is right; the body's verb describes the earlier plan.Scope creep
Only the accepted R1-5 residue. The spec line it exceeds is "Agent-skills config (
docs/agents/,CLAUDE.md): Forgejo issue tracker, triage labels, domain-doc consumer rules" — the/wayfinderdependency and label note is adjacent tooling config rather than tracker config. Disclosed and accepted in round 2.Implemented but wrong
Nothing in the diff.
One tracker-side inconsistency, outside the diff. The PR body points at #2 as a follow-up, and #2's body says:
That contradicts ADR-0001 and the PR body's own Migration context — PRs live on Forgejo; GitHub is a backup mirror. Worth a one-line edit to #2 so the CI work is not scoped against the wrong host. Not a reason to hold this PR.
Spec verdict
Nothing blocks merge. All twelve prior Spec findings are genuinely closed except R1-5, which is partial by explicit decision and was never a spec requirement.
Summary — Standards: 16 prior findings re-verified, 12 closed, 4 not fully closed (two of them open by explicit decision, one dropped by round 4 without a verdict), plus 2 new judgement calls; worst = finding 6 was reported CLOSED in rounds 3 and 4 but only half of it was done — the slug/id lists are still stated three times. Spec: 12 prior findings, 11 closed, 1 partial by decision, no new findings in the diff; worst = the PR body's "Route tables … corrected" describes a table that was deleted.
Nothing is recommended before merge on either axis. What is left is three duplication judgement calls (→ #2), one stale verb in the PR body, and a one-line edit to issue #2 so the CI work is not scoped against GitHub.
🤖 Review generated with Claude Code