Skip to content

ADR-0005: Rule Grouping in the Institution Detail UI

Status: Accepted (2026-05-19) Supersedes: — Superseded by: —

Context

The v0.4 methodology organises rules in a strict hierarchy: pillar (E/S/G) → sub-criterion → rule. This is the right structure for the workbook and the data model, but it is not always the right structure for the screening UI. A user looking at an institution wants to see things like "what's the fossil fuel picture" or "what's the weapons picture" as natural reading units — and those cut across the strict sub-criterion hierarchy.

For example, fossil-fuel-relevant rules include E5.1 (project financing), E5.2 (exit policy), E1.1 (NZBA membership, which is closely related but technically a Climate sub-criterion), and arguably E4.1 (climate disclosure). In the formal hierarchy these are scattered. A user reading the page asks "is this institution involved in fossils, and how do we know?" — and wants the answer in one place.

This ADR records the decision to add a UI-only thematic grouping layer that sits on top of the formal hierarchy, without disturbing it.

Decision

Rules in the institution detail page are presented in thematic groups within the rule evaluation table. Themes are a presentation-layer concept only; they do not affect scoring, pillar weights, or the data model.

Themes for v1. These are the initial groupings; they will be revisited as scrapers land and coverage grows.

Theme Includes rules
Climate & emissions NZBA membership, SBTi targets, IFRS S2 / climate disclosure
Fossil fuels & pipeline financing Fossil project financing (E5.1), fossil exit policy (E5.2)
Weapons & conflict Controversial weapons financing (E6.1), conflict-zone exposure (S5.1)
Governance frameworks PRB signatory, other framework memberships
Social: rights & labour Modern slavery statement, gender pay gap, human rights policy
Social: workforce Board diversity, executive comp
Governance: integrity Enforcement actions, audit independence, tax transparency
Other uncovered Catch-all collapsed group for low-priority uncovered rules

The user can also filter by pillar via filter pills (All / E / S / G / Covered only / Uncovered only), which is orthogonal to thematic grouping. Filter pills control which rules are visible; themes control how visible rules are organised.

Implementation.

  • Themes are defined in a config file (src/config/rule-themes.js) as a mapping of theme_name → list of rule_ids.
  • Themes are not stored in the DB. They are pure UI grouping.
  • A rule can appear in at most one theme. (If a rule has cross-cutting relevance, decide which theme is dominant for v1; revisit if the convention breaks down.)
  • Rules without a theme fall into "Other uncovered" automatically.
  • The order of themes on the page is configured, not alphabetical — fossil and weapons sit near the top because they map to the manual red flags (per v0.4) and are typically the screening-decisive categories.

Consequences

Positive. - The page reads the way a screening conversation actually goes: "let me see the fossil picture, let me see the weapons picture" rather than "let me trawl through 27 rules in sub-criterion order." - Themes give scattered rules a coherent home and surface the questions a user is actually trying to answer. - Filter pills + themes compose well: filter to "Environmental only" and the theme groupings within E still apply.

Negative. - A second classification (theme) alongside the formal one (pillar/sub-criterion) introduces a maintenance overhead. New rules need a theme assignment, and theme definitions need to be reviewed as the rule catalogue grows. - Themes are subjective. "Climate & emissions" vs "Fossil fuels" overlaps in places (Banking on Climate Chaos covers both). Document the convention; revisit when it breaks. - The Methodology page (ADR-0003) shows rules grouped by formal hierarchy, not theme. Users may find the two views inconsistent. Acceptable: the detail page is read for a single institution, where themes help; the Methodology page is a system-wide reference where the formal hierarchy is more useful.

Alternatives considered

  • Use formal sub-criterion grouping as the UI structure. Faithful to the workbook but reads awkwardly: cross-cutting issues fragment.
  • Allow rules to appear in multiple themes. Would mean a rule could show up twice on one page — confusing, and breaks the running totals (covered count per theme).
  • No thematic grouping; just a flat rules table with filter pills. Lighter to build but loses the "fossil picture / weapons picture" reading affordance.
  • User-customisable themes. Premature optimisation. The team is five people; a config file is fine.

References

  • ADR-0002 (UI architecture) — defines the rule evaluation panel
  • ADR-0003 (source register) — Methodology page uses formal hierarchy, not themes
  • v0.4 workbook, Rules sheet — formal hierarchy lives here
  • Manual red flags (fossil, weapons) per v0.4 intake — themes mirror these for visual coherence

Amendment — Rule ID corrections and Climate & nature theme

Date: 2026-05-19 Status: Accepted (amends ADR-0005)

Context

Cycle 3 (read interface) build surfaced two issues with ADR-0005's theme mapping when CC implemented src/config/rule-themes.js against the live database:

  1. The "Fossil fuels & pipeline financing" theme referenced E5.1 and E5.2 as the rule IDs. These are sub-rule numbers, not top-level rule IDs. The actual fossil-fuel rule in the v0.4 workbook and live DB is E2 (Fossil fuel financing policy). E5 is Biodiversity & nature risk.
  2. With E2 correctly placed in the fossil theme, E5 (Biodiversity & nature risk) had no theme — it fell through to 'other'.

CC's implementation in rule-themes.js is correct (uses live rule_ids); the ADR is what was wrong. This is the schema-fiction reconciliation pattern flagged in the 2026-05-19 12:18 handoff: ADRs drafted without live schema access, errors surface only when something exercises them.

Decision

Two corrections to the theme table above:

  1. Fossil fuels theme: rule IDs are E2 (not E5.1 / E5.2). Theme name unchanged: "Fossil fuels & pipeline financing".
  2. Climate theme renamed to "Climate & nature". E5 (Biodiversity & nature risk) joins this theme. Updated rule set: E1, E3, E4, E5.

Other themes unchanged.

Rationale

Why E5 joins climate rather than getting its own theme. Biodiversity is the only nature-risk rule in the current framework (S5 — Indigenous rights / FPIC — is a human-rights rule, not a nature one). A single-rule theme reads as overkill in a UI built around theme groupings. The field itself increasingly frames climate and nature together — TNFD sits alongside TCFD, and the rule set may grow that way too. Folding E5 into a renamed "Climate & nature" theme handles the present without precluding a split later if biodiversity rules multiply.

Why not defer E5 entirely. Leaving E5 in 'other' creates a known-loose-end with no obvious trigger to resolve it. Settling it now costs one line of config and one decision; deferring it means a future amendment and a fresh round of the same discussion.

Consequence

  • src/config/rule-themes.js updated: E5 added to the climate theme; theme label changed to "Climate & nature"
  • ADR-0005 theme table corrected: fossil row references E2; climate row renamed and includes E5
  • E5 no longer falls through to 'other' in the index and detail pages
  • No data or schema change — UI-only grouping per ADR-0005's original scope

Cross-references

  • Commit cbe0c1e — cycle 3 read interface (rule-themes.js with correct rule_ids but missing E5 mapping)
  • 2026-05-19 cycle 3 handoff — carry-forward #1
  • v0.4 workbook sheet 3.3 Criteria & Rules — canonical ID-to-label mapping