Saltar al contenido principal

GitHub Issues #5 and #6 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Finish and verify the resident-facing flooding and audit improvements requested by GitHub issues #5 and #6 on one existing branch.

Architecture: Preserve the existing uncommitted content rewrite and complete its one known gap with two optimized current-state photographs. Enforce the content contract with lightweight Node tests, expose those tests through npm and GitHub Actions, and validate the result through both Docusaurus builds plus visual inspection of the private site.

Tech Stack: Docusaurus 3.10, MDX, Node.js built-in test runner, GitHub Actions, WebP via cwebp.

Global Constraints​

  • Work in place on codex/recent-github-issues; the approved design explicitly preserves the existing uncommitted draft.
  • Keep both GitHub issues in this branch and session.
  • Do not create another worktree, stash, reset, discard, or overwrite the existing relevant changes.
  • Do not commit, push, open or update a pull request, mutate either issue, or deploy without separate user authorization.
  • Preserve the Spanish resident-facing voice and all verified financial figures.
  • Describe the photographs only at the level supported by the visible scene and source records.
  • Use native Markdown for mission chronologies; do not introduce Mermaid or another timeline component.
  • Follow red-green-refactor for every new behavior added during this session.

Task 1: Add a failing regression test for the missing current EDAR evidence​

Files:

  • Modify: scripts/missionTimelineContent.test.js
  • Test: scripts/missionTimelineContent.test.js

Interfaces:

  • Consumes: missionPage(name) and repository-relative file checks already defined in the test.

  • Produces: a content contract requiring both dated current photographs and language that separates restored equipment from unfinished grounds maintenance.

  • Step 1: Add the missing-current-evidence test

Append this test immediately after the flood page distinguishes restored EDAR damage from flood causality:

test("the flood page shows dated current EDAR grounds evidence", () => {
  const page = missionPage("evitar-inundaciones");
  const currentImages = [
    "edar-restaurada-2026-07-18.webp",
    "edar-entorno-arbol-2026-07-18.webp",
  ];

  for (const fileName of currentImages) {
    assert.ok(
      page.includes(`/img/evitar-inundaciones/${fileName}`),
      `${fileName} must be referenced by the flood page`,
    );
    assert.equal(
      existsSync(
        path.join(
          root,
          "static-vecinos",
          "img",
          "evitar-inundaciones",
          fileName,
        ),
      ),
      true,
      `${fileName} must exist in the private static assets`,
    );
  }

  assert.match(page, /18 de julio de 2026/);
  assert.match(page, /en abril de 2026[^.]*ya no estaba averiada/i);
  assert.match(page, /hojas|restos vegetales/i);
  assert.match(page, /árbol[^.\n]*(?:roto|caído)|(?:roto|caído)[^.\n]*árbol/i);
  assert.match(page, /mantenimiento del entorno/i);
});
  • Step 2: Run the focused test and verify RED

Run:

node --test scripts/missionTimelineContent.test.js

Expected: FAIL in the flood page shows dated current EDAR grounds evidence because edar-restaurada-2026-07-18.webp is not referenced.

  • Step 3: Confirm the failure is behavioral

Verify that the failure comes from the missing image reference, not a syntax error or test setup problem. Do not change production content until this exact failure is observed.

Task 2: Optimize the two issue photographs and complete the EDAR section​

Files:

  • Create: static-vecinos/img/evitar-inundaciones/edar-restaurada-2026-07-18.webp
  • Create: static-vecinos/img/evitar-inundaciones/edar-entorno-arbol-2026-07-18.webp
  • Modify: vecinos/misiones/evitar-inundaciones/index.mdx
  • Test: scripts/missionTimelineContent.test.js

Interfaces:

  • Consumes: private issue photographs downloaded to /private/tmp/las-vinas-issue-5-edar-restored and /private/tmp/las-vinas-issue-5-edar-hazard.

  • Produces: stable /img/evitar-inundaciones/*.webp URLs referenced by the private MDX page.

  • Step 1: Convert the landscape current-state photograph

Run:

cwebp -quiet -metadata none -resize 1600 0 -q 78 \
  /private/tmp/las-vinas-issue-5-edar-restored \
  -o static-vecinos/img/evitar-inundaciones/edar-restaurada-2026-07-18.webp

Expected: a 1600×1200 WebP without EXIF metadata.

  • Step 2: Convert the portrait tree-hazard photograph

Run:

cwebp -quiet -metadata none -resize 0 1600 -q 78 \
  /private/tmp/las-vinas-issue-5-edar-hazard \
  -o static-vecinos/img/evitar-inundaciones/edar-entorno-arbol-2026-07-18.webp

Expected: a 1200×1600 WebP without EXIF metadata.

  • Step 3: Verify image dimensions and compression

Run:

identify -format '%f %wx%h %b\n' \
  static-vecinos/img/evitar-inundaciones/edar-restaurada-2026-07-18.webp \
  static-vecinos/img/evitar-inundaciones/edar-entorno-arbol-2026-07-18.webp

Expected: 1600x1200 and 1200x1600; each output must be substantially smaller than its 8.8 MB or 4.7 MB JPEG source.

  • Step 4: Add current-state content after the two historical EDAR photographs

Replace the single paragraph beginning El [acta de la junta de propietarios de 20 de enero de 2026] with:

El [acta de la junta de propietarios de 20 de enero de 2026](/vecinos/manual/gobernanza-y-legal/juntas-de-propietarios/2026-01-20) informó de que **los trabajos de restauración ya estaban acabados**. Incluyeron la limpieza de la caseta, del depósito y del canal de entrada, la renovación de cuadros y cableado y la sustitución de bombas y boyas. En abril de 2026 la EDAR ya no estaba averiada.

Estas fotografías del **18 de julio de 2026** muestran el estado exterior actual del recinto:

![Estado exterior actual del acceso a la EDAR: tapas azules cerradas, vegetación y hojas acumuladas junto al muro](/img/evitar-inundaciones/edar-restaurada-2026-07-18.webp)

*Estado exterior del acceso después de la restauración. La instalación ya no está averiada, aunque se observan hojas y vegetación acumuladas en el entorno.*

![Árbol roto e inclinado sobre el recinto de la EDAR, detrás del cerramiento](/img/evitar-inundaciones/edar-entorno-arbol-2026-07-18.webp)

*El mantenimiento del entorno sigue pendiente: además de los restos vegetales, hay un árbol roto e inclinado sobre el recinto que debe revisarse y retirarse de forma segura.*

La restauración de la EDAR resolvió los daños de la instalación, pero no sustituye el mantenimiento preventivo del entorno ni la obra pluvial necesaria para evitar que vuelva a entrar la escorrentía.
  • Step 5: Run the focused test and verify GREEN

Run:

node --test scripts/missionTimelineContent.test.js

Expected: all mission timeline and flooding content tests PASS.

  • Step 6: Inspect the optimized assets directly

Open both WebP files and confirm that the access covers, leaves, broken tree, and enclosure remain legible with no visible rotation or severe compression artifacts.

Task 3: Make the resident content tests a maintained project check​

Files:

  • Modify: package.json
  • Modify: .github/workflows/pr-checks.yml
  • Test: scripts/internalAuditContent.test.js
  • Test: scripts/missionTimelineContent.test.js

Interfaces:

  • Consumes: the two root-level Node content test files.

  • Produces: npm run test:content, called locally and by the PR workflow.

  • Step 1: Add the npm script

Insert after test:liquidaciones-gastos in package.json:

"test:content": "node --test scripts/internalAuditContent.test.js scripts/missionTimelineContent.test.js",
  • Step 2: Run the npm test command locally

Run:

npm run test:content

Expected: all audit, chronology, flooding, media, and current-evidence tests PASS.

  • Step 3: Add the PR workflow step

Insert after the Lint step in .github/workflows/pr-checks.yml:

      - name: Test Resident Content
        run: npm run test:content
  • Step 4: Validate the workflow diff

Run:

git diff --check -- package.json .github/workflows/pr-checks.yml

Expected: no output and exit code 0.

Task 4: Verify every acceptance criterion and both production builds​

Files:

  • Verify: vecinos/misiones/evitar-inundaciones/index.mdx
  • Verify: vecinos/misiones/evitar-inundaciones/registros/inundacion-de-2020.mdx
  • Verify: vecinos/misiones/*/index.mdx
  • Verify: vecinos/manual/economia/auditorias/2026-07-12-internal-audit.mdx
  • Verify: src/theme/MDXComponents.js
  • Verify: scripts/internalAuditContent.test.js
  • Verify: scripts/missionTimelineContent.test.js

Interfaces:

  • Consumes: the complete working-tree implementation for issues #5 and #6.

  • Produces: evidence that tests, syntax, builds, links, responsive media, and resident-facing narratives are correct.

  • Step 1: Run all focused checks

Run:

npm run test:content
npm run test:liquidaciones-gastos
git diff --check

Expected: both test commands PASS and git diff --check emits nothing.

  • Step 2: Run lint

Run:

npm run lint

Expected: exit code 0, no errors, and no warnings introduced in files changed for issues #5 or #6. Record the repository’s pre-existing warning count separately.

  • Step 3: Build the public site

Run:

npm run build

Expected: Docusaurus reports successful generation of the public static files.

  • Step 4: Build the private site

Run:

npx docusaurus build --config docusaurus.config.vecinos.js --out-dir build-vecinos

Expected: Docusaurus reports successful generation of build-vecinos.

  • Step 5: Serve the private build for visual verification

Run:

npx docusaurus serve --dir build-vecinos --host 127.0.0.1 --port 3100

Open http://127.0.0.1:3100/vecinos/misiones/evitar-inundaciones/ and http://127.0.0.1:3100/vecinos/manual/economia/auditorias/2026-07-12-internal-audit/.

Expected:

  • the video is responsive and precedes the chronology;

  • the Markdown chronology is readable without client-side diagram rendering;

  • the water-route and project-plan sections render in the intended order;

  • the two current photographs render with their captions and remain legible;

  • the warning admonition renders correctly;

  • no raw repository terminology appears in the resident-facing audit; and

  • affected internal links resolve inside /vecinos/.

  • Step 6: Repeat the flooding-page inspection at a narrow viewport

Use a viewport approximately 390×844. Confirm that the portrait video, project plan, current photographs, lists, and tables do not overflow horizontally.

  • Step 7: Review the complete diff against both issue bodies

Run:

git diff --stat
git status --short

Check every issue #5 requirement: repaired EDAR status, cause/effect, both current photos, southern water route, project illustration, Markdown timelines everywhere, top video, meeting tense, and related-record consistency.

Check every issue #6 requirement: correct admonition, exact “No se ha modificado ningún dato.” sentence, no confusing codebase terms in the report, and a simplified final methodology.

  • Step 8: Stop before any repository publication action

Report the changed files and verification evidence. Ask before staging, committing, pushing, creating a pull request, closing issues, or deploying.