codebase-context

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]

About this skill