Project Exploration Skill
Version: 1.0
Author: Tres Pies Design
Purpose: Structured process for respectfully exploring a new project to determine collaboration readiness and fit before committing.
Philosophy: Exploration Before Commitment
When encountering a large project or codebase, explore its philosophy and patterns before diving into implementation. The goal is not just to understand the code, but to understand the project's relationship to your goals, values, and existing knowledge.
Core Principles
- Progressive Disclosure: Do not attempt to read everything at once. Start with a high-level overview and drill down as needed.
- Incremental Synthesis: Save findings as you go. Externalize understanding to prevent information loss.
- Seek Conceptual Clarity: Prioritize understanding the core philosophy, values, and goals before implementation details.
- Map Connections: Understand the project's relationship to your existing knowledge and skills. Explicitly map resonances.
- Express Genuine Enthusiasm: Collaboration is relational. Output should reflect genuine interest and readiness to contribute.
When to Use This Skill
- Invited to collaborate on a project with a large existing codebase
- Evaluating whether to adopt a library, framework, or tool
- Onboarding to a new team's repository
- Assessing whether a project's architecture supports your goals
The 5-Phase Exploration Process
Phase 1: First Impressions — Map the Terrain
Get a high-level overview of structure and scope.
- Read the README — What is this project? Who built it? What's its stated purpose?
- Scan project structure — List top-level directories and key files. Identify organizational patterns.
- Check recent activity — Last commit, release cadence, contributor count. Is this project alive?
- Document initial findings — Create an initial overview of themes, structure, and first impressions.
Output: Project overview with structure analysis and activity assessment.
Phase 2: Architecture Mapping — Taste the Water
Select 2-3 key documents or files to understand core content and patterns.
- Identify entry points — Main module, config files, core abstractions
- Map behavioral capabilities — Use semantic-clusters approach: what does this project actually do?
- Identify patterns — What architectural patterns does it follow? (MVC, plugin architecture, event-driven, etc.)
- Note dependencies — Key external dependencies and their role
Output: Architecture snapshot with capability map and pattern inventory.
Phase 3: Assess Fit — Build the Bridge
Evaluate against user's goals and constraints.
- Alignment check — Does this project's architecture support what the user wants to do?
- Pattern compatibility — Are the patterns compatible with existing work?
- Health assessment — Is the codebase healthy enough to build on? (Test coverage, documentation quality, code style consistency)
- Resonance mapping — Connect the project's philosophy to existing knowledge:
| Project Principle |
Existing Principle/Pattern |
Shared Insight |
| [Principle from project] |
[Your relevant pattern] |
[The connection] |
Phase 4: Identify Entry Points
Where would a new collaborator start?
- Most approachable areas — Well-documented, well-tested, clear interfaces
- Most impactful areas — Where contribution would add the most value
- Most risky areas — Complex, poorly documented, or tightly coupled
- Quick wins — Small improvements that build familiarity
Phase 5: Synthesis — The Exploration Brief
Produce a comprehensive assessment.
Fit Classification
| Rating |
Meaning |
Guidance |
| GREEN |
Strong fit. Architecture supports goals, patterns are compatible, codebase is healthy. |
Proceed with collaboration. Start with recommended entry points. |
| YELLOW |
Partial fit. Some concerns about architecture, patterns, or health. Manageable with effort. |
Proceed with caution. Address concerns before deep investment. |
| RED |
Poor fit. Fundamental misalignment in architecture, philosophy, or health. |
Reconsider collaboration. Document concerns for future reference. |
Output Format: Exploration Brief
## Exploration Brief: [Project Name]
**Date:** [Date]
**Repository:** [URL or path]
**Explorer:** [Name]
### Project Summary
[What this project is, who built it, what it does, and its core philosophy in 2-3 sentences.]
### Architecture Snapshot
**Structure:** [High-level organization]
**Key Patterns:** [Architectural patterns used]
**Core Dependencies:** [Major external dependencies]
**Activity:** [Last commit, release cadence, contributor count]
### Fit Assessment: [GREEN / YELLOW / RED]
**Alignment:** [Does this support your goals?]
**Pattern Compatibility:** [Are patterns compatible?]
**Codebase Health:** [Test coverage, docs quality, consistency]
### Resonance Map
| Project Principle | Existing Principle | Shared Insight |
| :--- | :--- | :--- |
| [Principle] | [Your pattern] | [Connection] |
### Recommended Entry Points
1. **[Area 1]:** [Why start here] — Risk: Low/Med/High
2. **[Area 2]:** [Why start here] — Risk: Low/Med/High
### Risks & Concerns
- [Risk 1: description and mitigation]
- [Risk 2: description and mitigation]
Quality Criteria
1---2name: project-exploration-33description: Explore a new project's philosophy and patterns before committing to collaboration. Assess architecture fit, map resonances, and identify entry points. Use when encountering a new codebase, repository, or project. Trigger phrases include 'explore this project', 'assess this codebase', 'should we collaborate on this', 'onboard me to this repo', 'evaluate this project for fit'.4metadata:5 source: https://skillmd.com/skills/dojogenesis/project-exploration-36---78# Project Exploration Skill910**Version:** 1.011**Author:** Tres Pies Design12**Purpose:** Structured process for respectfully exploring a new project to determine collaboration readiness and fit before committing.1314---1516## Philosophy: Exploration Before Commitment1718When encountering a large project or codebase, explore its philosophy and patterns before diving into implementation. The goal is not just to understand the code, but to understand the project's relationship to your goals, values, and existing knowledge.1920---2122## Core Principles2324- **Progressive Disclosure:** Do not attempt to read everything at once. Start with a high-level overview and drill down as needed.25- **Incremental Synthesis:** Save findings as you go. Externalize understanding to prevent information loss.26- **Seek Conceptual Clarity:** Prioritize understanding the core philosophy, values, and goals before implementation details.27- **Map Connections:** Understand the project's relationship to your existing knowledge and skills. Explicitly map resonances.28- **Express Genuine Enthusiasm:** Collaboration is relational. Output should reflect genuine interest and readiness to contribute.2930---3132## When to Use This Skill3334- Invited to collaborate on a project with a large existing codebase35- Evaluating whether to adopt a library, framework, or tool36- Onboarding to a new team's repository37- Assessing whether a project's architecture supports your goals3839---4041## The 5-Phase Exploration Process4243### Phase 1: First Impressions — Map the Terrain4445Get a high-level overview of structure and scope.46471. **Read the README** — What is this project? Who built it? What's its stated purpose?482. **Scan project structure** — List top-level directories and key files. Identify organizational patterns.493. **Check recent activity** — Last commit, release cadence, contributor count. Is this project alive?504. **Document initial findings** — Create an initial overview of themes, structure, and first impressions.5152**Output:** Project overview with structure analysis and activity assessment.5354### Phase 2: Architecture Mapping — Taste the Water5556Select 2-3 key documents or files to understand core content and patterns.57581. **Identify entry points** — Main module, config files, core abstractions592. **Map behavioral capabilities** — Use semantic-clusters approach: what does this project actually *do*?603. **Identify patterns** — What architectural patterns does it follow? (MVC, plugin architecture, event-driven, etc.)614. **Note dependencies** — Key external dependencies and their role6263**Output:** Architecture snapshot with capability map and pattern inventory.6465### Phase 3: Assess Fit — Build the Bridge6667Evaluate against user's goals and constraints.68691. **Alignment check** — Does this project's architecture support what the user wants to do?702. **Pattern compatibility** — Are the patterns compatible with existing work?713. **Health assessment** — Is the codebase healthy enough to build on? (Test coverage, documentation quality, code style consistency)724. **Resonance mapping** — Connect the project's philosophy to existing knowledge:7374| Project Principle | Existing Principle/Pattern | Shared Insight |75| :--- | :--- | :--- |76| [Principle from project] | [Your relevant pattern] | [The connection] |7778### Phase 4: Identify Entry Points7980Where would a new collaborator start?81821. **Most approachable areas** — Well-documented, well-tested, clear interfaces832. **Most impactful areas** — Where contribution would add the most value843. **Most risky areas** — Complex, poorly documented, or tightly coupled854. **Quick wins** — Small improvements that build familiarity8687### Phase 5: Synthesis — The Exploration Brief8889Produce a comprehensive assessment.9091---9293## Fit Classification9495| Rating | Meaning | Guidance |96|--------|---------|----------|97| **GREEN** | Strong fit. Architecture supports goals, patterns are compatible, codebase is healthy. | Proceed with collaboration. Start with recommended entry points. |98| **YELLOW** | Partial fit. Some concerns about architecture, patterns, or health. Manageable with effort. | Proceed with caution. Address concerns before deep investment. |99| **RED** | Poor fit. Fundamental misalignment in architecture, philosophy, or health. | Reconsider collaboration. Document concerns for future reference. |100101---102103## Output Format: Exploration Brief104105```markdown106## Exploration Brief: [Project Name]107108**Date:** [Date]109**Repository:** [URL or path]110**Explorer:** [Name]111112### Project Summary113114[What this project is, who built it, what it does, and its core philosophy in 2-3 sentences.]115116### Architecture Snapshot117118**Structure:** [High-level organization]119**Key Patterns:** [Architectural patterns used]120**Core Dependencies:** [Major external dependencies]121**Activity:** [Last commit, release cadence, contributor count]122123### Fit Assessment: [GREEN / YELLOW / RED]124125**Alignment:** [Does this support your goals?]126**Pattern Compatibility:** [Are patterns compatible?]127**Codebase Health:** [Test coverage, docs quality, consistency]128129### Resonance Map130131| Project Principle | Existing Principle | Shared Insight |132| :--- | :--- | :--- |133| [Principle] | [Your pattern] | [Connection] |134135### Recommended Entry Points1361371. **[Area 1]:** [Why start here] — Risk: Low/Med/High1382. **[Area 2]:** [Why start here] — Risk: Low/Med/High139140### Risks & Concerns141142- [Risk 1: description and mitigation]143- [Risk 2: description and mitigation]144```145146---147148## Quality Criteria149150- [ ] First impressions phase completed before architecture deep-dive151- [ ] Fit assessment uses GREEN/YELLOW/RED classification152- [ ] Resonance map connects project to existing knowledge153- [ ] Entry points ranked by approachability and impact154- [ ] Risks identified with mitigation strategies