| name | project-context-understanding |
| description | Provides deep project context mapping and analysis. Use PROACTIVELY before any major planning/build/review to map codebase structure, dependencies, connections, and patterns. Maps files, directories, modules, dependencies (internal/external), imports/exports, API calls, data flows, architecture patterns, and codebase conventions. Essential for context-aware analysis and personalized recommendations. |
| allowed-tools | Read, Grep, Glob, Bash |
Project Context Understanding - Deep Codebase Mapping
Purpose
This skill provides deep understanding of project structure, dependencies, connections, architecture patterns, and conventions. It maps the entire codebase to enable context-aware analysis and personalized recommendations.
Unique Value:
- Maps entire codebase structure (files, directories, modules)
- Maps dependencies (internal and external)
- Maps connections (imports, exports, API calls, data flows)
- Understands architecture patterns used
- Identifies codebase conventions and style
- Tracks relationships between components
When to Use:
- Before any major planning/build/review
- When understanding codebase structure is critical
- When dependencies need to be mapped
- When architecture patterns need to be identified
- When codebase conventions need to be understood
Quick Start
Understand project context by mapping codebase structure, dependencies, and patterns.
Example:
- Identify purpose: Planning file upload feature, need to understand project structure
- Map structure: Scan directories, identify modules, components
- Map dependencies: Internal dependencies, external libraries
- Map patterns: Architecture patterns, conventions, style
Result: Complete project context map for context-aware analysis.
Functionality First Mandate
BEFORE mapping project context, understand what you're analyzing:
-
What is the purpose of this analysis?
- What functionality are we planning/building/reviewing?
- What context do we need to understand?
-
What scope is relevant?
- Entire codebase or specific modules?
- Frontend, backend, or both?
- Specific features or components?
-
THEN map project context - Map structure, dependencies, connections relevant to the functionality
Process
Phase 1: Understand Analysis Purpose (MANDATORY FIRST STEP)
Before mapping, clarify:
-
What functionality are we analyzing?
- What problem are we solving?
- What feature/component/code are we working with?
-
What context do we need?
- Codebase structure?
- Dependencies?
- Architecture patterns?
- Codebase conventions?
- All of the above?
-
What scope is relevant?
- Entire codebase?
- Specific directories/modules?
- Related files only?
Example:
- Purpose: Planning file upload feature
- Context Needed: Backend API structure, storage services, CRM integration patterns
- Scope:
src/api/, src/services/, src/integrations/
Phase 2: Map Codebase Structure
Reference: See REFERENCE.md for detailed mapping techniques including:
- Directory structure mapping commands
- File pattern discovery
- Module structure analysis
- Output format examples
Use Grep/Glob to discover file structure:
- Directory Structure: See REFERENCE.md for commands
- File Patterns: See REFERENCE.md for commands
- Module Structure: See REFERENCE.md for commands
Phase 7: Create Dependency Graph Visualization
Create text-based dependency graph:
-
Module Dependencies:
- Map which modules import from which
- Identify circular dependencies
- Identify dependency chains
-
External Dependencies:
- Map external library usage
- Identify critical dependencies
- Identify version constraints
-
Visualization:
Dependency Graph:
components/UploadForm
├─> api/files
│ ├─> services/storage
│ │ └─> aws-sdk (external)
│ └─> services/crm-client
│ └─> axios (external)
└─> utils/validation
└─> (no dependencies)
Document:
- Module dependency graph
- External dependency usage
- Critical dependency paths
Phase 8: Track Component Relationships
Track relationships between components:
-
Component Hierarchy:
- Parent-child relationships
- Component composition patterns
- Shared component usage
-
Data Flow:
- Props flow (parent → child)
- State flow (component → state management)
- Event flow (child → parent)
-
Service Relationships:
- Service dependencies
- Service composition
- Service interfaces
Document:
- Component relationships
- Data flow patterns
- Service relationships
Example Output:
Component Relationships:
UploadForm (parent)
├─> FileInput (child)
│ └─> Receives: onFileSelect, accept, maxSize
│ └─> Emits: fileSelected event
├─> ProgressBar (child)
│ └─> Receives: progress (0-100)
└─> ErrorMessage (child)
└─> Receives: error message
Data Flow:
User selects file → FileInput → UploadForm → api/files → storage service
Output Format
MANDATORY TEMPLATE - Use this exact structure:
# Project Context Analysis
## Analysis Purpose
[What functionality are we analyzing? What context do we need?]
## Codebase Structure
[Directory structure, file organization, module boundaries]
## Dependencies
[External dependencies, internal dependencies, dependency graph]
## Connections
[Import/export relationships, API calls, data flows]
## Architecture Patterns
[Architecture type, design patterns, pattern examples]
## Codebase Conventions
[Naming conventions, structure conventions, style conventions]
## Dependency Graph
[Text-based visualization of dependencies]
## Component Relationships
[Component hierarchy, data flow, service relationships]
## Key Insights
[Summary of critical findings relevant to functionality]
Usage Guidelines
For Planning
- Map entire codebase structure to understand where new features fit
- Map dependencies to understand integration points
- Map architecture patterns to follow existing patterns
- Map conventions to maintain consistency
For Building
- Map relevant modules to understand where to add code
- Map dependencies to understand what's available
- Map patterns to follow existing patterns
- Map conventions to maintain code style
For Review
- Map affected modules to understand impact
- Map dependencies to check for breaking changes
- Map patterns to verify pattern compliance
- Map conventions to verify style compliance
- Accurate: Verify findings by reading actual files
Troubleshooting
Common Issues:
-
Context mapping without understanding purpose
- Symptom: Mapping everything, not relevant context
- Cause: Didn't identify purpose of analysis
- Fix: Identify purpose first, map only relevant context
- Prevention: Always identify purpose before mapping
-
Incomplete context mapping
- Symptom: Missing dependencies or connections
- Cause: Didn't complete all mapping steps
- Fix: Complete all steps: structure, dependencies, connections, patterns, conventions
- Prevention: Always complete all mapping steps
-
Context not verified
- Symptom: Mapped context inaccurate or outdated
- Cause: Didn't verify findings by reading files
- Fix: Verify findings by reading actual files
- Prevention: Always verify findings by reading files
If issues persist:
- Verify purpose was identified first
- Check that all mapping steps were completed
- Ensure findings were verified by reading files
- Review key principles section
Key Principles
- Purpose-Driven: Map context relevant to functionality being analyzed
- Comprehensive: Map structure, dependencies, connections, patterns, conventions
- Visual: Use text-based visualizations for clarity
- Actionable: Provide insights that inform decisions
- Efficient: Use Grep/Glob to discover patterns quickly
- Accurate: Verify findings by reading actual files
Common Mistakes to Avoid
- Mapping Everything: Don't map entire codebase if only specific modules are relevant
- Missing Dependencies: Don't forget to map internal dependencies
- Ignoring Patterns: Don't miss architectural patterns that inform design
- Generic Analysis: Don't provide generic analysis - be specific to codebase
- No Verification: Don't assume structure - verify by reading files
- Missing Connections: Don't forget to map import/export relationships
This skill enables context-aware analysis and personalized recommendations by deeply understanding project structure, dependencies, connections, architecture patterns, and conventions.