/potpie-source-ingestion

name: potpie-source-ingestion
description: "Use when the user explicitly asks to ingest, refresh, or deeply understand a repository, PR, issue, ticket, runbook, incident report, document, or web link into Potpie. The harness performs todo-driven discovery, uses local/GitHub/integration tools and read-only subagents when available, builds evidence-backed semantic mutations, and writes through graph propose/verified commit."

Potpie Source Ingestion

Use this skill for explicit ingestion requests. The harness is the intelligence: it gathers source data, reads it, decides what is durable, resolves identity, and writes semantic graph mutations with evidence. Potpie validates and stores; it does not decide what source material means.

Non-Negotiables

• Use a todo/checklist for every repository or multi-source ingestion. Do not

jump directly from a README to graph writes.

• Local inspection is required for repo understanding. Scanner-driven graph

updates are forbidden. Inspect files with `rg`, `rg --files`, `git`, and structured tooling; do not run legacy or deterministic ingestion/scanner commands that walk the tree and write graph facts.

• Use subagents only for read-only discovery slices. The main agent owns source

selection, identity resolution, mutation proposals, commits, and final synthesis.

• Do not write until each required discovery lane is complete, explicitly

unavailable, or intentionally scoped out by the user.

• Every write needs source refs, source authority, truth class, confidence,

compact summary, and retrieval-grade description.

Phase 0: Scope And Preflight

1. Define source kind, pot/project, repo/path/URL, time window, and target memory shape: baseline, history, docs, infra, debug memory, preferences, or all. 2. Verify Potpie scope and graph availability:

potpie --json pot info
potpie --json source list
potpie --json graph status
potpie --json graph catalog --task "harness-led source ingestion"

3. If the repo is not registered, register metadata only. Use explicit `--pot` when pot scope is ambiguous:

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

4. Describe the views you expect to write/read before authoring mutations:

potpie --json graph describe features --view feature_context --examples
potpie --json graph describe infra_topology --view service_neighborhood --examples
potpie --json graph describe recent_changes --view timeline --examples
potpie --json graph describe decisions --view preferences_for_scope --examples
potpie --json graph describe debugging --view prior_occurrences --examples

5. If the CLI is unavailable or broken, continue discovery, build the proposed evidence matrix, and stop before committing graph writes.

Phase 1: Todo Plan

Create and maintain todos with at least these lanes for repository ingestion:

• Scope, pot, source registration, and graph contract preflight.
• Product/docs: README, docs, ADRs, runbooks, public docs, linked websites.
• Local repo map: manifests, packages/apps, entrypoints, route/API surfaces,

tests, framework config, major modules, generated/API specs.

• Runtime/deploy: Dockerfiles, compose, Kubernetes, Terraform, CI workflows,

deploy scripts, environment templates, feature flags.

• API/data/integrations: service clients, adapters, datastores, models,

queues, auth providers, external APIs.

• GitHub/history: repo metadata, topics, releases/tags, recent merged PRs, open

issues, linked tickets/docs, CI/deploy records.

• Preferences/workflows: explicit coding style, test commands, local dev setup,

release/deploy/runbook workflows.

• Synthesis: evidence matrix, candidate graph facts, identity resolution,

proposal, verified commit, and gate-driven follow-up checks.

Update todos as lanes finish. Preserve uncertain findings for the inbox instead of forcing them into canonical graph claims.

Phase 2: Parallel Discovery

Parallelize independent read-only slices when tools allow it. Recommended subagent prompts:

• Docs/product: "Read README, docs, ADRs, runbooks, package metadata, and linked

product pages. Return product purpose, features, explicit decisions, preferences, workflows, and source refs. Do not write mutations."

• Local architecture: "Inspect manifests, top-level apps/packages, entrypoints,

route/API surfaces, tests, and framework config. Return service/module map, likely features, explicit source files, uncertainty, and no mutations."

• Runtime/deploy: "Inspect Docker/compose/Kubernetes/Terraform/CI/deploy/env

templates. Return environments, deploy shape, config variables, workflows, datastores, and source refs. Do not write mutations."

• API/data/integrations: "Inspect route specs, client/adapters, models,

datastores, queues, auth, and external integrations. Return candidate APIContract/DataStore/Adapter/Dependency facts with evidence. No mutations."

• GitHub history: "Use GitHub tools/CLI for repo metadata, releases, recent

merged PRs, open issues, linked tickets/docs, and CI signal. Return timeline, fixes, decisions, bug patterns, and source refs. No mutations."

• Preferences: "Find explicit preferences in docs, config, tests, contribution

guides, PR templates, and comments. Return only explicit reusable policies with evidence. No mutations."

The main agent should continue non-overlapping discovery while subagents run.

Phase 3: Local Repo Inspection Targets

Use structured, bounded local inspection. Examples:

rg --files -g 'README*' -g 'docs/**' -g '*ADR*' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'
rg --files -g 'Dockerfile*' -g 'docker-compose*' -g '.github/workflows/**' -g '*.tf' -g 'k8s/**' -g '.env*'
rg -n "FastAPI|APIRouter|express\\(|router\\.|Django|Flask|NextResponse|route\\(" .
rg -n "postgres|mysql|redis|mongo|s3|kafka|rabbit|queue|oauth|stripe|slack|github|linear|jira" .
rg -n "pytest|vitest|jest|playwright|make test|npm test|uv run|cargo test" RE