/potpie-graph

name: "potpie-graph"
version: "5"
description: "Use when the task can read or write the project-memory graph through the potpie CLI: discover the contract with `graph catalog`, read named views with `graph read`, resolve entity identity with `graph search-entities`, create validated plans with `graph propose`, commit plans with `graph commit --verify`, inspect quality with `graph quality`, or capture uncertain work with `graph inbox`. Also covers writing retrieval-grade descriptions and responding to nudges."

Potpie Graph Workbench

The graph is project memory: preferences, prior bugs and their fixes, infra topology, decisions, and a timeline of changes. You are the intelligence that reads it before acting and writes durable learnings after. Potpie validates, lowers, commits, audits, and ranks. It does **not** scan a repository or infer rich facts from prose for you.

Use text output for routine context reads. Add `--json` when a workflow needs exact machine parsing, mutation plans, commits, history verification, or full evidence/debug payloads.

1. Check Status And Discover The Contract

potpie graph status
potpie graph catalog --task "<task>" --profile read

Returns contract + ontology versions, the readable **views**, and active `match_mode` (`vector` vs `lexical`). Start graph-aware work here instead of reading docs. Use full JSON catalog output when you need mutation operation partitions, entity types, predicates, or exact machine parsing. Trust the catalog's current operation partition over any example in a skill file.

Describe the subgraph/view before a non-trivial read or write:

potpie graph describe debugging --view prior_occurrences --examples

2. Read - `graph read --subgraph --view`

potpie graph read --subgraph debugging --view prior_occurrences --query "refund race timeout" --limit 8
potpie graph read --subgraph debugging --view prior_occurrences --query "refund race timeout" --query-threshold 0.55 --limit 8
potpie graph read --subgraph decisions --view preferences_for_scope --scope repo:acme/x,path:src/payments/client.py
potpie graph read --subgraph recent_changes --view timeline --time-window 7d --limit 20 --format table
potpie graph read --subgraph recent_changes --view timeline --source-ref <github-pr-or-issue-ref> --format table
potpie graph read --subgraph infra_topology --view service_neighborhood --scope service:payments-api --depth 2 --direction out --environment prod
potpie graph neighborhood --entity service:payments-api --predicate USES --detail summary --limit 20

Views and what they answer:

| View | Inputs | Answers | |---|---|---| | `decisions.preferences_for_scope` | `--scope repo:…,path:…` `--query` | which preferences apply to this code | | `debugging.prior_occurrences` | `--query` (symptom), optional `--scope service:…` | "seen this before? what fixed it" (bug + fix/PR inline) | | `recent_changes.timeline` | optional `--scope`, `--since`, `--until`, `--time-window` | recent PRs/tickets/activity for the project pot | | `infra_topology.service_neighborhood` | `--scope service:…` `--depth` `--direction` `--environment` | dependency blast-radius, env-qualified | | `features.feature_context` | optional `--scope anchor_entity_key:repo:…` | what a repo/service does (Feature nodes via `PROVIDES` / `IMPLEMENTED_IN`) | | `decisions.active_decisions` | `--scope` | active decisions | | `code_topology.ownership_by_path` | `--scope` | who owns a scope | | `knowledge.document_context` | `--scope` | reference docs |

Text reads return compact summaries for fast orientation. Timeline reads should use `--format table` or `--format jsonl` for bounded event rows. Use `--json --detail full --relations full --format raw` only when you need the underlying relation payloads for debugging or exact machine processing. Inspect `coverage`, `freshness`, and `quality` before relying on results.

Query expansion is your job

The local embedder is small; recall depends on the query. Expand the user's words before reading: "add retry to the payments client" → also carry "timeout, flaky, tenacity, backoff, external call". That expansion is in-session reasoning, not something the daemon does.

3. Resolve identity — `graph search-entities`

**Before** linking or asserting against an existing entity, find its canonical key:

potpie graph search-entities "payments api" --type Service --limit 10
potpie graph search-entities "github issue 881" --source-ref <github-pr-or-issue-ref> --limit 10

Reuse the returned `key`. Inventing a near-duplicate key (`service:payments` vs `service:local:payments-api`) fragments the graph and breaks future reads.

4. Write - `graph propose` then verified `graph commit`

Writes are **semantic** operations (never raw graph CRUD). First create a server-held plan with `propose`; then commit exactly that `plan_id`.

potpie graph mutation-template --kind repo-baseline   # schema-only skeleton to fill
potpie --json graph propose --file mutation.json
potpie --json graph commit mutation-plan:01JY8T5C --verify
potpie --json graph history --plan mutation-plan:01JY8T5C

`mutation-template` kinds: `repo-baseline`, `feature`, `preference`, `preference-policy`, `infra-snapshot`, `bug-fix`, `decision`, `timeline-event`, `timeline-change` — placeholders only; you fill them from sources you actually read. Use the use-case templates for durable memory:

• `preference-policy` writes structured policy fields (`policy_kind`,

`prescription`, `strength`, `audience`) and can target a `CodeAsset`.

• `infra-snapshot` writes environment-qualified service, adapter, config, and

deployment-target facts (`USES_ADAPTER`, `CONFIGURES`, `DEPLOYED_WITH`).

• `timeline-change` writes source-time activity events; `occurred_at` is the

PR/ticket/deploy time, not ingestion time.

• `bug-fix` writes the symptom, known fix, and optional verification edge so

`debugging.prior_occurrences` can return the fix inlin