context-graph-apply

name

context-graph-apply

description

INVOKE THIS SKILL when translating a context-graph-mining report into an experiment variant for the procurement-agent. Reads the report's proposed diffs and writes a variant config bundle to `experiments/variants/<id>/` (manifest.yaml + system_prompt.txt + optional vendors.json + departments.json). Does NOT modify procurement-agent source — runtime parameterization means the variant is purely additive config. Use after `context-graph-mining` produces a report; output feeds `procurement-experiment run-experiment`.

Context Graph Apply

This skill translates a context-graph-mining report into a runnable experiment variant for the procurement-agent. It writes a config bundle that the agent loads at startup when EXPERIMENT_VARIANT=<id> is set — no source code is modified.

When to use

After context-graph-mining produces a report identifying clusters and proposed changes, invoke this skill to:

• Variant A (prompt-only): write a system-prompt fragment that adds reviewer-cited context to the agent's instructions.
• Variant B (prompt + structured metadata): write the prompt fragment plus enriched vendors.json / departments.json overlays that the agent reads through lookup_vendor and lookup_department.

Both are committable to the repo; downstream callers run with EXPERIMENT_VARIANT=cycle-N-A or =cycle-N-B.

What you have access to

• The mining report (path passed by the caller — typically the most recent report in .context-graph-mining/).
• The procurement-agent source: src/models.py (Vendor, Department fields), src/agent/tools.py (lookup_vendor, lookup_department surfacing), src/variants.py (overlay load mechanics).
• An experiments/variants/ directory where the output bundle is written.

Runtime hook contract (what variants can change)

The procurement-agent supports four overlay surfaces. Stay within these:

Surface	File	Schema
System-prompt fragment	system_prompt.txt	Plain text appended to the evaluator's baseline system prompt.
Vendor metadata	vendors.json	`{"VendorName": {"cost_overrun_factor": float, "relationship_credit": str, "deprecating_in_favor_of": str
Department behavior	departments.json	{"DeptName": {"behavior_notes": list[str]}}. Each note is one short reviewer-cited pattern.
Manifest	manifest.yaml	Human-facing record of what was applied + evidence. Required.

If the mining report proposes something that doesn't fit these surfaces (e.g., a brand-new entity type, a new tool), do not invent files — flag it in the manifest's out_of_scope list and stop. The user will extend the agent's hook surface in code, then re-run.

Workflow

Phase 1 — Parse the mining report

Read the report at the path the caller supplied. Identify:

• Cluster table (Section 2 in the standard report shape): each row is (cluster_id, vendor / department / pattern, agent recommendation, reviewer decision, evidence sessions).
• Precedent extraction (Section 3): which tribal-knowledge themes are encoded vs not.
• Proposed diffs (Section 4): each proposal targets specific source files. Translate each into the appropriate overlay surface (see the mapping table above).

Skip clusters marked "weak signal" or with fewer than 5 evidence sessions.

Phase 2 — Build the variant

For variant A (cycle-N-A): produce only system_prompt.txt and manifest.yaml. The prompt fragment should:

• Tell the agent that reviewers cite institutional knowledge that matters.
• List the top 3-5 patterns from the report's Section 3 with one-line summaries.
• Be terse — under 400 words.

For variant B (cycle-N-B): produce system_prompt.txt, vendors.json, departments.json, manifest.yaml. The vendor and department overlays should encode the report's structural proposals as data:

• Translate "DataStream's quotes inflate ~40%" → {"DataStream Analytics": {"cost_overrun_factor": 1.4}}.
• Translate "Marketing panic-buys single-campaign tools" → {"Marketing": {"behavior_notes": ["Tends to panic-buy single-campaign tools — require sustained-use justification"]}}.
• Translate "CloudBase being consolidated to Vertex" → {"CloudBase Inc": {"deprecating_in_favor_of": "Vertex Solutions"}}.

Cite each overlay entry in the manifest with at least 3 evidence sessions from the report.

Phase 3 — Write manifest.yaml

Schema:

variant_id: cycle-N-{A|B}
source_report: path/to/report-<ts>.md
generated_at: ISO-8601 timestamp
applied_changes:
  - cluster: cluster-A-creativehub-marketing
    surface: system_prompt | vendors | departments
    summary: one-line description
    evidence_sessions: [PR-001, PR-042, PR-056]
    expected_effect: e.g. "reduce CreativeHub × Marketing approve→reject overrides"
out_of_scope:
  - finding: ...
    reason: requires new agent capability not in current hook surface

Phase 4 — Validate

Before writing files, check:

1. Every applied change cites ≥ 3 distinct session IDs.
2. No vendors.json or departments.json key references a vendor/department that doesn't exist in procurement-agent/src/seed_data.py (or warn explicitly in the manifest if introducing a new entity).
3. system_prompt.txt, if present, is under 400 words.
4. JSON files parse and conform to the schemas above.

If validation fails, abort with a clear message — do not write a partial bundle.

Phase 5 — Output

Write the bundle to experiments/variants/<variant_id>/. The directory must not already exist (refuse to overwrite — the caller can delete it explicitly).

Return a one-paragraph summary in the final message:

• Variant id and path.
• Number of changes applied per surface.
• Anything in out_of_scope.
• The Bash command to start an experiment-side agent with this variant: EXPERIMENT_VARIANT=<id> uv run uvicorn src.main:app --port 8001.

Modes

• Default: write the bundle to disk.
• --dry-run (requested by the caller): produce the bundle in-memory and return its contents in the final message — no files written.

Constraints

• No source modification — the procurement-agent code is invariant. Variants are config only.
• Schema fidelity — write only files in the surfaces table. Anything else gets flagged as out-of-scope.
• Evidence required — every change cites ≥3 sessions or it doesn't ship.
• Idempotency by absence — refuse to overwrite an existing variant directory. The caller deletes and re-runs if they want a clean rebuild.

Related skills

• context-graph-mining — produces the input report.
• arize-experiment — runs the variant against the dataset (next stage in the loop).