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_neighborhood --scope service:<service> --depth 2 --direction both --limit 50
potpie --json graph quality duplicate-candidates --limit 20
potpie --json graph quality low-confidence --limit 20
potpie --json graph quality conflicting-claims --limit 20

Boundaries

Baseline capture is harness-led. Do not run scanner-driven graph updates or legacy ingestion commands to invent modules, services, features, or dependencies. Do not record dependencies just because a lockfile mentions them. Do not infer baseline architecture from PR titles or issue status; change history and change-history facts belong in potpie-change-timeline. Local file inspection is allowed and expected, but the harness must read, interpret, and cite the evidence before writing semantic facts.