Add govkit-synthetic-data skill (Faker-based scenario test data generator)#3
Merged
Merged
Conversation
…ator) Generate synthetic test data for a GovKit feature package from its Gherkin scenarios: a seeded, standalone Python Faker generator script plus committed data files and a MANIFEST coverage map tracing every dataset back to the scenario it exercises. - Tool-agnostic: the generator/project boundary is data files (CSV/JSONL/SQL), so the target stack can be anything; only the generator is Python. - Deterministic and regenerable (single seed, stdlib + faker only), with a synthetic marker on every record and guardrails against inventing business rules or touching real production data. - Includes SKILL.md, references/faker-patterns.md, and a standalone scripts/generator_template.py. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
PR Summary by QodoAdd GovKit synthetic-data skill with Faker-based deterministic generator template
AI Description
Diagram
High-Level Assessment
Files changed (3)
|
Code Review by Qodo
1. Missing run version metadata
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+1
to
+14
| #!/usr/bin/env python3 | ||
| """Synthetic test data generator — <WORK-ITEM-ID>. | ||
|
|
||
| Generated for the GovKit feature package at /features/<WORK-ITEM-ID>/. | ||
| ALL OUTPUT IS SYNTHETIC (Python Faker). No real records were used. | ||
|
|
||
| Deterministic: the same --seed always produces byte-identical output. | ||
| Dependencies: python 3.9+ and `pip install faker` — nothing else. | ||
|
|
||
| Usage: | ||
| python generate_test_data.py # default seed, all datasets | ||
| python generate_test_data.py --seed 42 | ||
| python generate_test_data.py --outdir data/ | ||
| """ |
There was a problem hiding this comment.
1. Missing run version metadata 🐞 Bug ⚙ Maintainability
generator_template.py claims to be self-describing, but its header/docstring does not include the seed or Faker version (as required by the skill instructions), reducing reproducibility/auditability when outputs differ across environments. This makes it harder to diagnose non-byte-identical output caused by dependency/runtime drift.
Agent Prompt
### Issue description
The skill instructions say the generator template is "Self-describing" and that the header comment names the work item, seed, and Faker version, but the current template header/docstring does not include seed/version metadata.
### Issue Context
This skill’s core promise is deterministic, byte-identical regeneration. When output differs due to environment drift (Faker/Python version changes), missing metadata makes it difficult to root-cause.
### Fix Focus Areas
- plugins/govkit/skills/govkit-synthetic-data/scripts/generator_template.py[1-15]
- plugins/govkit/skills/govkit-synthetic-data/scripts/generator_template.py[143-166]
### Implementation notes
- Import and surface Faker + Python version (e.g., `import faker` / `sys`).
- Include seed + versions in the startup banner / final print, and/or write a small manifest file next to outputs.
- Update the module docstring to include the seed and to mention where version metadata is emitted.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+55
to
+62
| def write_csv(records: list, path: Path) -> None: | ||
| path.parent.mkdir(parents=True, exist_ok=True) | ||
| if not records: | ||
| # An intentionally empty dataset still gets written so loaders can | ||
| # detect the zero-cardinality case. Supply columns explicitly if a | ||
| # header row is required. | ||
| path.write_text("", encoding="utf-8") | ||
| return |
There was a problem hiding this comment.
2. Zero-row csv lacks header 🐞 Bug ≡ Correctness
write_csv() writes an empty file for empty datasets, but its comment says headers may be required and there is no way to supply fieldnames without records. This can break CSV loaders/tests that require a header row even when the dataset has zero records.
Agent Prompt
### Issue description
`write_csv()` cannot emit a header row for empty datasets, yet the template explicitly supports zero-cardinality datasets and the function comment notes headers may be required.
### Issue Context
Many CSV consumers are schema-driven and expect headers even when there are 0 rows. The template currently produces an empty file which can be ambiguous or fail parsing.
### Fix Focus Areas
- plugins/govkit/skills/govkit-synthetic-data/scripts/generator_template.py[55-69]
### Implementation notes
- Add an optional `fieldnames: list[str] | None = None` parameter.
- If `records` is empty and `fieldnames` is provided, write a header-only CSV.
- Consider adding a small example usage in `main()` or comments showing how to emit a header-only zero dataset.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+162
to
+163
| if args.volume: | ||
| write_csv(happy_records(fake, args.volume), out / "example_volume.csv") |
There was a problem hiding this comment.
3. Volume dataset built in-memory 🐞 Bug ➹ Performance
The volume path builds args.volume records into a Python list before writing, which scales peak memory linearly with the requested dataset size. For NFR-driven volumes, this can cause slowdowns or OOM failures in CI.
Agent Prompt
### Issue description
The template materializes the entire volume dataset in memory via `happy_records(..., args.volume)` before writing CSV.
### Issue Context
This skill explicitly supports NFR-driven scale datasets; those counts can be large. Holding all records in RAM is unnecessary for CSV/JSONL writing and can fail in CI.
### Fix Focus Areas
- plugins/govkit/skills/govkit-synthetic-data/scripts/generator_template.py[115-117]
- plugins/govkit/skills/govkit-synthetic-data/scripts/generator_template.py[162-164]
### Implementation notes
- Change `happy_records` to yield records (iterator/generator) or add `iter_happy_records`.
- Update `write_csv` (and optionally `write_jsonl`) to accept an iterable and write incrementally.
- For CSV streaming, write header from a single "first" record, then write the first + subsequent records without building a full list.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
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.
Summary
Adds a new GovKit skill, govkit-synthetic-data, that turns an approved feature package into the synthetic test data its scenarios need: a seeded, standalone Python Faker generator plus committed data files and a coverage manifest.
The script is the deliverable, not just the data — a seeded generator regenerates byte-identical output in CI, survives schema tweaks with a one-line edit, and shows reviewers exactly how every value was produced. Faker output is inherently synthetic, which is what makes it safe in a government context.
What's included
plugins/govkit/skills/govkit-synthetic-data/SKILL.md— purpose, tool-agnostic design, inputs, the 5-step process (parse package → build data profile → plan coverage → write generator → run/verify/manifest), output layout, and guardrails.plugins/govkit/skills/govkit-synthetic-data/references/faker-patterns.md— provider selection, locale, custom providers for domain formats, relational integrity, and edge-case injection.plugins/govkit/skills/govkit-synthetic-data/scripts/generator_template.py— standalone starting-point script (single seed, stdlib + faker only, CSV/JSONL/SQL writers,--help,--seed).Design notes
pip install faker).Faker.seed()+random.seed(); verified by regenerating and diffing before it's considered done.🤖 Generated with Claude Code