docs: update plot specifications and examples across multiple libraries

- Remove return type sections from various plot specifications
- Enhance descriptions and examples for clarity
- Standardize data requirements and use cases
- Improve overall formatting and consistency in documentation

Author: MarkusNeusinger

.github/workflows/bot-validate-request.yml

@@ -49,11 +49,18 @@ jobs:
             exit 0
           fi
 
-          # Check 2: Must not already have spec ID in title (indicated by [...])
-          if [[ "$ISSUE_TITLE" == *"["* ]]; then
-            echo "::notice::Skipping: Issue title already contains spec ID"
-            echo "should_run=false" >> $GITHUB_OUTPUT
-            exit 0
+          # Check 2: Must not already have spec ID in title
+          # Spec ID format: [lowercase-with-hyphens] at the beginning, NOT [update...]
+          # Valid spec-id: [scatter-basic], [line-timeseries-multi]
+          # NOT spec-id: [update], [update:matplotlib], [Update:...]
+          if [[ "$ISSUE_TITLE" =~ ^\[[a-z0-9-]+\] ]]; then
+            FIRST_BRACKET=$(echo "$ISSUE_TITLE" | grep -oP '^\[\K[a-z0-9-]+(?=\])' || echo "")
+            # Skip only if it's a valid spec-id (not an update marker)
+            if [[ -n "$FIRST_BRACKET" && ! "$FIRST_BRACKET" =~ ^update ]]; then
+              echo "::notice::Skipping: Issue title already has spec ID: $FIRST_BRACKET"
+              echo "should_run=false" >> $GITHUB_OUTPUT
+              exit 0
+            fi
           fi
 
           # Check 3: For labeled events, only trigger when plot-request label is added

.github/workflows/gen-create-spec.yml

@@ -1,5 +1,5 @@
-name: "Gen: Create Spec"
-run-name: "Create Spec: ${{ github.event.issue.title }}"
+name: "Gen: Create Spec / Handle Update"
+run-name: "${{ contains(github.event.issue.labels.*.name, 'update') && 'Update' || 'Create Spec' }}: ${{ github.event.issue.title }}"
 
 on:
   issues:
@@ -19,6 +19,8 @@ jobs:
       spec_id: ${{ steps.extract_spec.outputs.spec_id }}
       feature_branch: ${{ steps.create_branch.outputs.feature_branch }}
       spec_exists: ${{ steps.check_spec.outputs.exists }}
+      is_update: ${{ steps.check.outputs.is_update }}
+      target_library: ${{ steps.check.outputs.target_library }}
 
     permissions:
       contents: write
@@ -28,10 +30,13 @@ jobs:
     steps:
       - name: Check conditions
         id: check
+        env:
+          ISSUE_TITLE: ${{ github.event.issue.title }}
         run: |
           echo "=== Debug Info ==="
           echo "Label added: ${{ github.event.label.name }}"
           echo "Issue labels: ${{ join(github.event.issue.labels.*.name, ', ') }}"
+          echo "Issue title: $ISSUE_TITLE"
           echo "=================="
 
           # Check 1: Must be "approved" label being added
@@ -49,15 +54,27 @@ jobs:
             exit 0
           fi
 
-          # Check 3: Must NOT have "update" label (updates use existing spec)
+          # Check 3: Detect if this is an update request
           HAS_UPDATE="${{ contains(github.event.issue.labels.*.name, 'update') }}"
           if [[ "$HAS_UPDATE" == "true" ]]; then
-            echo "::notice::Skipping: This is an update request, not a new spec"
-            echo "should_run=false" >> $GITHUB_OUTPUT
-            exit 0
+            echo "is_update=true" >> $GITHUB_OUTPUT
+            echo "::notice::This is an update request"
+
+            # Extract target library from title [update:library] or empty for all
+            if [[ "$ISSUE_TITLE" =~ \[update:([a-z]+)\] ]]; then
+              TARGET_LIB="${BASH_REMATCH[1]}"
+              echo "target_library=$TARGET_LIB" >> $GITHUB_OUTPUT
+              echo "::notice::Target library: $TARGET_LIB"
+            else
+              echo "target_library=" >> $GITHUB_OUTPUT
+              echo "::notice::Target: all libraries"
+            fi
+          else
+            echo "is_update=false" >> $GITHUB_OUTPUT
+            echo "target_library=" >> $GITHUB_OUTPUT
           fi
 
-          echo "::notice::All conditions met - proceeding with spec creation"
+          echo "::notice::All conditions met - proceeding"
           echo "should_run=true" >> $GITHUB_OUTPUT
 
       - name: Checkout repository
@@ -104,8 +121,13 @@ jobs:
           fi
 
           # Fallback: extract from title if in brackets [spec-id]
+          # Must be at the beginning and NOT an update marker
           if [ -z "$SPEC_ID" ]; then
-            SPEC_ID=$(echo "$ISSUE_TITLE" | grep -oP '\[\K[a-z0-9-]+(?=\])' | tail -1 || echo "")
+            FIRST_BRACKET=$(echo "$ISSUE_TITLE" | grep -oP '^\[\K[a-z0-9-]+(?=\])' || echo "")
+            # Only use if it's not an update marker
+            if [[ -n "$FIRST_BRACKET" && ! "$FIRST_BRACKET" =~ ^update ]]; then
+              SPEC_ID="$FIRST_BRACKET"
+            fi
           fi
 
           if [ -z "$SPEC_ID" ]; then
@@ -121,13 +143,19 @@ jobs:
         id: check_spec
         env:
           SPEC_ID: ${{ steps.extract_spec.outputs.spec_id }}
+          IS_UPDATE: ${{ steps.check.outputs.is_update }}
         run: |
           if [ -f "specs/$SPEC_ID.md" ]; then
             echo "exists=true" >> $GITHUB_OUTPUT
-            echo "::notice::Spec file already exists: specs/$SPEC_ID.md"
+            echo "::notice::Spec file exists: specs/$SPEC_ID.md"
           else
             echo "exists=false" >> $GITHUB_OUTPUT
-            echo "::notice::Spec file does not exist yet"
+            # For updates, spec MUST exist
+            if [[ "$IS_UPDATE" == "true" ]]; then
+              echo "::error::Update request but spec file does not exist: specs/$SPEC_ID.md"
+              exit 1
+            fi
+            echo "::notice::Spec file does not exist yet (will be created)"
           fi
 
       - name: Check if feature branch exists
@@ -151,12 +179,21 @@ jobs:
         env:
           SPEC_ID: ${{ steps.extract_spec.outputs.spec_id }}
           BRANCH_EXISTS: ${{ steps.check_branch.outputs.exists }}
+          IS_UPDATE: ${{ steps.check.outputs.is_update }}
         run: |
           BRANCH="plot/$SPEC_ID"
 
           echo "feature_branch=$BRANCH" >> $GITHUB_OUTPUT
 
-          if [[ "$BRANCH_EXISTS" == "true" ]]; then
+          # For updates: always create fresh branch from main (old branch was deleted after merge)
+          if [[ "$IS_UPDATE" == "true" ]]; then
+            if [[ "$BRANCH_EXISTS" == "true" ]]; then
+              echo "::notice::Deleting existing branch for fresh update: $BRANCH"
+              git push origin --delete "$BRANCH" 2>/dev/null || true
+            fi
+            git checkout -b "$BRANCH" origin/main
+            echo "::notice::Created fresh branch from main for update: $BRANCH"
+          elif [[ "$BRANCH_EXISTS" == "true" ]]; then
             git fetch origin "$BRANCH"
             git checkout "$BRANCH"
             echo "::notice::Checked out existing branch: $BRANCH"
@@ -193,17 +230,18 @@ jobs:
 
             4. Create the spec file at: `specs/${{ steps.extract_spec.outputs.spec_id }}.md`
                - Follow the template structure exactly
-               - Fill in all sections based on the issue description
-               - Be specific and detailed in quality criteria
-               - Include realistic use cases
+               - Keep it simple and focused (description, data, tags, use cases)
+               - Include example data if helpful (inline or dataset reference)
+               - Include realistic use cases with domain context
 
             5. Do NOT commit or push - just create the file
 
             ### Quality Requirements
-            - All required sections must be present (Title, Description, Data Requirements)
-            - Quality criteria should be specific and measurable
+            - All required sections: Title, Description, Data, Tags, Use Cases
+            - Description should clearly explain what the plot visualizes
+            - Data section should list required columns with types
             - Use cases should be realistic and varied
-            - The spec should be complete enough for AI to generate implementations
+            - Keep it concise - AI uses central prompts for implementation details
 
       - name: Commit and push spec file
         if: steps.check.outputs.should_run == 'true'
@@ -212,13 +250,20 @@ jobs:
           SPEC_ID: ${{ steps.extract_spec.outputs.spec_id }}
           BRANCH: ${{ steps.create_branch.outputs.feature_branch }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}
+          IS_UPDATE: ${{ steps.check.outputs.is_update }}
         run: |
-
           # Configure git
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-          # Check if spec file was created
+          # For updates, spec already exists - just push the branch
+          if [[ "$IS_UPDATE" == "true" ]]; then
+            git push -u origin "$BRANCH"
+            echo "::notice::Pushed update branch: $BRANCH"
+            exit 0
+          fi
+
+          # For new specs: check if spec file was created
           if [ -f "specs/$SPEC_ID.md" ]; then
             git add "specs/$SPEC_ID.md"
 
@@ -237,15 +282,36 @@ jobs:
             exit 1
           fi
 
-      - name: Post comment with spec creation summary
+      - name: Post comment with summary
         if: steps.check.outputs.should_run == 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SPEC_ID: ${{ steps.extract_spec.outputs.spec_id }}
           BRANCH: ${{ steps.create_branch.outputs.feature_branch }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}
+          IS_UPDATE: ${{ steps.check.outputs.is_update }}
+          TARGET_LIBRARY: ${{ steps.check.outputs.target_library }}
         run: |
-          gh issue comment "$ISSUE_NUMBER" --body "## Spec Created
+          if [[ "$IS_UPDATE" == "true" ]]; then
+            if [[ -n "$TARGET_LIBRARY" ]]; then
+              SCOPE="**$TARGET_LIBRARY** only"
+            else
+              SCOPE="all 9 libraries"
+            fi
+
+            gh issue comment "$ISSUE_NUMBER" --body "## 🔄 Update Request
+
+          **Spec ID:** \`$SPEC_ID\`
+          **Branch:** \`$BRANCH\`
+          **Scope:** $SCOPE
+
+          ### Next Steps
+          Triggering code regeneration...
+
+          ---
+          :robot: *[gen-create-spec workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
+          else
+            gh issue comment "$ISSUE_NUMBER" --body "## ✅ Spec Created
 
           **Spec ID:** \`$SPEC_ID\`
           **Branch:** \`$BRANCH\`
@@ -256,6 +322,7 @@ jobs:
 
           ---
           :robot: *[gen-create-spec workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
+          fi
 
   # ============================================================================
   # Step 2: Trigger library generation
@@ -274,11 +341,19 @@ jobs:
           SPEC_ID: ${{ needs.create-spec.outputs.spec_id }}
           FEATURE_BRANCH: ${{ needs.create-spec.outputs.feature_branch }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}
+          TARGET_LIBRARY: ${{ needs.create-spec.outputs.target_library }}
         run: |
-          gh workflow run gen-new-plot.yml \
-            --repo ${{ github.repository }} \
-            -f spec_id="$SPEC_ID" \
-            -f feature_branch="$FEATURE_BRANCH" \
-            -f issue_number="$ISSUE_NUMBER"
+          # Build command with optional target_library
+          CMD="gh workflow run gen-new-plot.yml --repo ${{ github.repository }}"
+          CMD="$CMD -f spec_id=\"$SPEC_ID\""
+          CMD="$CMD -f feature_branch=\"$FEATURE_BRANCH\""
+          CMD="$CMD -f issue_number=\"$ISSUE_NUMBER\""
+
+          if [[ -n "$TARGET_LIBRARY" ]]; then
+            CMD="$CMD -f target_library=\"$TARGET_LIBRARY\""
+            echo "::notice::Triggering gen-new-plot.yml for $SPEC_ID (library: $TARGET_LIBRARY)"
+          else
+            echo "::notice::Triggering gen-new-plot.yml for $SPEC_ID (all libraries)"
+          fi
 
-          echo "::notice::Triggered gen-new-plot.yml for $SPEC_ID"
+          eval $CMD

.github/workflows/gen-new-plot.yml

@@ -16,6 +16,11 @@ on:
         description: "Main issue number"
         required: true
         type: string
+      target_library:
+        description: "Single library to regenerate (empty = all libraries)"
+        required: false
+        type: string
+        default: ""
 
 concurrency:
   group: spec-to-code-${{ inputs.issue_number }}
@@ -36,6 +41,7 @@ jobs:
       spec_id: ${{ inputs.spec_id }}
       feature_branch: ${{ inputs.feature_branch }}
       issue_number: ${{ inputs.issue_number }}
+      target_library: ${{ inputs.target_library }}
 
     steps:
       - name: Log inputs
@@ -44,6 +50,7 @@ jobs:
           echo "Spec ID: ${{ inputs.spec_id }}"
           echo "Feature Branch: ${{ inputs.feature_branch }}"
           echo "Issue Number: ${{ inputs.issue_number }}"
+          echo "Target Library: ${{ inputs.target_library || 'all' }}"
           echo "======================="
 
       - name: Checkout repository
@@ -97,13 +104,20 @@ jobs:
         id: create
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TARGET_LIBRARY: ${{ inputs.target_library }}
         run: |
           SPEC_ID="${{ inputs.spec_id }}"
           PARENT_NUM="${{ inputs.issue_number }}"
           FEATURE_BRANCH="${{ inputs.feature_branch }}"
           PARENT_NODE_ID=$(gh api repos/${{ github.repository }}/issues/$PARENT_NUM --jq '.node_id')
 
           for LIBRARY in ${{ env.LIBRARIES }}; do
+            # Skip if target_library is set and doesn't match
+            if [[ -n "$TARGET_LIBRARY" && "$TARGET_LIBRARY" != "$LIBRARY" ]]; then
+              echo "::notice::Skipping $LIBRARY (target: $TARGET_LIBRARY)"
+              continue
+            fi
+
             echo "Creating sub-issue for $LIBRARY..."
 
             # Check if sub-issue already exists
@@ -155,6 +169,7 @@ jobs:
   # ============================================================================
   generate-matplotlib:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'matplotlib'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -168,6 +183,7 @@ jobs:
 
   generate-seaborn:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'seaborn'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -181,6 +197,7 @@ jobs:
 
   generate-plotly:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'plotly'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -194,6 +211,7 @@ jobs:
 
   generate-bokeh:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'bokeh'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -207,6 +225,7 @@ jobs:
 
   generate-altair:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'altair'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -220,6 +239,7 @@ jobs:
 
   generate-plotnine:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'plotnine'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -233,6 +253,7 @@ jobs:
 
   generate-pygal:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'pygal'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -246,6 +267,7 @@ jobs:
 
   generate-highcharts:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'highcharts'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}
@@ -259,6 +281,7 @@ jobs:
 
   generate-letsplot:
     needs: [setup, create-sub-issues]
+    if: inputs.target_library == '' || inputs.target_library == 'letsplot'
     uses: ./.github/workflows/gen-library-impl.yml
     with:
       spec_id: ${{ inputs.spec_id }}