docs: Major documentation overhaul - restructure folders, update tagline, add Getting Started guide
- Restructure docs/ folder (remove numeric prefixes): - 04_USER_GUIDES -> guides/ - 05_API_REFERENCE -> api/ - 06_PHYSICS -> physics/ - 07_DEVELOPMENT -> development/ - 08_ARCHIVE -> archive/ - 09_DIAGRAMS -> diagrams/ - Replace tagline 'Talk, don't click' with 'LLM-driven optimization framework' in 9 files - Create comprehensive docs/GETTING_STARTED.md: - Prerequisites and quick setup - Project structure overview - First study tutorial (Claude or manual) - Dashboard usage guide - Neural acceleration introduction - Rewrite docs/00_INDEX.md with correct paths and modern structure - Archive obsolete files: - 01_PROTOCOLS.md -> archive/historical/01_PROTOCOLS_legacy.md - 03_GETTING_STARTED.md -> archive/historical/ - ATOMIZER_PODCAST_BRIEFING.md -> archive/marketing/ - Update timestamps to 2026-01-20 across all key files - Update .gitignore to exclude docs/generated/ - Version bump: ATOMIZER_CONTEXT v1.8 -> v2.0
This commit is contained in:
197
docs/reference/DEEP_INVESTIGATION_PROMPT.md
Normal file
197
docs/reference/DEEP_INVESTIGATION_PROMPT.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Deep Investigation & Architecture Analysis Prompt
|
||||
|
||||
**Purpose**: Reusable instructions for conducting thorough system investigations and producing actionable design documents.
|
||||
|
||||
---
|
||||
|
||||
## Full Investigation Prompt
|
||||
|
||||
Use this when you need a comprehensive analysis of a system, architecture, or problem:
|
||||
|
||||
```markdown
|
||||
Please conduct a comprehensive investigation and produce a master design document.
|
||||
|
||||
### Investigation Phase
|
||||
|
||||
1. **Multi-Agent Exploration**: Launch parallel exploration agents to examine:
|
||||
- Frontend components and state management
|
||||
- Backend services, routes, and data flow
|
||||
- Core engine/library code and schemas
|
||||
- Configuration files and existing patterns
|
||||
- Any MCP tools, APIs, or integration points
|
||||
|
||||
2. **Source of Truth Analysis**: Identify ALL places where the same concept is represented:
|
||||
- Data schemas/types (JSON, TypeScript, Python)
|
||||
- Configuration formats and their variants
|
||||
- State management across components
|
||||
- Document inconsistencies and naming conflicts
|
||||
|
||||
3. **Data Flow Mapping**: Trace how data moves through the system:
|
||||
- Entry points → Processing → Storage → Display
|
||||
- Identify lossy conversions and sync gaps
|
||||
- Note missing endpoints or broken connections
|
||||
|
||||
### Documentation Phase
|
||||
|
||||
4. **Current State Report**: Document what exists with:
|
||||
- Architecture diagrams (text-based)
|
||||
- Comparison tables showing format inconsistencies
|
||||
- Data flow diagrams showing where information is lost
|
||||
- Clear "What's Wrong / What's OK" assessment
|
||||
|
||||
5. **Problem Statement**: Articulate:
|
||||
- Core issues with severity ratings
|
||||
- User pain points with concrete scenarios
|
||||
- Technical debt and architectural gaps
|
||||
|
||||
### Design Phase
|
||||
|
||||
6. **Proposed Architecture**: Design the solution with:
|
||||
- Single source of truth principle
|
||||
- Complete schema definition (JSON Schema if applicable)
|
||||
- Component responsibilities and interfaces
|
||||
- API/endpoint specifications
|
||||
- Real-time sync strategy if needed
|
||||
|
||||
7. **Integration Design**: Show how components connect:
|
||||
- Frontend ↔ Backend ↔ Engine data contracts
|
||||
- Bidirectional sync mechanisms
|
||||
- AI/Assistant integration points
|
||||
- Extensibility patterns (plugins, custom functions)
|
||||
|
||||
### Planning Phase
|
||||
|
||||
8. **Implementation Roadmap**: Break into phases with:
|
||||
- Clear deliverables per phase
|
||||
- Priority (P0/P1/P2) and effort estimates
|
||||
- Dependencies between tasks
|
||||
- Migration strategy for existing data
|
||||
|
||||
9. **Appendices**: Include:
|
||||
- Glossary of terms
|
||||
- File location references
|
||||
- Comparison tables (before/after)
|
||||
- Code examples for key components
|
||||
|
||||
### Output Format
|
||||
|
||||
Produce:
|
||||
1. **Master Document** (Markdown): Complete design document with all sections
|
||||
2. **Schema Files**: Actual JSON Schema or type definitions ready to use
|
||||
3. **Executive Summary**: Key findings, what's broken, proposed solution, timeline
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- Read actual source files, don't assume
|
||||
- Use tables for comparisons (makes inconsistencies obvious)
|
||||
- Include text-based diagrams for architecture and data flow
|
||||
- Provide concrete code examples, not just descriptions
|
||||
- Make it actionable: someone should be able to implement from this document
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Version
|
||||
|
||||
For faster investigations or when you already have context:
|
||||
|
||||
```markdown
|
||||
Deep investigation with master document output:
|
||||
|
||||
1. **Explore**: Parallel agents examine frontend, backend, engine, schemas
|
||||
2. **Map**: Trace data flow, identify all representations of same concept
|
||||
3. **Compare**: Tables showing format inconsistencies and naming conflicts
|
||||
4. **Diagram**: Architecture and data flow (text-based)
|
||||
5. **Assess**: What's wrong (severity) / What's OK / User pain points
|
||||
6. **Design**: Single source of truth, complete schema, API specs
|
||||
7. **Plan**: Phased roadmap with priorities and effort estimates
|
||||
8. **Deliver**: Master document + actual schema files + executive summary
|
||||
|
||||
Standards: Read actual code, use comparison tables, include diagrams, make it actionable.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Trigger Phrases
|
||||
|
||||
Use these phrases to invoke deep analysis behavior:
|
||||
|
||||
| Phrase | Effect |
|
||||
|--------|--------|
|
||||
| "Make a very deep and thoughtful research on..." | Triggers comprehensive multi-agent exploration |
|
||||
| "Produce a master document that will lead to implementation" | Ensures actionable output with roadmap |
|
||||
| "Investigate with multi-agent exploration" | Parallel exploration of different system areas |
|
||||
| "Map all representations and identify inconsistencies" | Source of truth analysis with comparison tables |
|
||||
| "Design a single source of truth architecture" | Unified schema/format design |
|
||||
| "Include comparison tables and data flow diagrams" | Visual documentation requirements |
|
||||
| "Make it actionable with implementation roadmap" | Phased planning with priorities |
|
||||
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
### For Architecture Overhaul
|
||||
```
|
||||
Please conduct a deep investigation on how [Component A] and [Component B]
|
||||
share data. I need a master document that:
|
||||
- Maps all data representations across the system
|
||||
- Identifies inconsistencies with comparison tables
|
||||
- Proposes a unified architecture
|
||||
- Includes implementation roadmap
|
||||
|
||||
Make it actionable - someone should be able to implement from this document.
|
||||
```
|
||||
|
||||
### For Problem Diagnosis
|
||||
```
|
||||
Deep investigation needed: [describe the problem]
|
||||
|
||||
Explore the codebase to understand:
|
||||
- Where this data/logic currently lives
|
||||
- How it flows through the system
|
||||
- What's broken and why
|
||||
|
||||
Produce a report with:
|
||||
- Root cause analysis
|
||||
- Data flow diagrams
|
||||
- Proposed fix with implementation steps
|
||||
```
|
||||
|
||||
### For New Feature Design
|
||||
```
|
||||
I want to add [feature]. Before implementing, conduct a deep analysis:
|
||||
|
||||
1. How does similar functionality work in the codebase?
|
||||
2. What components would be affected?
|
||||
3. What's the cleanest integration approach?
|
||||
|
||||
Produce a design document with architecture, API specs, and phased roadmap.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Checklist
|
||||
|
||||
A good deep investigation should produce:
|
||||
|
||||
- [ ] **Architecture diagram** (text-based, showing component relationships)
|
||||
- [ ] **Data flow diagram** (showing how data moves, where it's transformed)
|
||||
- [ ] **Comparison tables** (format inconsistencies, naming conflicts)
|
||||
- [ ] **Problem severity matrix** (Critical/High/Medium/Low ratings)
|
||||
- [ ] **User pain points** (concrete scenarios, not abstract)
|
||||
- [ ] **Proposed schema/types** (actual JSON Schema or TypeScript)
|
||||
- [ ] **API specifications** (endpoints, request/response formats)
|
||||
- [ ] **Implementation roadmap** (phased, with effort estimates)
|
||||
- [ ] **Migration strategy** (for existing data/code)
|
||||
- [ ] **Code examples** (for key components)
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- Example output: `docs/plans/UNIFIED_CONFIGURATION_ARCHITECTURE.md`
|
||||
- Example schema: `optimization_engine/schemas/atomizer_spec_v2.json`
|
||||
|
||||
---
|
||||
|
||||
*This prompt template was developed during the Atomizer Unified Configuration Architecture investigation (January 2026).*
|
||||
Reference in New Issue
Block a user