notque/vexjoy-agent / skills/analysis/data
data
VerifiedData analysis, reference enrichment, and data engineering: pipelines and warehouses, server database design and tuning, SQLite with Peewee.
references/enrichment-prompt.md
View on GitHub# Reference Enrichment — Headless Prompt
You are running as an autonomous hourly process to improve the toolkit's domain knowledge depth. This is ADR-173: Reference Enrichment.
## Context
- **Date:** ${ENRICH_DATE}
- **Run ID:** ${ENRICH_RUN_ID}
- **Repository:** ${ENRICH_REPO_DIR}
- **Targets:** ${ENRICH_TARGETS}
- **Max targets:** ${ENRICH_MAX_TARGETS}
- **Dry-run mode:** ${ENRICH_DRY_RUN_MODE}
These targets were identified by `scripts/audit-reference-depth.py` as having Level 0-2 reference depth (missing, thin, or incomplete domain knowledge). Your job is to enrich them to Level 3+ by generating concrete, domain-specific reference files.
## If Dry-Run Mode is "yes"
Only perform the audit analysis. For each target:
1. Run `python3 scripts/audit-reference-depth.py --agent {name} --verbose` (or `--skill {name}`)
2. Run `python3 skills/analysis/data/scripts/gap-analyzer.py --agent {name}` (or `--skill {name}`)
3. Report what WOULD be enriched: domains, gaps, recommended reference files
4. Report findings only — file creation happens in a later phase
Print a summary and exit.
## If Dry-Run Mode is "no"
### Phase 1: Setup
1. Check for existing open enrichment PRs: `gh pr list --search "enrich/refs" --state open --json number | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d))"`
2. If 5 or more enrichment PRs are already open, log "Too many open enrichment PRs (>=5), skipping to avoid accumulation" and exit
3. For each target in the targets list, check for an existing enrichment PR for that specific agent/skill:
`gh pr list --search "enrich/refs" --state open --json title --jq '[.[] | select(.title | test("{name}"))] | length'`
If any exist, skip that target — it already has pending enrichment work.
4. You are running inside a git worktree based on the latest origin/main. Verify you are NOT on the main branch of the primary checkout:
- Run `git log --oneline -1` to confirm you're at the expected HEAD
- Run `pwd` to confirm you're in the worktree path (should contain /tmp/enrichment-worktree)
5. Create a feature branch: `git checkout -b enrich/refs-${ENRICH_RUN_ID}`
### Phase 2: Enrich Each Target
For each target name in the targets list:
1. **Audit before:** Run `python3 scripts/audit-reference-depth.py --skill {name} --verbose` to record the starting level (`--agent {name}` only for a private overlay agent; repo agents are retired and their content lives in skill references)
2. **Gap analysis:** Run `python3 skills/analysis/data/scripts/gap-analyzer.py --skill {name}` to identify specific knowledge gaps (`--agent` only for an overlay agent)
3. **Read exemplars:** Read one high-quality reference file as a model (e.g., `~/.claude/skills/programming/references/go/preferred-patterns.md`). This shows what Level 3 depth looks like.
4. **Read the quality rubric:** Read `skills/analysis/data/references/quality-rubric.md` for Level classification criteria
5. **Read the template:** Read `skills/analysis/data/references/reference-file-template.md` for the standard structure
6. **Generate reference files:** For the top 2-3 gaps identified, create reference files that include:
- Concrete pattern tables with version ranges (e.g., "Python 3.10+: use match/case")
- Failure mode catalog with detection commands (grep/rg patterns)
- Code examples in fenced blocks
- Error-fix mappings from common issues
- Maximum 500 lines per file
7. **Update the agent/skill body:** Add a loading table that maps task types to the new reference files (or update existing table)
8. **Audit after:** Run `python3 scripts/audit-reference-depth.py --agent {name} --verbose` to verify improvement
9. **Lint:** Run `ruff check . --config pyproject.toml` and `ruff format --check . --config pyproject.toml` if any .py files were created
### Phase 2.5: Validate Enrichment Quality (Keep-or-Revert Gate)
For each enriched target, run a quick validation before committing:
1. **Generate 3 domain-specific test queries** for the agent/skill. Examples:
- For threejs-builder: "Create a holographic shader effect", "Optimize a scene with 10,000 instances", "Set up morph target animation"
- For phaser-gamedev: "Add screen shake on enemy hit", "Set up Matter.js collision categories"
- Queries should specifically exercise the domains covered by the NEW reference files
2. **Score the agent's knowledge** by checking if the agent would produce output that uses patterns from the new references:
- Read each new reference file and identify 3-5 key patterns it teaches (specific function calls, specific parameter values, specific failure modes to detect)
- For each test query, check: would the reference loading table's signal detection correctly trigger loading this reference?
- Verify the loading table entry exists and has correct file path
3. **Keep-or-revert decision:**
- If the loading table correctly maps signals to the new references AND the references contain concrete, actionable patterns (not generic advice): **KEEP**
- If the loading table is missing entries for the new references: **FIX the loading table, then KEEP**
- If the reference file contains only generic patterns that don't add domain-specific value beyond what the agent already knows: **REVERT** (delete the file, remove loading table entry)
4. **Log the decision** for each target: `[KEEP] {name}: {reason}` or `[REVERT] {name}: {reason}`
This gate prevents reference bloat — only references that add concrete, signal-matched domain knowledge survive. The enrichment system should get better, not just bigger.
### Phase 3: Commit and PR
1. Stage only the files you created/modified (reference files, agent/skill body updates)
2. Commit with: `feat(refs): {agent-name} — {brief description of what was added} (Level {before}→{after})`
- Example: `feat(refs): kubernetes prometheus-grafana — PromQL patterns, alerting rules, cardinality management (Level 0→3)`
3. Push: `git push -u origin enrich/refs-${ENRICH_RUN_ID}`
4. Create PR and auto-merge: `gh pr create --title "feat(refs): {agent-name} (Level {before}→{after})" --body "..."` then `gh pr merge --squash --auto --delete-branch`
- PR title should describe WHAT was enriched, not just the date
- PR body should include: targets processed, level before/after for each, list of new reference files
- The `--auto` flag merges once CI passes — no human review needed for reference-only changes
5. Stay in the worktree — the primary checkout owns the main branch.
## Safety Constraints
- **Never modify existing code** — only create/modify files in `references/` directories and loading tables in agent/skill bodies
- **Never modify agent/skill logic** — only add knowledge, not change behavior
- **Maximum 500 lines per reference file** — progressive disclosure principle
- **If a target already has Level 3+ references** when you actually check (audit data may be stale), skip it
- **No force-push, no commits to main** — everything goes through a PR
- **If anything fails, continue with the next target** — don't abort the whole run
- **Validation gate is mandatory** — never skip Phase 2.5, even if the references "look good"
## Output
End your session with a summary:
```
=== Reference Enrichment Summary ===
Date: {date}
Targets processed: N/M
- {name}: Level {before} → Level {after} ({new_files} new reference files)
- {name}: SKIPPED (already Level 3+)
- ...
PR: {url or "none (dry-run)"}
===
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |