| name | codebase-context |
| description | Gather architectural context about an internal system from code and documentation across the organization — use when asked to understand a system's architecture, find its repos, or get an overview before working on it. |
Codebase Context
Gather comprehensive architectural context about an internal system by searching code and documentation across the organization.
Determine the system name from the user's request. If not specified, ask before proceeding.
Core Principles
- Breadth before depth: Find all relevant pieces before diving deep
- Docs + code: Both tell important parts of the story
- Be skeptical: Not every search result is relevant context
- Freshness matters: Stale docs can mislead
Process
Phase 1: Find the Code
Search for the system's codebase across all repositories:
code_search "[system] main OR core updated:past_month"
code_search "[system] service handler"
Look for:
- Main entry points and core modules
- API definitions (REST, gRPC, GraphQL)
- Key data structures and models
Phase 2: Find the Documentation
Search for architecture and design docs:
search "[system] architecture OR design doc"
search "[system] RFC OR proposal"
search "[system] runbook OR playbook"
Phase 3: Identify Key Contributors
Find who's actively working on this system:
code_search "[system] owner:* updated:past_month"
Cross-reference with employee_search for contact info.
Phase 4: Vet All Content
For each piece of content, evaluate:
| Test | ✅ Include | ⚠️ Note | ❌ Reject |
|---|
| Relevance | Core component, directly relevant | Mentions system but not central | Keyword coincidence |
| Currency | <6 months, matches code | 6-12 months | 12+ months with no activity |
| Authority | Approved RFC, design doc, official runbook | Team wiki, notes, drafts | Outdated proposals, abandoned work |
| Doc/Code consistency | Docs reflect current state | Note discrepancy, prefer code | Doc significantly wrong — warn user |
Repository Health:
- ✅ ACTIVE: Commits in past month
- ⚠️ SLOWING: Last commit 1-6 months ago
- ❌ STALE: No commits in 6+ months
Phase 5: Generate Vetted Context Report
# Codebase Context: [System Name]
## Freshness Check
| Component | Last Updated | Status |
|-----------|--------------|--------|
| Main repo | [date] | Active / Slowing / Stale |
| Design doc | [date] | Current / Aging / Outdated |
## Overview
[1-2 paragraph summary synthesized from current docs — note age of sources]
## Key Repositories
| Repository | Purpose | Last Active | Status |
|------------|---------|-------------|--------|
| [repo] | [what it does] | [date] | Active / Stale |
## Architecture Highlights
[Only include if from recent/authoritative sources]
- **API Layer**: [description] (source: [doc], updated [date])
- **Data Model**: [description]
- **Key Dependencies**: [list]
## Documentation (Vetted)
### Current & Authoritative
| Doc | Type | Updated | Summary |
|-----|------|---------|---------|
| [Title] | RFC | [date] | [summary] |
### Use With Caution (Aging)
| Doc | Type | Updated | Caveat |
|-----|------|---------|--------|
| [Title] | Design doc | [date] | May not reflect current implementation |
## Key Contributors
| Name | Role | Last Active | Contact |
|------|------|-------------|---------|
| [Name] | [Title] | [date] | [email] |
## Related Systems
- **Upstream**: [systems that call this one]
- **Downstream**: [systems this one calls]
## Warnings
- [ ] [Any concerns about the system's state]
If Limited Context Found
# Codebase Context: [System Name]
## Limited Context Available
Found limited authoritative information about this system.
**What was found:** [code/docs summary]
**Gaps:** No recent design documentation, no clear architectural overview
**Suggested next steps:**
1. Check with [suggested team/person]
2. Explore the code directly: [suggested entry points]
Troubleshooting
No Results Found
- Try alternative system names or acronyms
- Search for related technologies
- Check if the system might be in a private repo
Conflicting Information
- Note the discrepancy clearly
- Prefer code as source of truth for current state
- Reference doc dates to identify which might be outdated
