project-discovery

Project Discovery

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)
• Documentation quick scan (README, setup instructions)
• 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:

bash "${CLAUDE_PLUGIN_ROOT}/skills/project-discovery/scripts/discover.sh"

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.

Systematic Discovery Workflow (Manual Alternative)

When the script is unavailable, execute this 5-step systematic discovery process. Complete all steps before providing the summary.

---

Step 1: Analyze git state

Goal: Understand version control state to prevent data loss and branch confusion.

Commands to Run:

# Current branch and tracking info
git branch --show-current
git status --short --branch

# Uncommitted changes summary
git status --porcelain | wc -l
git diff --stat
git diff --staged --stat

# Remote sync status
git rev-list --left-right --count HEAD...@{u} 2>/dev/null || echo "No tracking branch"

# Recent commit history (last 10 commits)
git log --oneline --decorate -n 10

# Check for conventional commits pattern
git log --oneline -n 20 | grep -E "^[a-f0-9]+ (feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert)(\(.+\))?:"

What to Extract:

• Current branch name
• Number of uncommitted files (staged + unstaged)
• Number of commits ahead/behind remote
• Recent commit messages (look for patterns, conventional commits)
• Last commit author and date
• Whether working tree is clean

Risk Flags:

• ⚠️ Uncommitted changes exist (risk of data loss)
• ⚠️ Branch diverged from remote (conflicts possible)
• ⚠️ On main/master branch (should work on feature branch)
• ⚠️ Detached HEAD state (not on any branch)

---

Step 2: Detect project type

Goal: Identify language, framework, and project structure to use correct tooling.

Commands to Run:

# Check for project manifests (determines language/ecosystem)
ls -la | grep -E "(package\.json|Cargo\.toml|pyproject\.toml|go\.mod|Gemfile|pom\.xml|build\.gradle|composer\.json|mix\.exs)"

# Detect monorepo structure
find . -maxdepth 3 -name "package.json" -o -name "Cargo.toml" -o -name "pyproject.toml" | head -20

# Check directory structure
ls -d */ 2>/dev/null | head -20

# Find entry points (main files)
find . -maxdepth 2 -name "main.*" -o -name "index.*" -o -name "app.*" -o -name "__init__.py" 2>/dev/null | head -10

Project Manifest Detection:

File	Language/Ecosystem	Common Frameworks
package.json	JavaScript/TypeScript	React, Vue, Next.js, Express, Node
Cargo.toml	Rust	Actix, Rocket, Tokio
pyproject.toml	Python	Django, FastAPI, Flask
go.mod	Go	Gin, Echo, Fiber
Gemfile	Ruby	Rails, Sinatra
pom.xml / build.gradle	Java	Spring, Quarkus
composer.json	PHP	Laravel, Symfony
mix.exs	Elixir	Phoenix

What to Extract:

• Primary language(s) and version(s)
• Framework detected (check package.json dependencies, Cargo.toml deps, etc.)
• Monorepo vs single-project (multiple manifests = monorepo)
• Common directory patterns (src/, lib/, tests/, docs/)
• Entry point files

Additional Framework Detection:

# JavaScript/TypeScript frameworks
grep -E "(react|vue|next|nuxt|svelte|angular|express|fastify|nest)" package.json 2>/dev/null

# Python frameworks
grep -E "(django|fastapi|flask|pyramid)" pyproject.toml 2>/dev/null

# Check for specific config files
ls | grep -E "(next\.config|vite\.config|webpack\.config|tsconfig|jest\.config|pytest\.ini|setup\.py)"

---

Step 3: Discover development tooling

Goal: Identify build system, test framework, linters, and CI/CD to run correct commands.

Commands to Run:

# Build system detection
ls -la | grep -E "(Makefile|Justfile|package\.json|Cargo\.toml|pyproject\.toml)"

# Check package.json scripts (if JS/TS project)
jq -r '.scripts | keys[]' package.json 2>/dev/null | head -20

# Check Makefile targets
grep "^[a-zA-Z0-9_-]*:" Makefile 2>/dev/null | cut -d: -f1 | head -20

# Test framework detection
find . -maxdepth 3 -name "*test*" -o -name "*spec*" 2>/dev/null | grep -E "\.(js|ts|py|rs|go)$" | head -10

# Linter/formatter detection
ls -la | grep -E "(\.eslintrc|\.prettierrc|ruff\.toml|\.flake8|rustfmt\.toml|\.golangci)"

# Pre-commit hooks
ls -la .git/hooks/ 2>/dev/null | grep -v sample
cat .pre-commit-config.yaml 2>/dev/null | head -20

# CI/CD detection
ls -la .github/workflows/ 2>/dev/null | grep "\.yml"
ls -la .gitlab-ci.yml 2>/dev/null
ls -la .circleci/config.yml 2>/dev/null

What to Extract:

Build System:

• npm scripts (if package.json)
• Make targets (if Makefile)
• Cargo commands (if Rust)
• Python build tools (setuptools, poetry, hatchling)

Test Framework:

• Jest, Vitest, Mocha (JS/TS)
• pytest, unittest (Python)
• cargo test (Rust)
• go test (Go)
• Test file naming conventions

Linters/Formatters:

• ESLint, Prettier (JS/TS)
• ruff, black, flake8 (Python)
• clippy, rustfmt (Rust)
• golangci-lint (Go)

Pre-commit Hooks:

• Present or absent
• Configured tools (from .pre-commit-config.yaml)

CI/CD:

• GitHub Actions (list workflow files)
• GitLab CI
• CircleCI
• Other CI systems

---

Step 4: Scan documentation

Goal: Understand project purpose and setup requirements from documentation.

Commands to Run:

# README first section (project purpose)
head -50 README.md 2>/dev/null

# Check for common documentation files
ls -la | grep -E "(README|CONTRIBUTING|CHANGELOG|LICENSE|ARCHITECTURE|docs/)"

# Look for setup/installation instructions in README
grep -A 10 -i "install\|setup\|getting started" README.md 2>/dev/null | head -30

# Check for documentation directory
ls -la docs/ 2>/dev/null | head -20

What to Extract:

• Project name and one-sentence description
• Primary purpose (web app, library, tool, etc.)
• Key features or capabilities
• Setup/installation instructions present?
• CONTRIBUTING.md exists? (indicates contributor guidance)
• Documentation directory structure

Documentation Quality Indicators:

• ✅ README with clear description and setup steps
• ✅ CONTRIBUTING.md (good for contributions)
• ✅ CHANGELOG.md (indicates release management)
• ✅ docs/ directory (comprehensive documentation)
• ⚠️ Missing README or minimal content
• ⚠️ No setup instructions

---

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

1. Always run project discovery when entering an unfamiliar codebase
2. Check git state to preserve uncommitted work
3. Identify tooling to use correct build/test commands
4. Read README for setup requirements and project conventions

Discovery Efficiency

1. Complete all 5 steps even if early steps reveal issues (comprehensive context prevents follow-up questions)
2. Highlight risk flags prominently in summary
3. Provide actionable recommendations specific to the project state
4. Keep discovery focused (2-3 minutes; defer deep investigation to specialized skills)

Integration with Workflow

1. Discovery first, then action - Establish context before editing files
2. Update mental model - If discovery reveals surprises, re-evaluate planned approach
3. 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

Project Type Detection

ls -la | grep -E "(package\.json|Cargo\.toml|pyproject\.toml|go\.mod)"
find . -maxdepth 3 -name "package.json"       # Monorepo detection

Tooling Discovery

jq -r '.scripts | keys[]' package.json        # npm scripts
grep "^[a-zA-Z0-9_-]*:" Makefile              # Make targets
ls -la .github/workflows/                      # GitHub Actions

Documentation Scan

head -50 README.md                            # Project description
ls -la | grep -E "(README|CONTRIBUTING)"      # Key docs

---

Example Output

See examples.md for complete discovery outputs for:

• Python project with pytest + ruff + GitHub Actions
• JavaScript/TypeScript project with npm + ESLint + Vitest
• Rust project with cargo + clippy + no CI
• Monorepo with multiple sub-projects
• Project with uncommitted changes (risk flags)
• Clean project ready for work

---

Rationale: Why Systematic Discovery Matters

Problem: Claude often works on incomplete assumptions:

• Editing wrong branch
• Using incorrect build commands
• Overwriting uncommitted work
• Missing critical tooling (tests, linters)

Solution: Systematic orientation establishes:

• ✅ Clear git state (prevent data loss)
• ✅ Correct project type (use right tools)
• ✅ Available tooling (run proper commands)
• ✅ Risk awareness (flag dangerous states)

Result: Confident, accurate work on solid foundation rather than shaky assumptions.

---

For detailed command reference and more examples, see discovery-commands.md and examples.md.