update(arc-basic): plotly — comprehensive quality review

[MarkusNeusinger]

Summary

Updated plotly implementation for arc-basic.

Changes: Comprehensive quality review and update

Changes

• Updated implementation with improved code quality and visual design

Test Plan

• Preview images uploaded to GCS staging
• Implementation file passes ruff format/check
• Metadata YAML updated with current versions
• Automated review triggered

---

Generated with Claude Code /update command

[Copilot]

Pull request overview

Updates the arc-basic Plotly implementation and its metadata as part of a “comprehensive quality review”, focusing on refreshed styling/hover behavior and metadata version bumps.

Changes:

• Updated Plotly arc rendering styles (weight-based color/width) and hover details.
• Tweaked layout/visual design (baseline, margins, title/label styling).
• Updated metadata versions/timestamps and quality score field.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
plots/arc-basic/metadata/plotly.yaml	Refreshes generation metadata (versions, timestamps) and quality score value.
plots/arc-basic/implementations/plotly.py	Improves arc styling, hover behavior, and overall layout/visual presentation.

[Copilot]

quality_score changing from an integer to null is likely to break any consumers expecting a numeric score (sorting, thresholds, dashboards). If the score is unknown, consider omitting the field or using a consistent sentinel your pipeline supports (e.g., keep prior numeric score or use 0/-1 if that’s the established convention).

[Copilot]

quality_score changing from an integer to null is likely to break any consumers expecting a numeric score (sorting, thresholds, dashboards). If the score is unknown, consider omitting the field or using a consistent sentinel your pipeline supports (e.g., keep prior numeric score or use 0/-1 if that’s the established convention).

Suggested change

	quality_score: null
	quality_score: 36

[Copilot]

The header now includes Quality: /100 without a numeric value, which reads like a formatting regression and makes the metadata in the file ambiguous. Populate the score (if available) or change the label to something explicit like Quality: N/A to avoid confusion.

Suggested change

	Quality: /100 | Updated: 2026-02-23
	Quality: N/A | Updated: 2026-02-23

[Copilot]

The add_shape call is packed into a single long line, which makes future edits (e.g., changing baseline range or line style) harder and increases diff noise. Consider formatting the keyword arguments across multiple lines for readability and consistency with the surrounding update_layout style.

Suggested change

	type="line", x0=x_positions[0] - 0.3, x1=x_positions[-1] + 0.3, y0=0, y1=0, line={"width": 1.5, "color": "#CCCCCC"}
	type="line",
	x0=x_positions[0] - 0.3,
	x1=x_positions[-1] + 0.3,
	y0=0,
	y1=0,
	line={
	"width": 1.5,
	"color": "#CCCCCC",
	},

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays a basic arc diagram with 10 character nodes (Alice, Bob, Carol, David, Eve, Frank, Grace, Henry, Iris, Jack) arranged evenly along a horizontal gray baseline. Curved parabolic arcs connect node pairs above the line. Arc height is proportional to the distance between connected nodes — long-range connections (e.g., Alice-Iris, Carol-Jack) produce tall arcs reaching near the top, while short-range connections (e.g., Alice-Bob) produce small arcs near the baseline. Arc opacity and line width encode connection weight across 3 levels: weight 1 = thin/faint, weight 2 = medium, weight 3 = thick/opaque. All arcs use a single blue hue (#306998). Nodes are yellow circles (#FFD43B) with blue outlines. Node labels appear below the baseline in dark gray text. The title "arc-basic · plotly · pyplots.ai" is centered at top. Background is clean white with the plotly_white template.

Score: 86/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 30pt, node labels 18pt), but node labels at 18pt are slightly below the 20pt guideline for labels at this resolution
• VQ-02: No Overlap (6/6) — No text collisions; overlapping arcs are distinguishable via varying opacity
• VQ-03: Element Visibility (5/6) — Nodes and most arcs clearly visible; weakest arcs (weight 1: opacity 0.30, width 2.0) are somewhat faint
• VQ-04: Color Accessibility (4/4) — Single-hue blue palette with opacity encoding is inherently colorblind-safe; yellow nodes contrast well
• VQ-05: Layout & Canvas (3/4) — Plot fills canvas well horizontally, arcs use vertical space effectively, but some wasted space below the baseline/labels
• VQ-06: Axis Labels & Title (2/2) — Title correctly formatted; axes appropriately hidden for arc diagrams; node labels serve as identifiers

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (5/8) — Cohesive blue-yellow palette with intentional opacity/width encoding for weight; above default styling but not quite publication-level polish
• DE-02: Visual Refinement (5/6) — Axes fully hidden, subtle gray baseline, clean plotly_white template, compact margins; shows clear design intent
• DE-03: Data Storytelling (4/6) — Weight encoding through opacity/width creates visual hierarchy; arc height naturally highlights long-range vs short-range connections; viewer can distinguish connection patterns

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct arc diagram with nodes on horizontal line and curved arcs above
• SC-02: Required Features (4/4) — All spec features present: arcs above axis, height proportional to distance, semi-transparent arcs, readable labels, color/weight encoding
• SC-03: Data Mapping (3/3) — Nodes correctly positioned along x-axis, arcs correctly connect specified pairs, heights proportional to node distance
• SC-04: Title & Legend (3/3) — Title format correct (arc-basic · plotly · pyplots.ai); no legend needed for single-hue opacity encoding (hover provides details)

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows short-range and long-range connections, varying weights (1-3), different connection densities per node; good variety but could show more extreme patterns
• DQ-02: Realistic Context (5/5) — Character interactions in a story narrative is a real-world, neutral, comprehensible scenario directly aligned with the spec's applications
• DQ-03: Appropriate Scale (4/4) — 10 nodes (within spec's 10-50 range), 12 edges with realistic density, weights 1-3

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data → styling config → figure → arc loop → nodes → baseline → layout → save
• CQ-02: Reproducibility (2/2) — All data is hardcoded/deterministic, no random elements
• CQ-03: Clean Imports (2/2) — Only numpy and plotly.graph_objects, both used
• CQ-04: Code Elegance (2/2) — Clean arc drawing loop, well-structured arc_styles dict for weight mapping, appropriate complexity
• CQ-05: Output & API (1/1) — Saves plot.png at 1600×900 scale=3 (4800×2700) and plot.html; current Plotly API

Library Mastery (6/10)

• LM-01: Idiomatic Usage (3/5) — Uses go.Figure(), go.Scatter(), add_trace(), update_layout(), add_shape() correctly but doesn't leverage higher-level Plotly patterns or Express API
• LM-02: Distinctive Features (3/5) — Interactive hover tooltips showing connection details, custom hoverlabel styling, HTML export for full interactivity — these are Plotly-distinctive features

Score Caps Applied

• None — no cap conditions triggered

Strengths

• Perfect spec compliance — all features from the specification are implemented correctly
• Clean, well-structured code with appropriate complexity and no over-engineering
• Effective weight encoding through opacity and line width creates meaningful visual hierarchy
• Good data choice — character interactions in narrative is realistic and directly relevant to the spec's applications
• Interactive hover tooltips add value for the Plotly version

Weaknesses

• Node label font size (18pt) slightly below the 20pt guideline — increase to 20pt or higher
• Weakest arcs (weight 1) at opacity 0.30 are somewhat faint — consider increasing minimum opacity to 0.40
• Vertical space below the baseline is underutilized — tighten y-axis lower bound or add a subtitle/annotation
• Library mastery could be improved — consider using more advanced Plotly features (e.g., custom colorscale, animation frames, or more sophisticated hover templates)

Issues Found

1. VQ-01 MINOR: Node label font size 18pt below 20pt guideline
   • Fix: Increase textfont size to 20-22pt
2. VQ-03 MINOR: Weakest arcs barely visible at 0.30 opacity
   • Fix: Raise minimum opacity to 0.40 and minimum width to 2.5
3. VQ-05 MINOR: Some wasted vertical space below baseline
   • Fix: Adjust y-axis range lower bound from -0.6 to -0.4, or add a subtitle with context
4. LM-01 LOW: Basic Plotly usage without leveraging advanced patterns
   • Fix: Use more expressive hover templates, consider gradient coloring for arcs, or add animation/transition features

AI Feedback for Next Attempt

To reach 90+: (1) Increase node label font to 20pt+ for full VQ-01 marks. (2) Raise the minimum arc opacity to 0.40 so all connections are clearly visible. (3) Improve layout by tightening the bottom margin or adding a subtitle. (4) Boost library mastery by using more distinctive Plotly features — e.g., gradient-colored arcs using colorscale, richer hover templates with HTML formatting, or a weight legend using custom legend entries. (5) Consider adding more visual storytelling — highlight the strongest connections or annotate the longest-range arc to create a clear focal point.

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 basic arc diagram with 10 character nodes (Alice, Bob, Carol, David, Eve, Frank, Grace, Henry, Iris, Jack) arranged along a horizontal baseline near the bottom of the canvas. Curved parabolic arcs connect pairs of nodes above the line, with arc height proportional to the distance between connected nodes. Arcs are rendered in a graduated blue color scheme: dark navy blue with high opacity and thick width for Strong (3) connections, medium blue with moderate opacity and width for Medium (2), and light pale blue with low opacity and thin width for Weak (1). A legend titled "Connection Strength" in the upper right classifies the three weight levels. Yellow circular markers with dark blue outlines represent the nodes. A subtle gray horizontal baseline runs through the node positions. An annotation with an arrow points to the tallest arc (Alice–Iris) labeled "longest range." The title "arc-basic · plotly · pyplots.ai" is centered at the top. The background is clean white.

Score: 87/100

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

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set throughout (title=30, node labels=22, legend title=16, legend items=14). Annotation text at 14pt is slightly small for the 4800×2700 canvas.
• VQ-02: No Overlap (6/6) — All text is fully readable with no collisions. Node labels are well-spaced. Legend is positioned clear of arcs.
• VQ-03: Element Visibility (5/6) — Nodes (size 26) and arcs (widths 2.5–5.0) are well-sized. The weakest arcs (alpha 0.40, width 2.5) are somewhat faint but remain distinguishable.
• VQ-04: Color Accessibility (4/4) — Single-hue blue scheme with varying intensity is inherently colorblind-safe. Yellow nodes provide strong contrast against blue arcs.
• VQ-05: Layout & Canvas (3/4) — Good horizontal spread. However, the y-axis range extends to 4.5 while most arcs peak around 3.6, and the entire region below the baseline is empty, resulting in some wasted vertical space.
• VQ-06: Axis Labels & Title (1/2) — Title in correct format. Axes are appropriately hidden for an arc diagram. Node labels are descriptive character names but no units concept applies to this plot type.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: custom blue palette with intentional weight encoding through color intensity + opacity + line width. Python-themed yellow/blue node styling. Cohesive color scheme clearly above library defaults.
• DE-02: Visual Refinement (4/6) — Good refinement: all axis elements hidden, subtle gray baseline shape, legend with semi-transparent background and subtle border, tight margins. Above defaults but not fully polished.
• DE-03: Data Storytelling (4/6) — Weight encoding creates clear visual hierarchy (strong connections pop, weak ones fade). The "longest range" annotation provides a focal point. Viewer can immediately distinguish connection patterns.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct arc diagram: nodes on horizontal line, curved arcs above.
• SC-02: Required Features (4/4) — All spec features present: arc height proportional to distance, semi-transparent arcs, readable node labels, color coding by weight, weight-based arc thickness.
• SC-03: Data Mapping (3/3) — Nodes correctly positioned with linspace, arcs connect correct pairs, heights scale with node distance.
• SC-04: Title & Legend (3/3) — Title "arc-basic · plotly · pyplots.ai" in correct format. Legend shows "Connection Strength" with three labeled weight levels.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all arc diagram aspects: short-range and long-range connections, three weight levels, overlapping arcs, varying densities across the node sequence.
• DQ-02: Realistic Context (5/5) — Character interactions in a story narrative — neutral, comprehensible real-world scenario with named characters.
• DQ-03: Appropriate Scale (4/4) — 10 nodes and 12 edges provide good density without overcrowding. Weights 1–3 are sensible for interaction strength.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data → plot → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic: hardcoded nodes, edges, and positions. No random generation.
• CQ-03: Clean Imports (2/2) — Only numpy and plotly.graph_objects imported; both used.
• CQ-04: Code Elegance (2/2) — Clean arc_styles dictionary for weight mapping. Concise loop for arc drawing. Dummy traces for legend is standard Plotly pattern.
• CQ-05: Output & API (1/1) — Saves as plot.png (1600×900, scale=3 = 4800×2700) and plot.html. Current Plotly API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good use of go.Figure(), go.Scatter(), add_trace(), update_layout(), add_shape(), add_annotation(). Dummy trace legend pattern is idiomatic Plotly.
• LM-02: Distinctive Features (3/5) — Custom hovertemplate with HTML formatting, hoverlabel styling, hovermode configuration, and HTML export via write_html() leverage Plotly's interactive strengths.

Score Caps Applied

• None — no cap conditions triggered.

Strengths

• Excellent spec compliance with all required features implemented (arc height proportional to distance, weight encoding, semi-transparency)
• Cohesive blue palette with intentional 3-level weight encoding through color intensity, opacity, and line width simultaneously
• Clean, well-structured code with deterministic data and idiomatic Plotly patterns
• Good data storytelling with the "longest range" annotation and visual hierarchy through weight styling
• Realistic, neutral data context (character interactions in a narrative)

Weaknesses

• Annotation text "longest range" at 14pt is slightly undersized for the 4800×2700 canvas
• Vertical canvas utilization has room for improvement — empty space below baseline and above the tallest arcs
• Weakest arcs (weight=1) are quite faint and could benefit from slightly higher minimum opacity or width
• Could leverage additional Plotly-specific features to further differentiate from static library implementations

Issues Found

1. VQ-01 MINOR: Annotation font size (14pt) is small relative to other text elements
   • Fix: Increase annotation font size to 18-20pt for consistency
2. VQ-05 MINOR: Vertical space not optimally utilized — y-range extends to 4.5 but tallest arc peaks ~3.6, plus empty space below baseline
   • Fix: Tighten y-axis range and reduce bottom margin, or shift the baseline up slightly
3. DE-02 MINOR: Visual refinement is good but could be further polished
   • Fix: Consider adding a subtle subtitle describing the data context, or refine the baseline styling
4. LM-02 MINOR: Could use more Plotly-distinctive features
   • Fix: Consider adding Plotly-specific enhancements like animation, custom buttons, or range slider

AI Feedback for Next Attempt

Score 87 — close to approval threshold. Focus on: (1) Increase annotation font size to 18-20pt for better legibility. (2) Tighten vertical canvas utilization by adjusting y-axis range closer to actual arc heights and minimizing dead space below the baseline. (3) Increase minimum arc opacity/width slightly so the weakest connections are more easily visible. (4) Consider adding a subtle Plotly-specific feature like transition animations or a more detailed hover experience to strengthen Library Mastery. These targeted fixes should push the score above 90.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 2/3

Applied fixes based on AI review feedback.

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

---

🤖 impl-repair

[claude]

AI Review - Attempt 3/3

Image Description

The plot displays a basic arc diagram with 10 character nodes (Alice, Bob, Carol, David, Eve, Frank, Grace, Henry, Iris, Jack) arranged along a subtle gray horizontal baseline near the bottom of the canvas. Parabolic arcs connect pairs of nodes above the line, with arc height proportional to the distance between connected nodes. Three weight levels are distinguished through a graduated blue color scheme: dark navy blue with high opacity (0.90) and thick width (5.0) for Strong (3) connections, medium blue with moderate opacity (0.65) and width (3.5) for Medium (2), and light pale blue with lower opacity (0.50) and width (3.0) for Weak (1). Yellow circular node markers (size 26) with dark blue outlines sit on the baseline. An annotation arrow points to the tallest arc (Alice–Iris) labeled "longest range" in 20pt font. A legend titled "Connection Strength" in the upper right classifies the three weight levels. Interactive filter buttons (All, Strong, Medium, Weak) appear in the upper left via Plotly updatemenus. The title "arc-basic · plotly · pyplots.ai" is centered at the top with a subtitle "Character interactions in a story narrative." Clean white background with no grid lines or axis elements.

Score: 90/100

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

Visual Quality (27/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set: title=30pt, subtitle=18px, node labels=22pt, legend title=18pt, legend items=16pt, annotation=20pt, hoverlabel=16pt. All text perfectly readable at 4800×2700.
• VQ-02: No Overlap (6/6) — All text fully readable with no collisions. Node labels well-spaced. Legend positioned clear of arcs. Annotation doesn't interfere with other elements.
• VQ-03: Element Visibility (5/6) — Nodes (size 26, yellow with blue outline) are clearly visible. Strong and medium arcs are well-sized. Weakest arcs (alpha 0.50, width 3.0) are distinguishable but somewhat faint in the static image, especially long-range weak arcs.
• VQ-04: Color Accessibility (4/4) — Single-hue blue scheme with intensity/opacity variation is inherently colorblind-safe. Yellow nodes provide strong contrast against blue arcs. No red-green dependency.
• VQ-05: Layout & Canvas (3/4) — Good horizontal spread with nodes spanning the full width. Vertical space utilization is reasonable with tallest arc peaking at ~3.6 in a range of [-0.7, 4.1], but some empty space below baseline and at bottom margin.
• VQ-06: Axis Labels & Title (1/2) — Title in correct format with descriptive subtitle. Axes appropriately hidden for arc diagram. Node labels are descriptive character names. No units concept applicable to this plot type.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: custom three-level blue palette with intentional weight encoding through color intensity, opacity, and line width simultaneously. Python-themed yellow/blue node styling. Cohesive color scheme clearly above library defaults with professional polish.
• DE-02: Visual Refinement (4/6) — Good refinement: all axis elements hidden, subtle gray baseline shape, legend with semi-transparent background and subtle border, filter buttons with consistent styling, tight margins (30px). Above defaults but not fully polished to publication level.
• DE-03: Data Storytelling (4/6) — Weight encoding creates clear visual hierarchy: strong connections pop with dark navy blue while weak ones fade back. The "longest range" annotation provides a clear focal point directing viewer attention. Interactive filter buttons allow exploring connection patterns by strength level.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct arc diagram: nodes arranged along horizontal line, curved parabolic arcs above the line.
• SC-02: Required Features (4/4) — All spec features present: arc height proportional to node distance, semi-transparent arcs for overlapping connections, readable node labels along axis, color coding edges by weight, weight-based arc thickness.
• SC-03: Data Mapping (3/3) — Nodes correctly positioned with linspace(0, 10, 10). Arcs connect correct pairs. Heights scale with node distance (abs(tgt-src) * 0.45).
• SC-04: Title & Legend (3/3) — Title "arc-basic · plotly · pyplots.ai" in correct format. Legend shows "Connection Strength" with three labeled weight levels (Strong/Medium/Weak).

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all arc diagram aspects: short-range connections (Alice-Bob, Bob-Carol), long-range connections (Alice-Iris, Carol-Jack), three distinct weight levels, overlapping arcs in the middle section, varying connection densities across the node sequence.
• DQ-02: Realistic Context (5/5) — Character interactions in a story narrative — neutral, comprehensible real-world scenario with named characters. Appropriate domain for demonstrating arc diagrams.
• DQ-03: Appropriate Scale (4/4) — 10 nodes and 12 edges provide good density without overcrowding. Weights 1–3 are sensible for interaction strength. Node count within recommended 10–50 range.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean linear flow: imports → data → figure → arcs loop → legend traces → nodes → baseline → annotation → filter buttons → layout → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic: hardcoded nodes, edges, and positions. No random generation needed.
• CQ-03: Clean Imports (2/2) — Only numpy and plotly.graph_objects imported; both actively used.
• CQ-04: Code Elegance (2/2) — Clean arc_styles dictionary for weight mapping. Concise loop for arc drawing. Dummy traces for legend is standard Plotly pattern. No fake functionality or over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot.png (1600×900 × scale=3 = 4800×2700) and plot.html with CDN. Current Plotly 6.x API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Expert Plotly usage: go.Figure with sequential add_trace for custom plot building, hovertemplate with HTML formatting and <extra></extra> tag, customdata for enriched hover info, updatemenus for interactive filtering, add_shape for decorative elements, add_annotation with arrow styling, write_image + write_html dual output with config dict for modeBar customization.
• LM-02: Distinctive Features (4/5) — Leverages several Plotly-distinctive features: updatemenus filter buttons for interactive weight filtering (couldn't replicate in static libraries), custom hovertemplate with HTML formatting, hoverlabel styling, write_html with CDN and modeBar config, toImageButtonOptions for high-res export.

Score Caps Applied

• None — no cap conditions triggered.

Strengths

• Perfect spec compliance with all required features: proportional arc heights, semi-transparency, weight-based color coding and thickness
• Expert Plotly usage with interactive filter buttons (updatemenus), rich hovertemplates with customdata, and dual PNG/HTML output
• Cohesive three-level blue palette encoding weight through color intensity, opacity, and line width simultaneously
• Strong data storytelling with "longest range" annotation as focal point and clear visual hierarchy through weight styling
• Clean, deterministic code following KISS principles with idiomatic Plotly patterns throughout

Weaknesses

• Weakest arcs (weight=1, alpha 0.50) are somewhat faint in the static PNG output
• Some vertical canvas space wasted below the baseline area
• VQ-06 limited by plot type — arc diagrams don't have traditional axis labels with units

Issues Found

1. VQ-03 MINOR: Weakest arcs (weight=1) at alpha 0.50 and width 3.0 are distinguishable but faint in the static image
   • Fix: Consider increasing minimum opacity to 0.55-0.60 for better static visibility while maintaining weight differentiation
2. VQ-05 MINOR: Some vertical dead space below baseline and at canvas edges
   • Fix: Could tighten y-axis range slightly or increase bottom margin utilization

AI Feedback for Next Attempt

Score 90 — meets approval threshold. The implementation demonstrates expert Plotly usage with interactive filter buttons, rich hovertemplates, and cohesive visual design. The three-level weight encoding through multiple visual channels is effective. Minor remaining issues are the faint weakest arcs in static output and slight vertical space inefficiency, but these don't significantly impact the overall quality.

Verdict: APPROVED