cross-service-research
Cross-microservice research and planning across multiple repositories, with findings saved to Obsidian. Use when the user asks to investigate, research, plan, understand, or trace functionality across
SKILL.mdskills/cross-service-research/SKILL.md
GitHubCross-Service Research
Research across multiple repositories and save findings to Obsidian.
Constraints
- Read-only: Never modify source code unless explicitly asked. This skill is for research and planning.
- Ignore worktrees: Directories with a
.gitfile (not directory) are worktrees. Skip them unless explicitly asked. - Output to Obsidian: Write all findings to Obsidian via CLI. See Output to Obsidian.
Setup
Before starting, determine:
- Base path — The workspace directory containing repos (e.g.,
/Users/milton/Workspaces/K/) - Vault — Ask the user which Obsidian vault to use. Always pass
vault="<name>"to the CLI.
To list main repos (skip worktrees):
for dir in <base_path>/*/; do
[ -d "$dir/.git" ] && echo "$(basename $dir)"
done
Research Workflow
1. Scope the Research
Clarify what the user needs. Common patterns:
- Data flow: How data moves from service A to B (endpoints, events, shared DBs)
- Schema/contract: What models or API contracts services share
- Pattern comparison: How different services solve the same problem
- Feature planning: What services a new feature will touch
2. Discover Relevant Services
Use warpgrep_codebase_search as the primary search tool — it runs parallel grep+read with natural language queries, ideal for broad cross-repo exploration.
mcp__morph-mcp__warpgrep_codebase_search(
search_string="<natural language description>",
repo_path="<base_path>/<service>"
)
3. Search Strategy
Preferred: warpgrep_codebase_search — Exploratory, broad, or complex searches. Describe what you're looking for in natural language. Run multiple calls in parallel across repos.
Fallback: Grep — Precise pattern matching when you know the exact regex within an already-identified scope.
Grep pattern="@(app|router)\.(get|post|put|delete|patch)" path="<base_path>/<service>/"
Grep pattern="(BASE_URL|SERVICE_URL|httpx|requests\.)" path="<base_path>/<service>/"
Grep pattern="class \w+(BaseModel|Base):" path="<base_path>/<service>/app/"
4. Trace Inter-Service Communication
| Pattern | How to Find |
|---|---|
| HTTP calls between services | warpgrep for "HTTP calls to other services" or Grep for httpx, requests, base URLs |
| Shared libraries | Check for common dependency packages |
| Message queues / events | warpgrep for "event publishing" or Grep for queue/topic names |
| Shared databases | Grep for connection strings, model imports |
5. Parallel Multi-Repo Search
Launch parallel warpgrep calls — one per repo:
warpgrep(search_string="<query>", repo_path="<base_path>/service-a")
warpgrep(search_string="<query>", repo_path="<base_path>/service-b")
warpgrep(search_string="<query>", repo_path="<base_path>/service-c")
Output to Obsidian
Save all research to Obsidian using the obsidian CLI. Target vault: vault="<vault_name>" (ask user at start).
Base folder: Projects/Research/<mission>/ where <mission> is a short kebab-case name (e.g., auth-flow, whatsapp-routing).
Creating notes
Use obsidian create with silent to avoid opening each note:
obsidian vault="<vault>" create path="Projects/Research/<mission>/Summary.md" content="<content>" silent
For appending to existing notes:
obsidian vault="<vault>" append path="Projects/Research/<mission>/Summary.md" content="<content>"
Document structure per mission
Create these notes as needed:
| Note | Purpose |
|---|---|
Summary |
Always create. Overview + conclusions + open questions. Links to other notes. |
<Service> Findings |
Per-service deep dives |
Flow |
Data/control flow descriptions with mermaid diagrams |
Comparison |
Side-by-side pattern comparisons across services |
Note format
Use Obsidian Flavored Markdown. See the obsidian-markdown skill for full syntax reference.
- Properties (frontmatter): Include
tags,date, andmissionfor each note - Wikilinks: Use
[[note]]to link between research notes in the same mission - Callouts: Use
> [!important],> [!warning],> [!info]for key findings - Mermaid diagrams: For architecture and flow visualizations
- Code references: Include
file_path:line_numberformat for all key code locations
Example Summary note content:
---
tags:
- research
- cross-service
date: <today>
mission: <mission-name>
---
# <Mission Title>
> [!abstract] TL;DR
> One paragraph answering the research question.
## Services Involved
- [[<Service A> Findings]]
- [[<Service B> Findings]]
## Key Findings
> [!important] Finding 1
> Description with `path/to/file.py:42` reference.
## Architecture
```mermaid
graph LR
A[Service A] -->|HTTP| B[Service B]
B -->|Events| C[Service C]
```
## Open Questions
- [ ] Question 1
- [ ] Question 2
Checking for existing research
Before creating notes, search the vault to avoid duplicates:
obsidian vault="<vault>" search query="<mission-name>" limit=5
Team-Based Research
For large missions spanning 3+ services, use TeamCreate to parallelize. Each teammate investigates one or more services concurrently.
Setup
TeamCreate(team_name="research-<mission>", description="Cross-service research: <objective>")
Task structure
- Create one task per service or per research question
- Spawn
general-purposeteammates withteam_name - Each teammate:
- Receives mission context and assigned service(s)
- Uses warpgrep/Grep to investigate (read-only)
- Returns findings as text (lead writes to Obsidian)
- The lead (you) consolidates and writes all notes to Obsidian
- Clean up teams with
TeamDelete
Teammate prompt template
You are researching a codebase. Your mission: <objective>.
Your assigned service(s): <service-list> at <base_path>/<service>/
Rules:
- READ-ONLY. Do not modify any source code.
- Ignore worktree directories (those with a .git file instead of directory).
- Use warpgrep_codebase_search as primary search tool.
- Return findings as structured text with file_path:line_number references.
- Mark your task complete when done.
When to use teams vs solo
| Scenario | Approach |
|---|---|
| Quick lookup in 1-2 services | Solo with warpgrep |
| Tracing a flow across 2-3 services | Solo with parallel warpgrep calls |
| Broad research across 3+ services | Team — one teammate per service |
Tips
- warpgrep first, Grep second: Start broad, narrow down.
- Launch parallel warpgrep calls across repos — one per repo in the same message.
- Always ask for vault name before writing to Obsidian.
- Use
obsidian searchto check for existing research before creating duplicates. - If a service map exists for the workspace (like a
references/service-map.md), read it first to orient.