From project-docs
Pre-planning technical discovery for complex features. Orchestrates explorers to gather codebase context, validates architecture docs, and prepares comprehensive input for the dev-plan-generator. Use when the user has a proposal or feature idea that needs codebase analysis before planning — maps existing patterns, validates assumptions, and surfaces constraints. Triggers when user says "explore the codebase for this feature", "do technical discovery", "what does the codebase look like for this", "analyze the code before we plan", or wants pre-planning research documented as a discovery artifact.
How this skill is triggered — by the user, by Claude, or both
Slash command
/project-docs:dev-discoveryThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A methodology for gathering comprehensive technical context before creating a
A methodology for gathering comprehensive technical context before creating a development plan. Use this when starting work on complex features to avoid blind spots and ensure the dev-plan-generator has complete information.
Use this skill when:
Key indicator: Any feature that would benefit from the "Architecture
Discovery Before Implementation" methodology in docs/lessons-learned/.
Proposal/Feature Idea
↓
[Dev Discovery] ← YOU orchestrate this
↓
┌─────┴─────┐
↓ ↓
Explorers Architecture
(parallel) Doc Check
↓ ↓
└─────┬─────┘
↓
Discovery Output
(project artifact)
↓
Dev Plan Generator
(with full context)
Read the proposal and identify:
Create a list of exploration targets based on this analysis.
For each affected system, check docs/architecture/ for relevant docs:
ls docs/architecture/
For each affected area, ask:
If an architecture doc is missing and needed:
If an architecture doc exists but is stale:
Launch multiple Explore agents in parallel to gather context. Be specific about what each explorer should find.
Example exploration prompts:
"Explore how document export currently works in the desktop app.
Find: export-related files, the export flow, what format is used,
where exports are saved. Focus on src/renderer/ and src/main/."
"Explore the context menu system in the desktop app.
Find: how context menus are registered, where menu items are defined,
how menu actions are handled. Map the pattern we should follow."
"Explore how the mobile app handles file operations.
Find: file picker usage, save operations, any existing import/export."
Explorer assignment strategy:
Thoroughness level: Use "very thorough" for critical paths, "medium" for supporting areas.
Once explorers return, synthesize their findings into a discovery document.
Write to project artifacts:
docs/projects/<project>/artifacts/<feature-name>-discovery.md
The <project> name comes from the proposal path (e.g.,
docs/projects/operator-hub-export-import/proposal.md →
operator-hub-export-import).
Create the artifacts folder if needed:
mkdir -p docs/projects/<project>/artifacts
This file captures:
Now invoke the dev-plan-generator with:
The planner now has complete context and can focus on what to build rather than understanding the codebase.
Save to docs/projects/<project>/artifacts/<feature-name>-discovery.md:
# Technical Discovery: [Feature Name]
**Date:** YYYY-MM-DD **Proposal:** [link or reference]
## Affected Systems
### Desktop
- [ ] Main process
- [ ] Preload
- [ ] Renderer
- Key areas: [list]
### Mobile
- [ ] Affected
- Key areas: [list]
### API
- [ ] Affected
- Key areas: [list]
### Shared Packages
- [ ] @operator/shared
- [ ] @operator/database
- Key areas: [list]
## Architecture Documentation Status
| System | Doc Exists | Current | Action Needed |
| ---------- | ---------- | ------- | ------------------ |
| [System 1] | Yes/No | Yes/No | None/Create/Update |
| [System 2] | Yes/No | Yes/No | None/Create/Update |
## Explorer Findings
### [Area 1]: [Summary]
**Key Files:**
- `path/to/file.ts` - Purpose
- `path/to/other.ts` - Purpose
**Current Pattern:** [How this area currently works]
**Integration Points:**
- Connects to X via Y
- Exposes Z to A
**Relevant Code:**
```typescript
// Key snippet showing the pattern
```
[Same structure...]
[ASCII diagram showing how components connect]
## Artifact Storage
Discovery files are stored alongside the project they support:
docs/projects//artifacts/ -discovery.md context-menu-exploration.md dependency-analysis.md
**Benefits:**
- Co-located with the project — proposal, plan, and research live together
- Committed to the repo — survives branch merges and available for reference
- Discoverable — anyone can find the research that informed the plan
- Multiple artifacts per project if needed
**Lifecycle:**
- Created during dev-discovery
- Used during planning and early development
- Referenced throughout the feature work
- Archived with the project when complete
## Quality Checklist
Before handing off to the planner:
- [ ] All affected systems identified
- [ ] Architecture docs checked (created if missing and needed)
- [ ] Explorers covered all major areas
- [ ] Key files and patterns documented
- [ ] Integration points mapped
- [ ] Open questions listed
- [ ] Discovery file written
## Example Usage
**User:** "Let's implement the Operator Hub export/import feature from the proposal"
**You (using this skill):**
1. Read the proposal, identify: Desktop context menu, file system operations, JSON serialization, folder/document traversal
2. Check architecture docs:
- `desktop-file-operations.md` - exists, current
- `context-menu-system.md` - doesn't exist, should create
3. Spawn explorers:
- Explorer 1: "Desktop context menu registration and handling"
- Explorer 2: "Document/folder traversal and serialization patterns"
- Explorer 3: "File save/open dialogs in Electron"
4. Create architecture doc for context menu system
5. Write discovery to `docs/projects/operator-hub-export-import/artifacts/discovery.md`
6. Call dev-plan-generator with proposal + discovery file
## Relationship to Other Tools
- **Explore agent**: This skill orchestrates multiple Explore agents
- **dev-plan-generator**: This skill prepares input for the planner
- **Architecture docs**: This skill validates and creates these as needed
- **Lessons learned**: This skill implements the "Architecture Discovery Before Implementation" methodology
npx claudepluginhub ichabodcole/project-docs-scaffold-template --plugin project-docsAutonomously researches feature requests or architecture documents, explores codebase patterns, identifies ambiguities and gaps, produces feature-context.md for orchestrator without making technical decisions.
Plans and architects new features: analyzes requirements, asks clarifying questions, creates detailed implementation plans aligned with project architecture. Use before coding.
Read-only codebase exploration and implementation plan design. Use before coding to understand architecture, find patterns, and produce step-by-step strategies.