Atomizer/docs/reference/DEEP_INVESTIGATION_PROMPT.md

# 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).*