Repository Discovery

Contributed by: Mark Whaley · Source: PM Starter Kit

Use this when a PM needs to know which code repositories implement which services, where in those repos each service lives, and who maintains them. Takes verified services from /architecture-context-reviewer and resolves them to repos, service root paths, and ownership using service catalogs, repo metadata, CODEOWNERS, and build artifacts.

This skill grounds downstream code analysis in the correct locations. It sits in the Feature Impact Radar pipeline: /technical-intent-parser → /architecture-context-reviewer → /repository-discovery → /codependency-analyzer.

Process

Step 1: Gather inputs

Ask the user:

1. Services — The verified service names from /architecture-context-reviewer (e.g., billing-service, notification-service). If coming from the pipeline, these are already available.
2. Systems involved — The system domains (e.g., billing, notifications, user_preferences).
3. Repo host — Where does your code live? (GitHub, GitLab, Bitbucket.) Which org(s) should I search?
4. Repo model — Is the codebase primarily a monorepo, many service repos (polyrepo), or mixed?
5. Service catalog link (optional) — Do you have a service catalog/registry (Backstage, Cortex, etc.) that maps services to repos?

If services and systems are missing, stop and request them (or run the upstream skills first).

Step 2: Identify which personas are affected

Before generating the discovery, prompt the user:

Persona check: Which user persona(s) does this codebase serve? If you have defined personas (e.g., from /persona-create or /persona-draft), name them. If not, describe who uses the product these services power.

This connects repository structure to real user outcomes and helps prioritize which repos matter most for product decisions.

Step 3: Resolve service → repo mapping

For each service, follow this priority order:

Primary path — Service catalog/registry:

• Check for repo URL, repo slug (org/repo), service descriptor (catalog-info.yaml), and owning team.

Fallback — Repo host search (only if catalog mapping is missing):

• Search with progressively broader queries:
  • Exact service name: "billing-service"
  • Likely variants: "billing", "billing svc", "billing api"
  • Service descriptors: catalog-info.yaml or service.yaml containing the service name
  • Deployment artifacts: Helm chart names, Docker image names

Verification rule: Do not accept a repo as a match until you see at least one of:

• Service descriptor file declaring the service
• Build artifact naming the service
• Documentation clearly stating "this repo is the service"

Step 4: Identify service root paths

If monorepo:

• Locate the service root directory using catalog-info.yaml/service.yaml paths, Dockerfile + build pipeline references, or directory conventions (services/<name>, apps/<name>).

If single-service repo:

• Service path is / (repo root), unless evidence says otherwise.

Step 5: Extract maintainers/owners

For each repo and/or service path, extract maintainers from:

• CODEOWNERS (path-level owners preferred)
• OWNERS / MAINTAINERS
• Service catalog ownership fields
• On-call/team metadata

Prefer team slugs/handles over individuals (e.g., payments-team). If only individuals are available, include them and note that team owner is unknown.

Step 6: Present the discovery

## Repository Discovery — (Feature/Context Name)

**Date:** (Date)
**Repo host:** (GitHub/GitLab/Bitbucket)
**Repo model:** (Monorepo / Polyrepo / Mixed)
**Confidence level:** (High / Medium / Low)

---

### Repositories

| Repository | Description | Primary language |
|---|---|---|
| (org/repo) | (What this repo contains) | (Language/framework) |

### Service → Repo Mapping

| Service | Repository | Service root path | Evidence |
|---|---|---|---|
| (service-name) | (org/repo) | (path, e.g., `/` or `services/billing`) | (How this was confirmed) |

### Maintainers / Owners

| Repository : Path | Owning team | Source |
|---|---|---|
| (org/repo:path) | (team slug) | (CODEOWNERS / catalog / repo settings) |

### Discovery Gaps

- (What couldn't be resolved — e.g., "No repo found for user-preferences-service")
- (Missing evidence — e.g., "CODEOWNERS not present in messaging/notification-platform")

### Questions for the Team

1. (Question about gaps — e.g., "Which repo implements user-preferences-service?")
2. (Question about ownership — e.g., "Who maintains the shared libraries in core/monorepo:libs/?")

Step 7: Review and validate

Ask the user:

• Do the repo mappings look correct?
• Are there repos I missed that contain relevant services?
• Are the ownership mappings accurate?
• Ready to proceed to /codependency-analyzer with these repo locations?

Adjust as needed.

Related skills

• /architecture-context-reviewer — upstream: provides the verified services this skill maps to repos.
• /codependency-analyzer — next step: analyzes code dependencies within the discovered repos.
• /technical-intent-parser — pipeline entry point: decomposes a feature into technical signals.
• /context-packet — when building broader project context that includes codebase as one input.

Output location

Present the repo mapping, maintainers, and gaps as formatted text in the conversation. The output feeds directly into /codependency-analyzer and downstream pipeline skills. The user may also use it as a standalone reference for codebase onboarding or engagement discovery.