fix(prompts): disambiguate tag-vocab tables (Copilot review on #5856)#5859
Merged
Conversation
Three follow-ups landing the Copilot review feedback: 1. Sankey example was contradictory: said "Sankey is also a flow plot" right next to a strict rule that plot_type cannot contain `flow`. Reword as "plot_type: sankey + features: flow" so the example agrees with the policy. 2. data_type vs features overlap: temporal moved to features only (it's a presentation property, not a data shape); directional stayed in data_type only; multivariate and hierarchical stayed in data_type only. Each tag now lives in exactly one dimension. 3. features had both `multi`/`multi-series` and `flow`/ `flow-visualization` listed — pick the canonical form (the shorter one) and call out that polish will rewrite the legacy synonyms to match. Net effect: the polish prompt now has unambiguous guidance about which dimension every common tag belongs in, so it stops flip-flopping when re-running on the same spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Clarifies the spec tag vocabulary policy to remove ambiguity between plot_type, data_type, and features, reducing regenerations that “flip” tags between allowed dimensions.
Changes:
- Updated the Sankey example to align with the rule that
flowis afeaturestag, not aplot_type. - Removed duplicated/ambiguous tags across dimensions (e.g.,
temporal,multivariate,hierarchical,directional) and added guidance on what belongs indata_typevsfeatures. - Added an explicit canonical-vs-legacy synonym note for
featurestags to make rewrite behavior referenceable.
| - Multiple tags allowed when plot combines multiple types | ||
| - Example: Sankey is also a `flow` plot | ||
| - Multiple tags allowed when plot combines multiple types — but every value must come from this canonical table | ||
| - `flow`, `temporal`, `multi`, etc. are NOT plot types. They go in `features` (where they describe a property of the visualization). A Sankey diagram is `plot_type: sankey` plus `features: flow`. |
| - `multi` (not `multi-series`) for "more than one series in the same chart" | ||
| - `flow` (not `flow-visualization`) for diagrams whose primary message is movement between states | ||
| - `stepwise` (not `sequential`) for staircase-style transitions | ||
| - `color-mapped` (not `labeled`) when the distinction is colour encoding |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to PR #5856 addressing the three Copilot review comments. All three pointed to real ambiguities in the policy doc that would have re-introduced churn the original PR was trying to remove.
What changed
Sankey example was self-contradictory. The doc said "Sankey is also a
flowplot" right next to the new rule thatplot_typecannot containflow. Reworded to "A Sankey diagram isplot_type: sankeyplusfeatures: flow" so the example matches the policy.Same tag listed in multiple dimensions.
temporalwas in bothdata_typeandfeatures;multivariate/hierarchical/directionalwere duplicated asfeatureseven though they describe input shape. Resolved each to a single home:temporal→featuresonly (presentation), the three structure tags →data_typeonly (shape).Both canonical and legacy synonyms in the same table.
featureslistedmultiandmulti-series, plusflowandflow-visualization. Kept just the canonical form in the table (multi,flow,stepwise,color-mapped) and added an explicit "polish rewrites legacy synonyms" callout so the rewrite rules are visible at the source.Why it matters
Without these fixes the polish prompt could legitimately have flipped the same tag back and forth between dimensions on consecutive regen ticks (since both placements would look "valid" by the table). The disambiguation ensures every common tag has exactly one home, and the canonical-vs-synonym list makes the rewrite rules referenceable.
Test plan
prompts/spec-tags-generator.mddaily-regentick uses the disambiguated tables — should produce zero churn on already-canonicalized specs🤖 Generated with Claude Code