Skip to content

Decision Log

Architecture Decision Records (ADRs) for the ESG Screening system. Each ADR records one standing design decision: context, what was decided, alternatives, consequences.

The canonical files live in the main repo at docs/adr/. This site renders them for navigability.

For ADR conventions, see the ADR README in the main repo.

ADR index

# Title Status Date Summary
0001 Coverage-weighted scoring Accepted 2026-05-19 Headline scores computed only over rules with live signals; base values retained for audit.
0002 UI architecture: server-rendered read interface Accepted 2026-05-19 Node + Express + EJS/Handlebars + plain CSS at esg-screen.org. No SPA, no build step.
0003 Source register and Methodology page Accepted 2026-05-19 /methodology page generated from DB. Source status, rule catalogue, scoring explainer.
0004 RAG thresholds for score and coverage Accepted 2026-05-19 Score: <40 / 40–69 / ≥70. Coverage: <25% / 25–59% / ≥60%. Dustier-than-pure palette.
0005 Rule grouping in the institution detail UI Accepted 2026-05-19 UI-only thematic grouping ("fossil fuels," "weapons," etc.) on top of formal pillar/sub-criterion hierarchy.
0006 Ops site and canonical hierarchy Proposed 2026-05-19 This ops site as the rendered standing-reference surface. Pending commit.

When to write a new ADR

Per the ADR README, write one when a decision:

  • affects how the system is built, displayed, or scored, AND
  • is non-trivial to reverse, AND
  • a future contributor (including future-you) would benefit from understanding the reasoning.

Examples that should be ADRs:

  • Scoring methodology choices
  • UI architecture
  • Source-register conventions
  • Schema decisions of structural importance
  • Authentication model
  • Framework structure

Examples that should not be ADRs:

  • Bug fixes
  • Individual scraper implementations (those follow the add-a-scraper runbook)
  • Copy edits
  • Dependency upgrades

ADR conventions

  • Numbering: sequential, 4-digit, zero-padded. Never reused.
  • Filename: NNNN-kebab-case-slug.md
  • Status values: Proposed · Accepted · Superseded by NNNN · Deprecated
  • Length: aim for one page, max two. If longer, the decision is probably two decisions — split.
  • Tone: plain language. Audience is a future engineer, not a methodology committee.

ADR process

  1. Decisions surfaced in chat sessions are captured as ADR drafts in that session's outputs (/mnt/user-data/outputs/).
  2. The session-end Slack handoff names the new ADRs.
  3. The next CC-on-VM session commits the ADRs to docs/adr/ as its first action of the cycle.
  4. Code that implements an ADR should reference the ADR number in a comment or PR description.
  5. When an ADR is superseded, both files are updated in the same commit: the old one's status changes to Superseded by NNNN, the new one references it under Supersedes.

Cross-references

ADR Implemented by Referenced by
0001 Migration 011, scoring engine modules 0002 (hero panel design), 0004 (coverage colour)
0002 src/ui/, Express routes 0003 (Methodology page route), 0004 (palette), 0005 (rule table)
0003 Migration 012, /methodology route 0002 (page slot), 0001 (scoring explainer content)
0004 src/config/rag.js, base stylesheet 0002 (where colour is applied), 0001 (coverage band)
0005 src/config/rule-themes.js, detail page template 0002 (rule evaluation section)
0006 This site, Cloudflare Pages deployment All of the above (rendered surface)