OpenParable
Skip to content
← Back to skills

Graph Mutation Plan

Development
graph-mutation-plan

Graph Mutation Plan is an Agent Skill for development published in the potpie-ai/potpie repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Cookbook for composing an apply_graph_mutations plan — stable entity_key patterns, the canonical label/edge vocabulary, evidence/invalidation/confidence discipline, and a worked example. Load this when building a non-trivial mutation plan.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/potpie-ai/potpie/blob/HEAD/potpie/context-engine/adapters/outbound/reconciliation/skills/graph-mutation-plan/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/graph-mutation-plan, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Composing an apply_graph_mutations plan

Call apply_graph_mutations(plan, event_id, summary) once per logical group of mutations. The plan is idempotent on stable entity_keys, so a retried plan converges rather than duplicating. Every structural mutation must stay inside the given pot_id — never reference another pot.

Plan fields

  • summary: one-line description of what this plan records.
  • episodes: {name, episode_body, source_description, reference_time?} — narrative/source text to retain (e.g. a PR body, a note).
  • entity_upserts: {entity_key, labels, properties}.
  • edge_upserts: {edge_type, from_entity_key, to_entity_key, properties}.
  • edge_deletes: {edge_type, from_entity_key, to_entity_key}.
  • invalidations: {reason, target_entity_key?, edge_type?, from_entity_key?, to_entity_key?}.
  • evidence: {kind, ref, metadata?} — what grounds this plan.
  • confidence: float | null.
  • warnings: list[str] — anything you could not confirm.

Stable entity_key cookbook

Use these so re-ingestion (and a later live webhook for a backfilled artifact) upserts the same node:

ArtifactKey pattern
Repositorygithub:repo:<owner>/<repo>
Pull requestgithub:pr:<owner>/<repo>:<n>
Issuegithub:issue:<owner>/<repo>:<n>
Module / packagemodule:<repo>:<dotted.path>
Featurefeature:<repo>:<slug>
External ticket / issueticket:<source>:<identifier>
Activity (timeline)timeline:activity:<verb>:<short_hex>
Period buckettimeline:period:daily:<pot_id>:<YYYY-MM-DD>

When no pattern fits, mint a deterministic key from stable identifiers in the source (never a random id, never a timestamp), so the same fact re-keys the same way.

Canonical vocabulary

Always give an entity at least one canonical label — never only generic Entity. Labels/edges outside the canonical vocabulary are downgraded automatically (entities → Document / Observation, edges → RELATED_TO), so prefer a canonical type when one fits.

Entity labels (topology — source of truth is domain/ontology.py): Repository, Service, Environment, DataStore, Cluster, Team, Person. Plus the work/knowledge types the playbooks reference: Activity, Feature, Decision, Fix, BugPattern, Incident, DiagnosticSignal, Module, Document.

Edge types: DEFINED_IN (Service→Repository), DEPLOYED_TO (Service→Environment), DEPENDS_ON (Service→Service), USES (Service→DataStore), HOSTED_ON (Environment→Cluster), OWNED_BY (Service/Repository→Team/Person), MEMBER_OF (Person→Team). For completed work, an Activity carries PERFORMED (→ the actor), TOUCHED (→ the modules/features it changed), and IN_PERIOD (→ the period bucket). Use RELATED_TO only when nothing canonical fits.

Discipline

  • Justify every mutation from the event payload or a tool-observed fact. If unsure, add a warning and keep the plan minimal — don't invent.
  • Supersession → invalidation. When this event makes a prior fact untrue, add an invalidation referencing the prior entity/edge rather than silently overwriting.
  • Evidence, not vibes. Link the PR/issue/commit/url that grounds the plan under evidence; set confidence lower when the inference is indirect.

Worked example — a merged PR that fixes a bug

{
  "summary": "PR #482 fixes the retry-storm in the billing worker",
  "episodes": [{
    "name": "PR #482 body",
    "episode_body": "<the PR description text>",
    "source_description": "github pull_request merged"
  }],
  "entity_upserts": [
    {"entity_key": "timeline:activity:merged:9f3a1c",
     "labels": ["Activity"],
     "properties": {"verb": "merged", "verb_class": "code", "title": "Merge PR #482"}},
    {"entity_key": "fix:billing:retry-storm",
     "labels": ["Fix"], "properties": {"title": "Bound billing retry backoff"}}
  ],
  "edge_upserts": [
    {"edge_type": "PERFORMED", "from_entity_key": "person:github:alice",
     "to_entity_key": "timeline:activity:merged:9f3a1c"},
    {"edge_type": "TOUCHED", "from_entity_key": "timeline:activity:merged:9f3a1c",
     "to_entity_key": "module:o/r:billing.worker"},
    {"edge_type": "RESOLVED", "from_entity_key": "fix:billing:retry-storm",
     "to_entity_key": "bug:billing:retry-storm"}
  ],
  "evidence": [{"kind": "pull_request", "ref": "github:pr:o/r:482"}],
  "confidence": 0.9,
  "warnings": []
}

Trivial PRs (typo/lint) need only the Activity — no Fix or Decision. Don't invent design decisions the PR body doesn't state.