Systematic project orientation for unfamiliar codebases. Automatically activates when Claude detects uncertainty about project state, structure, or tooling. Analyzes git state (branch, changes, commits), project type (language, framework, structure), and development tooling (build, test, lint, CI/CD). Provides structured summary with risk flags and recommendations. Use when entering new projects or when working on shaky assumptions.
Systematic project orientation for unfamiliar codebases. Automatically activates when Claude detects uncertainty about project state, structure, or tooling. Analyzes git state (branch, changes, commits), project type (language, framework, structure), and development tooling (build, test, lint, CI/CD). Provides structured summary with risk flags and recommendations. Use when entering new projects or when working on shaky assumptions.
Systematic project orientation to understand codebase state before making changes. Prevents working on incorrect assumptions by establishing clear context about git state, project structure, and development tooling.
Core Expertise
Automatic Activation Detection:
Detects uncertainty in Claude's reasoning or responses
Activates on manual user requests for orientation
Focuses on git repositories only
Discovery Capabilities:
Git state analysis (branch, changes, remote sync, commit history)
Project type identification (language, framework, monorepo detection)
Development tooling discovery (build, test, lint, CI/CD)
Risk flag identification (uncommitted work, branch divergence)
Output:
Structured summary of project state
Critical risk flags highlighted
Actionable next-step recommendations
2-3 minute discovery timeframe
When This Skill Activates
Automatic Triggers
This skill automatically activates when Claude's internal reasoning or responses contain uncertainty phrases like:
"I should first understand..."
"Let me check the project..."
"Not sure about the structure..."
"I need to understand..."
"Before proceeding, let me..."
"I'm uncertain about..."
"Let me investigate the project..."
Rationale: These phrases indicate Claude is working on incomplete context, which can lead to incorrect assumptions, wrong commands, or inappropriate file edits.
Manual Invocation
Users can explicitly request project discovery with keywords:
"orient yourself"
"discover the project"
"understand this codebase"
"what's the project state?"
"analyze the project structure"
"give me project context"
When NOT to Activate
Do NOT activate this skill when:
Claude has clear context and is confidently executing a specific task
User is asking about specific code that Claude has already analyzed
Current conversation already established project context
Working in a non-git directory (this skill is git-focused)
Quick Discovery (Recommended)
For fast, consistent project orientation, run the bundled discovery script:
This replaces the manual 5-phase process below with a single execution that outputs structured data covering git state, project type, tooling, documentation, and risk assessment. Use the script output to populate the summary template in Phase 5.
For detailed reference on each phase, see the manual workflow below or scripts/discover.sh.
Step 5: Summarize state and recommend next actions
Goal: Synthesize all findings into actionable summary with risk flags.
Output Format Template:
# Project Discovery Summary## 📊 Project Overview-**Type**: [Language] / [Framework] / [Monorepo or Single-project]
-**Purpose**: [One-sentence description from README]
-**Entry Point**: [Main file or startup command]
## 🔀 Git State-**Branch**: [current-branch-name]
-**Status**: [X files changed, Y staged, Z unstaged] OR [Working tree clean]
-**Remote Sync**: [X commits ahead, Y commits behind] OR [In sync with origin]
-**Last Commit**: [Hash] - [Message] by [Author] ([Time ago])
-**Commit Style**: [Conventional commits detected] OR [Free-form commits]
### ⚠️ Risk Flags
[List any risk flags found in Phase 1, or state "None - safe to proceed"]
## 🛠️ Development Tooling### Build System- [Build command: npm run build / cargo build / make / etc.]
### Test Framework- [Test command: npm test / pytest / cargo test / etc.]
- [Test file location: tests/ or src/__tests__/ or *_test.rs]
### Code Quality
- **Linters**: [ESLint / ruff / clippy / etc.]
- **Formatters**: [Prettier / black / rustfmt / etc.]
- **Pre-commit Hooks**: [Configured] OR [Not configured]
### CI/CD
- [GitHub Actions: X workflows] OR [No CI/CD detected]
- [Workflows: build.yml, test.yml, deploy.yml]
## 📚 Documentation
- **README**: [Present with setup instructions] OR [Missing or minimal]
- **CONTRIBUTING**: [Present] OR [Not present]
- **Other Docs**: [docs/ directory, ARCHITECTURE.md, etc.]
## ✅ Recommendations
[Based on findings, provide 2-4 actionable recommendations, such as:]
1. **Commit uncommitted work** - You have X unstaged files that could be lost
2. **Create feature branch** - Currently on main; create a feature branch before making changes
3. **Pull latest changes** - X commits behind origin/main
4. **Run tests before changes** - Use `[test-command]` to establish baseline
5. **Review setup instructions** - Check README.md for dependencies and setup steps
6. **Safe to proceed** - Working tree clean, branch in sync, tooling detected
---
**Discovery completed in [time]. Ready to work with clear context.**
Risk Flag Priority:
🔴 Critical: Uncommitted changes + on main branch + behind remote
🟡 Warning: Any single risk flag (uncommitted changes, diverged branch, etc.)
🟢 Safe: Clean working tree, feature branch, in sync with remote
Integration with Other Skills
Related Skills
git-commit-workflow: Use after discovering conventional commit patterns
chezmoi-expert: If project is a dotfiles repo (detects chezmoi.toml)
git-security-checks: Run if pre-commit hooks detected
Explore agent: Delegate to this agent if deeper codebase exploration needed beyond initial orientation
When to Delegate
After project discovery, if user asks for deeper investigation:
"How does authentication work?" → Use Explore agent
"Review this code for security" → Use security-audit agent
"Understand the architecture" → Use code-analysis agent
Project discovery establishes baseline context; specialized skills handle deep investigation.
Error Handling & Edge Cases
Non-Git Directory
If git status fails (not a git repository):
⚠️ **Not a Git Repository**
This skill is designed for git repositories only. This directory does not have a `.git` folder.
**Recommendations:**1. Initialize git: `git init`2. Or navigate to a git repository
3. Or use manual exploration tools (ls, find, etc.) for non-git projects
Empty Repository
If git repo exists but has no commits:
ℹ️ **Empty Git Repository**
This is a newly initialized git repository with no commits yet.
**Recommendations:**1. Make initial commit to establish git history
2. Check README.md for project purpose (if exists)
3. Proceed with caution - no version history to reference
Large Monorepo Performance
If discovery takes >30 seconds (e.g., huge monorepo):
ℹ️ **Large Repository Detected**
Discovery is taking longer than expected. For large monorepos, consider:
1.**Focus on specific subdirectory**: Navigate to relevant sub-project first
2.**Use targeted exploration**: Ask specific questions rather than full discovery
3.**Check monorepo docs**: Often have READMEs explaining structure
Missing Documentation
If no README.md or minimal content:
⚠️ **Documentation Sparse**
No README.md found or content is minimal.
**Recommendations:**1. Check commit messages for context about project purpose
2. Examine directory structure and entry points
3. Look for inline code comments
4. Ask user for project context if available
Best Practices
Before Making Any Changes
Always run project discovery when entering an unfamiliar codebase
Check git state to preserve uncommitted work
Identify tooling to use correct build/test commands
Read README for setup requirements and project conventions
Discovery Efficiency
Complete all 5 steps even if early steps reveal issues (comprehensive context prevents follow-up questions)
Highlight risk flags prominently in summary
Provide actionable recommendations specific to the project state
Keep discovery focused (2-3 minutes; defer deep investigation to specialized skills)
Integration with Workflow
Discovery first, then action - Establish context before editing files
Update mental model - If discovery reveals surprises, re-evaluate planned approach
Respect git state - Don't ignore risk flags; address them before proceeding
Quick Reference: Discovery Commands
Essential Git Commands
git branch --show-current # Current branch
git status --short --branch # Git state summary
git log --oneline -n 10 # Recent commits
git rev-list --count HEAD...@{u} # Commits ahead/behind remote
