feat(deploy): add LLM agentic release notes skill suite for Data Commons Platform - #200
Draft
clincoln8 wants to merge 70 commits into
Draft
feat(deploy): add LLM agentic release notes skill suite for Data Commons Platform#200clincoln8 wants to merge 70 commits into
clincoln8 wants to merge 70 commits into
Conversation
- Add ComponentConfig and SourceRule multi-repository mapping rules in config.py - Add PullRequest, ComponentVersionInfo, and ReleaseInfoManifest models in models.py - Add PRExtractor with gcloud container image tag lookup and single-call gh pr list date search in pr_extractor.py - Add unit and integration tests in deploy/generate_release_notes/tests/ - Add generate-release-notes dependency group to pyproject.toml
…or to exclude post-release PRs
…passing missing image errors
…i pipeline (Flash + Pro) - Add Two-Stage Gemini LLM Pipeline in feature_extractor.py (Stage 1 Flash noise filter + Stage 2 Pro synthesis and SOP classification) - Add unit tests with mocked Gemini Client in test_feature_extractor.py
…ed PR IDs, SOPCategory enum, merged_at timestamps)
… FeatureUpdate model and Stage 2 Gemini prompt
…er using Gemini Pro - Add ReleaseNotesWriter in release_notes_writer.py with agentic prompt following streamlined DCP template - Add unit and integration test suite in test_release_notes_writer.py
…eration tool - Connect Step 1 (PRExtractor), Step 2 (FeatureExtractor), and Step 3 (ReleaseNotesWriter) into click CLI - Add test_main.py unit test suite
…ase_notes execution
…-2.5-pro for API compatibility
…nd synthesis model to gemini-2.5-pro
…2 synthesis and Step 3 writing
…file path rules into Stage 2 prompt
…etails across Feature Extractor and Release Notes Writer
…ipeline with direct bot/noise filtering instructions
…tform (focus on Ingestion Inputs & APIs, de-emphasize Spanner DB layer, drop internal testing)
…ng so t_max extends to current time for all repos
…de-emphasize Spanner DB layer in Release Notes Writer
…move backticks around PR links
…Enabled, focusing on explicit user actions and input types
… schema to use actionable use cases
…to feature_extractor.py
… vs DON'T table to release_notes_writer.py
…budgets to release notes prompts
…X ESPv2 mixer context
…gressions helper in FeatureExtractor
…rom Bug Fixes payload in ReleaseNotesWriter
…in --manifest-out JSON
…tski Agentic Skill Suite
…o Jetski mentions
…t for PR extraction skills
… generator into pure Agentic Skill Suite
…evance analysis in extraction skills
… PRs audit section to prs_*.txt
…at (Change Summary + DCP Impact), and add IMAGE_DELTAS.txt pipeline stage
…tinct component sections in Release Delta Synthesis skill
…g resolution fallback, 6 dedicated subagents, and SOP mapping matrix
…ns for all ignored PRs, and simplify section mapping principles in dcp-context
…ASE_NOTES_v1.1.1.md
…elease notes skills and README
…dynamically with release size
… output directory
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces an agentic, skill-driven tool suite for generating partner-facing release notes for the Data Commons Platform (DCP), adding orchestrator and subagent skills alongside configuration and dependency updates in pyproject.toml and uv.lock. The review feedback highlights several necessary improvements, including resolving inconsistencies in the README regarding the number of skills and executive summary rules, replacing LaTeX arrows with standard Unicode arrows for proper markdown rendering, formatting the gcloud timestamp output to UTC to avoid timezone mismatches, and removing a contradiction in the release-writer skill instructions where a banned word was used.
|
|
||
| ## Agentic Skill Suite Architecture | ||
|
|
||
| The release notes generation pipeline is structured into 4 modular `SKILL.md` instruction sets. Point your LLM agent at these skills to execute the generation process: |
Contributor
There was a problem hiding this comment.
The text states that the pipeline is structured into "4 modular SKILL.md instruction sets", but the directory tree directly below lists 5 SKILL.md files (the master orchestrator plus 4 sub-skills). This should be updated to "5 modular SKILL.md instruction sets" or clarified as "1 master orchestrator and 4 subagent skills" to avoid confusion.
Suggested change
| The release notes generation pipeline is structured into 4 modular `SKILL.md` instruction sets. Point your LLM agent at these skills to execute the generation process: | |
| The release notes generation pipeline is structured into 5 modular SKILL.md instruction sets. Point your LLM agent at these skills to execute the generation process: |
|
|
||
| ### 4. Release Writer Skill (`skills/release-writer/SKILL.md`) | ||
| Defines the non-verbose, partner-facing GFM format: | ||
| - **Executive Summary**: 1 single sentence (max 25 words). |
Contributor
There was a problem hiding this comment.
There is a discrepancy between the executive summary rule defined here and the one in skills/release-writer/SKILL.md. Here, it states that the executive summary is strictly "1 single sentence (max 25 words)". However, release-writer/SKILL.md defines a dynamic executive summary that scales up to "2-3 sentences" for large/feature-rich releases. Please update this description to reflect the dynamic scaling rules.
Suggested change
| - **Executive Summary**: 1 single sentence (max 25 words). | |
| - Executive Summary: Dynamic length scaling with release scope (2-3 sentences for major releases, 1 single sentence of max 25 words for patch releases). |
Comment on lines
+93
to
+99
| | `datacommonsorg/website` | All PRs (excluding `cdc_data/`) | Core Services (`services`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-services` | | ||
| | `datacommonsorg/mixer` | All PRs (`internal/server/`, `proto/`, `deploy/`) | Core Services (`services`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-services` | | ||
| | `datacommonsorg/agent-toolkit` | All PRs (`src/datacommons_mcp/`) | Core Services (`services`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-services` | | ||
| | `datacommonsorg/import` | `simple/` | Data Preprocessor (`preprocessing`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-data` | | ||
| | `datacommonsorg/import` | `pipeline/ingestion/` | Dataflow Worker (`dataflow_worker`) $\rightarrow$ Dataflow Templates | | ||
| | `datacommonsorg/import` | `pipeline/workflow/ingestion-helper/` | Ingestion Helper (`ingestion_helper`) $\rightarrow$ `datacommons-ingestion-helper` | | ||
| | `datacommonsorg/import` | `pipeline/workflow/aggregation-helper/` | Postprocessing Helper (`postprocessing`) $\rightarrow$ `datacommons-aggregation-helper` | |
Contributor
There was a problem hiding this comment.
The LaTeX math symbol $\rightarrow$ is used in the markdown table. In standard GitHub Flavored Markdown (GFM), this may not render correctly outside of a math block. It is cleaner and more portable to use a standard Unicode arrow (→) or a text arrow (->).
Suggested change
| | `datacommonsorg/website` | All PRs (excluding `cdc_data/`) | Core Services (`services`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-services` | | |
| | `datacommonsorg/mixer` | All PRs (`internal/server/`, `proto/`, `deploy/`) | Core Services (`services`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-services` | | |
| | `datacommonsorg/agent-toolkit` | All PRs (`src/datacommons_mcp/`) | Core Services (`services`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-services` | | |
| | `datacommonsorg/import` | `simple/` | Data Preprocessor (`preprocessing`) $\rightarrow$ `gcr.io/datcom-ci/datacommons-data` | | |
| | `datacommonsorg/import` | `pipeline/ingestion/` | Dataflow Worker (`dataflow_worker`) $\rightarrow$ Dataflow Templates | | |
| | `datacommonsorg/import` | `pipeline/workflow/ingestion-helper/` | Ingestion Helper (`ingestion_helper`) $\rightarrow$ `datacommons-ingestion-helper` | | |
| | `datacommonsorg/import` | `pipeline/workflow/aggregation-helper/` | Postprocessing Helper (`postprocessing`) $\rightarrow$ `datacommons-aggregation-helper` | | |
| | datacommonsorg/website | All PRs (excluding cdc_data/) | Core Services (services) → gcr.io/datcom-ci/datacommons-services | | |
| | datacommonsorg/mixer | All PRs (internal/server/, proto/, deploy/) | Core Services (services) → gcr.io/datcom-ci/datacommons-services | | |
| | datacommonsorg/agent-toolkit | All PRs (src/datacommons_mcp/) | Core Services (services) → gcr.io/datcom-ci/datacommons-services | | |
| | datacommonsorg/import | simple/ | Data Preprocessor (preprocessing) → gcr.io/datcom-ci/datacommons-data | | |
| | datacommonsorg/import | pipeline/ingestion/ | Dataflow Worker (dataflow_worker) → Dataflow Templates | | |
| | datacommonsorg/import | pipeline/workflow/ingestion-helper/ | Ingestion Helper (ingestion_helper) → datacommons-ingestion-helper | | |
| | datacommonsorg/import | pipeline/workflow/aggregation-helper/ | Postprocessing Helper (postprocessing) → datacommons-aggregation-helper | |
Comment on lines
+46
to
+50
| - **Subagent 1 (`services-extractor`)**: Extract PRs for `gcr.io/datcom-ci/datacommons-services` from `website`, `mixer`, `agent-toolkit` $\rightarrow$ write `output/prs_services.txt`. | ||
| - **Subagent 2 (`preprocessing-extractor`)**: Extract PRs for `gcr.io/datcom-ci/datacommons-data` (preprocessor) from `import` repo $\rightarrow$ write `output/prs_preprocessing.txt`. | ||
| - **Subagent 3 (`dataflow-worker-extractor`)**: Extract PRs for Dataflow Ingestion Worker from `import` repo $\rightarrow$ write `output/prs_dataflow_worker.txt`. | ||
| - **Subagent 4 (`ingestion-helper-extractor`)**: Extract PRs for Ingestion Helper Service from `import` repo $\rightarrow$ write `output/prs_ingestion_helper.txt`. | ||
| - **Subagent 5 (`postprocessing-extractor`)**: Extract PRs for Postprocessing Helper Service from `import` repo $\rightarrow$ write `output/prs_postprocessing.txt`. |
Contributor
There was a problem hiding this comment.
The LaTeX math symbol $\rightarrow$ is used here. Please replace it with a standard Unicode arrow (→) or text arrow (->) to ensure proper rendering in GFM.
Suggested change
| - **Subagent 1 (`services-extractor`)**: Extract PRs for `gcr.io/datcom-ci/datacommons-services` from `website`, `mixer`, `agent-toolkit` $\rightarrow$ write `output/prs_services.txt`. | |
| - **Subagent 2 (`preprocessing-extractor`)**: Extract PRs for `gcr.io/datcom-ci/datacommons-data` (preprocessor) from `import` repo $\rightarrow$ write `output/prs_preprocessing.txt`. | |
| - **Subagent 3 (`dataflow-worker-extractor`)**: Extract PRs for Dataflow Ingestion Worker from `import` repo $\rightarrow$ write `output/prs_dataflow_worker.txt`. | |
| - **Subagent 4 (`ingestion-helper-extractor`)**: Extract PRs for Ingestion Helper Service from `import` repo $\rightarrow$ write `output/prs_ingestion_helper.txt`. | |
| - **Subagent 5 (`postprocessing-extractor`)**: Extract PRs for Postprocessing Helper Service from `import` repo $\rightarrow$ write `output/prs_postprocessing.txt`. | |
| - Subagent 1 (services-extractor): Extract PRs for gcr.io/datcom-ci/datacommons-services from website, mixer, agent-toolkit → write output/prs_services.txt. | |
| - Subagent 2 (preprocessing-extractor): Extract PRs for gcr.io/datcom-ci/datacommons-data (preprocessor) from import repo → write output/prs_preprocessing.txt. | |
| - Subagent 3 (dataflow-worker-extractor): Extract PRs for Dataflow Ingestion Worker from import repo → write output/prs_dataflow_worker.txt. | |
| - Subagent 4 (ingestion-helper-extractor): Extract PRs for Ingestion Helper Service from import repo → write output/prs_ingestion_helper.txt. | |
| - Subagent 5 (postprocessing-extractor): Extract PRs for Postprocessing Helper Service from import repo → write output/prs_postprocessing.txt. |
| 1. **Artifact Registry Tag Resolution**: | ||
| Resolve the creation timestamp for `<prev_version>` and `<new_version>` for your assigned `image_uri`: | ||
| ```bash | ||
| gcloud container images list-tags <image_uri> --filter="tags:<version>" --format="value(timestamp.datetime)" |
Contributor
There was a problem hiding this comment.
The gcloud container images list-tags command outputs the timestamp in the local timezone of the environment by default. Since GitHub's search API expects UTC timestamps, using local time can lead to timezone mismatches and missed or extra PRs in the query range. It is highly recommended to explicitly format the timestamp in UTC.
Suggested change
| gcloud container images list-tags <image_uri> --filter="tags:<version>" --format="value(timestamp.datetime)" | |
| gcloud container images list-tags <image_uri> --filter="tags:<version>" --format="value(timestamp.format('%Y-%m-%dT%H:%M:%SZ', tz=UTC))" |
| - **BANNED AI FLUFF WORDS (STRICT)**: DO NOT use AI cliché words: `seamlessly`, `empower`, `leveraging`, `robust`, `overhaul`, `delivers a major`, `comprehensive`, `fosters`, `game-changing`, `cutting-edge`, `paradigm`. | ||
| - **DYNAMIC EXECUTIVE SUMMARY**: | ||
| - The summary length and detail level MUST scale dynamically with the scope of the release. | ||
| - **Large / Feature-Rich Releases**: Provide a comprehensive 2–3 sentence overview highlighting all major capabilities, API protocols, preprocessor boosts, and critical fixes without an artificial word count cap. |
Contributor
There was a problem hiding this comment.
There is a direct contradiction in the instructions. Line 15 explicitly bans the word comprehensive as an "AI fluff word". However, line 18 instructs the LLM to "Provide a comprehensive 2-3 sentence overview". This contradiction will likely confuse the LLM agent. Please replace comprehensive in line 18 with a non-banned alternative like detailed or thorough.
Suggested change
| - **Large / Feature-Rich Releases**: Provide a comprehensive 2–3 sentence overview highlighting all major capabilities, API protocols, preprocessor boosts, and critical fixes without an artificial word count cap. | |
| - Large / Feature-Rich Releases: Provide a detailed 2-3 sentence overview highlighting all major capabilities, API protocols, preprocessor boosts, and critical fixes without an artificial word count cap. |
…nd update skill descriptions
…h for component and repository mapping
…Start at top and architecture at end
clincoln8
marked this pull request as draft
July 30, 2026 23:35
…dcp-context SKILL.md
…ter SKILL.md and clean dcp-context SKILL.md
…touchpoints vs internal mechanics, and single source of truth mapping
…ards with Prime Directives, CoT phases, and zero fluff guidelines
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
1 participant
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.
Description
This PR introduces an end-to-end, LLM-native Skill Suite for generating publication-ready, partner-facing release notes for the Data Commons Platform (DCP) stack.
Instead of relying on rigid Python CLI scripts or manual PR curation, this tool provides a 4-step agentic workflow using LLM subagents and structured verification checkpoints:
Architecture & Skill Suite Breakdown:
deploy/generate_release_notes/SKILL.md): Entrypoint skill that orchestrates the release notes pipeline across 6 repositories and 6 container images.deploy/generate_release_notes/skills/pr-extraction/SKILL.md): Instructs subagents to resolve image tags across Artifact Registry (with user prompt fallback on missing tags), query merged PRs viagh pr list, extract change summaries & DCP impact, filter out intermediate release-window regressions and Base DC flag flips, and output human-verifiable text files (prs_*.txt).deploy/generate_release_notes/skills/release-delta-synthesis/SKILL.md): Analyzes allprs_*.txtfiles to distinguish true platform bug fixes present in prior releases vs. intra-release intermediate fixes, synthesizes salient features per container image (separating Mixer, MCP Agent Toolkit, and Website UI into distinct sections), and outputsIMAGE_DELTAS_<version>.txt.deploy/generate_release_notes/skills/dcp-context/SKILL.md): Architectural reference mapping DCP components, persona principles (external contracts, zero internal DB table exposure), and section mapping rules.deploy/generate_release_notes/skills/release-writer/SKILL.md): Authors publication-ready release notes with dynamic Executive Summary scaling (2-3 sentences for major releases, 1 sentence for patch releases), two-tier Key Feature Updates (What's New + Specific Capabilities), GFM links ([repo#PR](URL)), and 4 grouped Bug Fix categories.deploy/generate_release_notes/README.md): Comprehensive instructions for developers on how to prompt their LLM agent to execute the pipeline.Technical Highlights
prs_*.txtincludes a 1-sentenceReason:explaining why it was excluded.KeyValueStore,IngestionHistory) for partner-facing clarity.Verification
v1.1.0->v1.1.1(RELEASE_NOTES_v1.1.1.mdandIMAGE_DELTAS_v1.1.1.txt).[repo#PR](URL)without backtick formatting errors.