/potpie-repo-baseline

name: potpie-repo-baseline
description: "Use when establishing, refreshing, or deeply understanding a repository's baseline memory in Potpie: purpose, application type, features, services/modules, environments, deploy shape, dependencies, API contracts, datastores, integrations, ownership, and explicit preferences. The harness reads authored and code-adjacent sources, then writes graph workbench mutations."

Potpie Repo Baseline

Use this skill when the user asks to ingest, refresh, establish, or deeply understand what a repository is and how it works.

Procedure

1. Resolve the pot and source:

potpie --json pot info
potpie --json source list
potpie source add repo . --pot <pot-id-or-name>

Source registration records metadata only. It does not ingest or scan.

2. Discover the live graph contract:

potpie --json graph status
potpie --json graph catalog --task "deep repo baseline"
potpie --json graph describe features --view feature_context --examples
potpie --json graph describe infra_topology --view service_neighborhood --examples
potpie --json graph describe decisions --view preferences_for_scope --examples

3. Create todos for the baseline lanes: docs/product, repo map, runtime/deploy, API/data/integrations, preferences/workflows, synthesis, identity resolution, write, verify. 4. Read authored sources first, then inspect source files that are authoritative for durable facts: routes, service clients, adapters, deployment targets, API contracts, model/datastore usage, and test/workflow commands. 5. Resolve identity before writing:

potpie graph search-entities "<repo service feature>" --limit 10
potpie graph search-entities "<service>" --type Service --environment prod --limit 10

6. Write one or more semantic mutation batches:

potpie --json graph propose --file mutation.json
potpie --json graph commit <plan_id> --verify
potpie --json graph history --plan <plan_id>

`graph mutation-template --kind repo-baseline` is an optional skeleton helper; trust `graph catalog` and `graph describe ... --examples` for the live contract.

Deep Baseline Mode

Use this mode whenever the user says "ingest repo", "deeply understand", "baseline this repo", or asks for broad repo memory.

1. Product and docs:

• README, docs, ADRs, runbooks, contributing guide, package metadata,

public docs, linked websites.

• Capture purpose, app type, domain vocabulary, explicit features,

decisions, preferences, and workflows. 2. Repo map:

• Manifests, top-level apps/packages, framework config, route/API

entrypoints, generated API specs, tests.

• Capture services/modules only when a source clearly supports them.

3. Runtime and deploy:

• Dockerfiles, compose, Kubernetes, Terraform, CI workflows, deploy scripts,

environment templates, feature flags.

• Capture environments, deploy shape, config variables, release/test

workflows, and ownership when explicit. 4. API, data, and integrations:

• Service clients, adapters, auth providers, queues, datastore/model usage,

external API clients.

• Capture APIContract, DataStore, Adapter, Dependency, and integration facts

with file/doc evidence. 5. Preferences and local workflows:

• Contribution docs, lint/test configs, Makefiles, package scripts,

PR templates, code comments that explicitly state policy.

• Record only reusable explicit preferences.

6. Synthesis:

• Build an evidence matrix before writing. Split high-confidence facts from

uncertain observations. Use inbox for useful but weak findings.

Source Priority

1. README and authored docs. 2. ADRs, runbooks, architecture docs, deployment docs. 3. Package/app manifests and top-level workspace definitions. 4. CI/deploy workflows and environment templates. 5. Framework config and route/API specs. 6. Visible route/API entrypoints. 7. Service clients/adapters, only to confirm topology. 8. Datastore/model usage, only to confirm durable infra facts. 9. Tests and fixtures, only to confirm workflows, API behavior, or feature intent that is otherwise explicit.

Baseline Memory

Record source-backed repository purpose, app type, features, deployable services or modules, environments, deploy shape, dependencies, adapters, datastores, API contracts, important integrations, ownership, local workflows, and explicit coding preferences.

Use canonical entity families when writing: `Repository`, `Service`, `Feature`, `Environment`, `DataStore`, `APIContract`, `Dependency`, and `Preference`. Represent capabilities as `Feature` entities; link repos or services with `PROVIDES`, and use `IMPLEMENTED_IN` when a source locates implementation. Use topology relations such as `DEFINED_IN`, `DEPLOYED_TO`, `DEPENDS_ON`, `USES`, `EXPOSES`, `USES_ADAPTER`, `CONFIGURES`, and `OWNED_BY` only when the source supports the relation. Link explicit preferences with `POLICY_APPLIES_TO`.

Use `authoritative_fact` for explicit source-of-truth evidence, such as docs, deployment config, API specs, or source files that define behavior. Use `source_observation` for direct observations that are not necessarily policy. Use `agent_claim` for lower-authority synthesis. Every entity and claim needs a compact summary, retrieval-grade description, confidence, truth class, source authority, and source refs when available.

Mutation Requirements

Before proposing:

• Resolve existing repository, service, feature, dependency, and owner entities.
• Prefer updating/linking existing entities over creating near-duplicates.
• Include evidence for `authoritative_fact` and `source_observation`.
• Keep one mutation file to one coherent family or source slice when possible.
• Put low-confidence but useful findings into `graph inbox add`.

After committing:

potpie graph read --subgraph features --view feature_context --scope anchor_entity_key:<repo-key> --limit 50
potpie graph read --subgraph infra_topology --view service