Saltar al contenido principal

GitHub Issues #5 and #6 Design

Status: Approved in conversation on 19 July 2026

Objective​

Resolve GitHub issues #5 and #6 together on the existing codex/recent-github-issues branch. The result must make the flooding mission accurate and easier for residents to follow, replace the custom mission timelines with native Markdown, and rewrite the internal audit so it reads naturally without access to the repository.

No commit, push, pull request, issue closure, or deployment is part of this work unless the user authorizes it separately.

Existing Work​

The branch already contains an uncommitted draft that:

  • converts the mission chronologies to Markdown;
  • removes the custom Timeline component and mission _timeline.js files;
  • restructures the flooding narrative around the southern runoff route;
  • embeds the DANA video in the executive summary;
  • adds an extracted and optimized plan image from the 2023 Global Omnium project;
  • sanitizes the resident-facing audit and fixes its Docusaurus admonition; and
  • adds focused Node content tests.

This work will be preserved and completed. The principal known gap is that the two current photographs attached to issue #5 have not been optimized, added to the site, or covered by a regression test.

Design Decisions​

Native mission chronologies​

Every mission chronology will be an ordinary Markdown bullet list. Each event retains its date, state or title, explanation, and link. The shared React Timeline component, its MDX registration, and the eight mission-specific _timeline.js files will be removed because they no longer have consumers.

Markdown is preferred over Mermaid because these chronologies are short reading sequences, not relationship diagrams. Markdown remains searchable, accessible, responsive, and readable if client-side diagram rendering fails.

Flooding narrative and causal chain​

vecinos/misiones/evitar-inundaciones/index.mdx will present the evidence in this order:

  1. The executive summary states the history, southern runoff mechanism, structural proposal, and current EDAR status.
  2. The DANA video provides immediate visual evidence of the flooding inside Las Viñas.
  3. The Markdown chronology records the documented events from 2020 through the June 2026 council meeting.
  4. “Cómo entra y sale el agua” explains that runoff from the southern upstream catchments concentrates by the triangular parcel, overtops the road level, crosses Las Viñas, and exits toward the barranco.
  5. The 2023 project plan illustrates the proposed channel, 1,400 mm collector, coordinated wall and drainage, and barranco outlet.
  6. The official maps are explained as incomplete evidence for the route observed inside Las Viñas, not as proof that the water entered from the northwest.
  7. The technical diagnosis distinguishes the flood cause from its consequences: the flood damaged and obstructed the EDAR; the damaged EDAR then created a separate sanitary and operational risk.
  8. The solution and administrative sections describe the structural works, interim maintenance, and current institutional status.

The narrative will remain consistent with the 2020 flood report, the 2023 project and registered instance, the June 2026 council meeting record, the individual containment guidance, and the water and sanitation manual.

EDAR status and current photographs​

The page will not describe the EDAR as still broken. It will state the two pieces of dated evidence without inventing an exact completion day:

  • the 20 January 2026 owners’ meeting minutes reported that the restoration works had finished; and
  • issue #5 confirms that the EDAR was no longer broken by April 2026.

The two photographs taken on 18 July 2026 will be converted from JPEG to metadata-free WebP and resized to a web-appropriate maximum dimension while retaining enough detail to inspect the scene.

  • The landscape photograph will document the current exterior/access area after restoration, including the blue access covers and accumulated leaves.
  • The portrait photograph will document the broken or fallen tree leaning over the enclosure and the surrounding vegetation.

Captions and alternative text will describe only what the photographs show. They will not claim to show internal EDAR machinery or prove the installation’s operating condition. The text will distinguish successful EDAR restoration from unfinished grounds maintenance and the tree hazard.

Audit for resident readers​

vecinos/manual/economia/auditorias/2026-07-12-internal-audit.mdx will retain the financial findings, totals, confidence levels, limitations, discrepancies, and recommendations while removing repository-oriented language from the main report.

The resident-facing sections must not depend on knowledge of:

  • JSON files, object identifiers, source-code paths, or internal field names;
  • repository directory layout;
  • hashes or ZIP members; or
  • OCR and rendering implementation details.

Those concepts will be translated into ordinary terms such as “liquidación”, “partida”, “factura”, “justificante”, “documentación consultada”, and “comprobación visual”. A short final section, “Nota metodológica sobre las fuentes”, will explain source coverage, deduplication, assisted transcription, visual verification, and removal of personal data.

The conclusions admonition will use Docusaurus 3 syntax:

:::warning[Estado de las conclusiones]

No se ha modificado ningún dato.

:::

File Responsibilities​

  • vecinos/misiones/evitar-inundaciones/index.mdx: flooding narrative, video, chronology, causal explanation, project illustration, current EDAR status, and current photographs.
  • vecinos/misiones/evitar-inundaciones/registros/inundacion-de-2020.mdx: stable cross-link to the new water-route section and matching route description.
  • vecinos/misiones/*/index.mdx: native Markdown chronologies.
  • src/components/Timeline/index.js: deleted after all consumers are migrated.
  • src/theme/MDXComponents.js: remove the obsolete global Timeline registration.
  • vecinos/misiones/*/_timeline.js: delete obsolete chronology data modules.
  • static-vecinos/img/evitar-inundaciones/proyecto-planta-general-actuaciones.webp: optimized plan illustration extracted from the 2023 project.
  • static-vecinos/img/evitar-inundaciones/edar-restaurada-2026-07-18.webp: optimized current exterior/access photograph.
  • static-vecinos/img/evitar-inundaciones/edar-entorno-arbol-2026-07-18.webp: optimized grounds and broken-tree photograph.
  • vecinos/manual/economia/auditorias/2026-07-12-internal-audit.mdx: resident-readable audit and final methodological note.
  • scripts/missionTimelineContent.test.js: regression checks for chronology migration, flooding evidence, media placement, EDAR causality, and current photographs.
  • scripts/internalAuditContent.test.js: regression checks for the admonition, methodology placement, and absence of repository internals from resident-facing sections.
  • package.json: expose a focused root content-test command.
  • .github/workflows/pr-checks.yml: run the focused content tests before both production builds.

Test and Verification Strategy​

Implementation will follow a red-green-refactor cycle for the remaining behavior:

  1. Extend the flooding content test to require both optimized current photographs, their dated context, and language separating restored equipment from grounds maintenance.
  2. Run the focused test and confirm that it fails because the photographs and current-state content are absent.
  3. Add the optimized assets and minimal MDX changes needed to pass.
  4. Run both focused content tests and confirm they pass.
  5. Add the root test command and PR workflow step, then run the command locally.
  6. Run git diff --check.
  7. Run npm run lint; no new errors or warnings may be introduced. Existing repository warnings will be reported separately.
  8. Build the public site with npm run build.
  9. Build the private site with npx docusaurus build --config docusaurus.config.vecinos.js --out-dir build-vecinos.
  10. Serve and inspect the affected private pages at desktop and narrow mobile widths, checking image rendering, captions, video responsiveness, chronology readability, headings, admonitions, and internal links.
  11. Review the final diff against every acceptance point in issues #5 and #6.

Failure Handling​

  • A missing or invalid image path must fail the private build or focused content test.
  • A chronology that reintroduces the custom component, Mermaid, or an _timeline.js file must fail the content test.
  • Repository-oriented audit terms outside the final methodology must fail the audit content test.
  • If image conversion materially harms legibility, increase the WebP dimensions or quality and compare again before accepting it.
  • If the existing uncommitted draft conflicts with a verified source record, preserve the source record and revise the draft rather than weakening the evidence.

Acceptance Criteria​

  • Every requirement in issues #5 and #6 is represented in the content or tests.
  • The EDAR is not described as the cause of the flood or as currently broken.
  • The current EDAR-area and tree photographs appear with accurate alternative text and substantially smaller file sizes than their 8.8 MB and 4.7 MB originals.
  • The route from the southern triangular parcel to the barranco is understandable without reading the codebase or opening the source PDF.
  • All eight mission pages use native Markdown chronologies, with no Timeline implementation left.
  • The audit reads naturally to residents and ends with a simplified methodological note.
  • The Docusaurus 3 admonition renders correctly and says “No se ha modificado ningún dato.”
  • Focused content tests, lint, public build, and private build complete successfully, with no new warnings attributable to this work.
  • All work remains on codex/recent-github-issues; no commit, push, issue mutation, or deployment occurs without separate authorization.