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:

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:

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