feat(plotly): implement heatmap-cohort-retention

[github-actions]

Implementation: heatmap-cohort-retention - plotly

Implements the plotly version of heatmap-cohort-retention.

File: plots/heatmap-cohort-retention/implementations/plotly.py

Parent Issue: #4570

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a triangular cohort retention heatmap with 10 monthly cohorts (Jan–Oct 2024) on the y-axis, each labeled with cohort size (e.g., "Jan 2024 (n=1,200)"). The x-axis shows "Month 0" through "Month 9" labeled "Months Since Signup." Each cell contains the retention percentage in white text. The color scheme uses a custom green sequential gradient from very light green (low retention ~9%) to deep forest green (100%). A colorbar on the right shows "Retention %" from 0% to 100%. The triangular shape is correctly formed — Jan 2024 has all 10 periods while Oct 2024 has only Month 0. Cells have small gaps between them. The title reads "heatmap-cohort-retention · plotly · pyplots.ai" centered at the top. White text on the lightest green cells (9%, 11%) has reduced readability due to low contrast.

Score: 84/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	11	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	7	10
Total	84	100

Visual Quality (27/30)

• VQ-01: Text Legibility (6/8) — Font sizes explicitly set (title=28, labels=22, ticks=16, cell text=15), but white text on light green cells (9%, 11%, 15%) has poor contrast and is hard to read
• VQ-02: No Overlap (6/6) — No overlapping text anywhere
• VQ-03: Element Visibility (6/6) — Cells well-sized, color gradient clearly visible, gaps between cells aid readability
• VQ-04: Color Accessibility (3/4) — Green sequential scale is colorblind-safe, but white-on-light-green contrast issue reduces accessibility
• VQ-05: Layout & Canvas (4/4) — Good use of canvas, balanced margins, heatmap fills the space well
• VQ-06: Axis Labels & Title (2/2) — "Months Since Signup" and "Signup Cohort" are descriptive and appropriate

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom green palette is thoughtful, cell gaps add polish, plotly_white template is clean — above defaults but not publication-level
• DE-02: Visual Refinement (3/6) — plotly_white removes gridlines, cell gaps are a nice touch, good margins — some refinement visible
• DE-03: Data Storytelling (3/6) — The triangular shape and color gradient naturally show retention decay; trend_bonus in data creates a subtle narrative of improving cohorts over time, but no explicit visual emphasis draws attention to this insight

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct triangular cohort retention heatmap
• SC-02: Required Features (4/4) — All spec features present: triangular shape, retention % in cells, cohort sizes in y-labels, colorbar, sequential green colormap
• SC-03: Data Mapping (3/3) — Cohorts on y-axis, periods on x-axis, retention as color intensity
• SC-04: Title & Legend (3/3) — Title format correct: "heatmap-cohort-retention · plotly · pyplots.ai"; colorbar serves as legend

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows retention decay, triangular shape, varying cohort sizes, improving trend for newer cohorts; could show more dramatic variation between cohorts
• DQ-02: Realistic Context (5/5) — SaaS monthly cohort retention is a classic, realistic use case with plausible cohort sizes
• DQ-03: Appropriate Scale (4/4) — Retention values realistic: 100% at Month 0, exponential decay to ~9% at Month 9

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean imports → data → plot → save structure, no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — Only numpy and plotly.graph_objects, both used
• CQ-04: Code Elegance (2/2) — Clean, appropriate complexity, well-organized
• CQ-05: Output & API (1/1) — Saves as plot.png with correct dimensions, also saves HTML

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of go.Heatmap with texttemplate, hovertext, colorbar config; could use plotly express or more advanced layout features
• LM-02: Distinctive Features (3/5) — Leverages Plotly-specific features: rich HTML hovertext, HTML export, texttemplate for cell annotations

Score Caps Applied

• None

Strengths

• Perfect spec compliance — all required features implemented correctly
• Clean, well-structured code with appropriate seed and KISS architecture
• Custom green colorscale is visually appealing and appropriate for retention data
• Rich hover text with HTML formatting leverages Plotly's interactivity
• Cell gaps (xgap/ygap) add visual clarity between cells

Weaknesses

• White text on light green cells (low retention values like 9%, 11%) has poor contrast and is hard to read
• Design could be elevated with more visual storytelling — e.g., highlighting the improving retention trend across cohorts
• Cell text font could use conditional coloring (dark text on light cells, white text on dark cells)

Issues Found

1. VQ-01/VQ-04 MEDIUM: White text on light green cells has poor contrast
   • Fix: Use conditional text color — dark text for light cells, white text for dark cells
2. DE-01 MEDIUM: Good but not publication-level design
   • Fix: Consider adding subtle annotation or visual emphasis to highlight retention trends
3. DE-03 LOW: Retention improvement trend across cohorts is not visually emphasized
   • Fix: Use color contrast or annotations to draw attention to the improving cohort quality narrative

AI Feedback for Next Attempt

Fix the text contrast issue: use dark text color on light cells and white on dark cells (threshold around 50% retention). This is the most impactful improvement. Also consider adding a subtle visual element to emphasize the improving retention trend across newer cohorts, such as a brief annotation or visual highlight on the diagonal.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/3

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

The plot displays a triangular cohort retention heatmap with 10 monthly cohorts (Jan 2024 – Oct 2024) on the y-axis and Months 0–9 on the x-axis. A custom teal-green sequential colorscale runs from very light green (low retention, ~9%) to deep forest green (100% retention). Each cell contains a bold percentage annotation with conditional text coloring — white text on dark cells, dark green text on light cells. The y-axis labels include cohort sizes in parentheses (e.g., "Jan 2024 (n=1,200)"). The triangular shape is clearly visible: Jan 2024 spans all 10 months while Oct 2024 has only Month 0. A colorbar on the right displays "Retention Rate" with percentage ticks from 0–100%. A subtle green annotation at the bottom reads "↑ Later cohorts retain better". The background is a soft off-white (#fafafa) with the plotly_white template providing a clean, minimal chrome appearance. Cell gaps of 3px create clear visual separation between cells.

Score: 91/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	14	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	91	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 28, axes 22, ticks 16-17, cell text 15, colorbar 18/16). Cell annotation font at 15 is adequate but slightly small relative to overall plot size.
• VQ-02: No Overlap (6/6) — No overlapping text anywhere. Cell gaps and margin sizing prevent all collisions.
• VQ-03: Element Visibility (6/6) — Heatmap cells are well-sized with 3px gaps providing clear separation. All cells easily distinguishable.
• VQ-04: Color Accessibility (4/4) — Green sequential colorscale is colorblind-safe. Conditional text coloring (dark on light, white on dark) ensures readability across all retention values.
• VQ-05: Layout & Canvas (4/4) — Plot fills canvas well with balanced margins (l=195, r=90, t=75, b=95). The triangular shape naturally leaves white space in the upper-right but this is inherent to the data.
• VQ-06: Axis Labels & Title (2/2) — "Months Since Signup" and "Signup Cohort" are descriptive. Units not applicable for this plot type.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Custom 7-stop teal-green colorscale with good perceptual uniformity. Conditional text coloring (#1a2e1a vs white) is a thoughtful design choice. Custom font family, off-white background, and cell gaps create a polished look clearly above defaults.
• DE-02: Visual Refinement (4/6) — plotly_white template removes gridlines, 3px cell gaps provide clean separation, generous whitespace, custom background color. Good refinement visible.
• DE-03: Data Storytelling (4/6) — The "↑ Later cohorts retain better" annotation guides interpretation. The trend_bonus in data generation creates a visible improving pattern across cohorts that tells a clear story. Visual hierarchy through color intensity naturally draws attention to retention drop-off patterns.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct triangular heatmap with NaN masking for future periods.
• SC-02: Required Features (4/4) — All spec features present: triangular shape, 100% at period 0, retention % text in cells, cohort sizes next to labels, sequential green colorscale, colorbar legend.
• SC-03: Data Mapping (3/3) — X=months since signup, Y=cohort labels (reversed for chronological order), Z=retention rate. All data visible.
• SC-04: Title & Legend (3/3) — Title "heatmap-cohort-retention · plotly · pyplots.ai" matches required format. Colorbar serves as legend with "Retention Rate" label and % suffix.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows full retention decay curves, triangular shape from cohort age differences, cohort size variation (900–1,450), improving trend in later cohorts, and range from 100% down to 9%.
• DQ-02: Realistic Context (5/5) — SaaS monthly cohort retention is a classic, neutral business analytics scenario. Cohort sizes and labels are realistic.
• DQ-03: Appropriate Scale (4/4) — Retention values follow realistic exponential decay. Period 0 = 100%, rapid initial drop-off, gradual decline to single digits. Cohort sizes (900–1,450) are plausible for a SaaS product.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data generation → hover/annotations → plot → style → save.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ensures deterministic output.
• CQ-03: Clean Imports (2/2) — Only numpy and plotly.graph_objects, both fully utilized.
• CQ-04: Code Elegance (2/2) — Appropriate complexity. Conditional text coloring logic is clean. No fake UI or over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot.png with correct 4800×2700 dimensions (1600×900 × scale=3). Also exports HTML.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Good use of go.Heatmap with proper parameters (xgap, ygap, colorscale, colorbar dict). fig.add_annotation for cell text and storytelling note. update_layout with plotly patterns.
• LM-02: Distinctive Features (4/5) — Rich HTML hover tooltips with formatted cohort info (a Plotly-exclusive interactive feature). HTML export via write_html. Colorbar customization with ticksuffix. These are distinctly Plotly capabilities.

Score Caps Applied

• None — no caps triggered.

Strengths

• Excellent triangular shape implementation with NaN masking for unavailable periods
• Custom 7-stop teal-green colorscale with good perceptual uniformity
• Smart conditional text coloring (dark on light cells, white on dark cells) for universal readability
• Rich HTML hover tooltips showing cohort name, period, size, and retention — leveraging Plotly's interactivity
• Storytelling annotation "↑ Later cohorts retain better" guides viewer interpretation
• Data shows realistic retention decay with an improving trend across cohorts

Weaknesses

• Cell annotation font size (15) could be slightly larger for improved readability at full resolution
• LM-01 could reach 5 by using plotly.express or more advanced Plotly patterns

Issues Found

No blocking issues found. Implementation meets all spec requirements with good design quality.

AI Feedback for Next Attempt

N/A — implementation approved.

Verdict: APPROVED