Prompt file imported from aosanya/CodeValdSharedLib (.github/prompts/research.prompt.md). Copyright stays with the author.

Research & Documentation Gap Analysis Prompt

Name: research
Author: aosanya

Purpose

This prompt guides a structured Q&A session to explore and complete documentation for any feature or architectural component in the CodeValdSharedLib library through one question at a time, allowing for deep dives into specific topics.

🔄 MANDATORY REFACTOR WORKFLOW (ENFORCE BEFORE ANY RESEARCH SESSION)

BEFORE starting any research or writing new task documentation:

Step 1: CHECK File Size

wc -l documentation/3-SofwareDevelopment/mvp-details/{topic-file}.md

Step 2: IF >500 lines OR individual MVP-XXX.md files exist:

a. CREATE folder structure:

documentation/3-SofwareDevelopment/mvp-details/{domain-name}/
├── README.md              # Domain overview, architecture, task index (MAX 300 lines)
├── {topic-1}.md           # Topic-based grouping of related tasks (MAX 500 lines)
├── {topic-2}.md           # Topic-based grouping of related tasks (MAX 500 lines)
├── architecture/          # Optional: detailed technical designs
│   ├── flow-diagrams.md
│   ├── data-models.md
│   └── state-machines.md
└── examples/              # Optional: code samples, configs
    ├── sample-configs.yaml
    └── api-examples.md

b. CREATE README.md with:

Domain overview
Architecture summary
Task index with links

c. SPLIT content by TOPIC (NOT by task ID):

Group related tasks into topic files
Examples: webhooks.md, authentication.md, state-machines.md, instance-management.md

d. MOVE architecture diagrams → architecture/ subfolder

e. MOVE examples → examples/ subfolder

Step 3: ONLY THEN add new task content to appropriate topic file

🛑 STOP CONDITIONS (Do NOT proceed until fixed)

❌ Domain file exceeds 500 lines → MUST refactor first
❌ README.md exceeds 300 lines → MUST split content
❌ Individual MVP-XXX.md files exist → MUST consolidate by topic
❌ Task file exceeds 200 lines → MUST split into subtopics

Find Your Task's Domain

Small domains (2-4 tasks, <500 lines): Single file like authentication.md
Large domains (5+ tasks OR >500 lines): MUST use folder structure

Current Status Check Required

Before starting research, AI must:

Check current file line count
List existing files in domain
Determine if refactor is needed
Execute refactor if triggered
ONLY THEN begin research questions

Instructions for AI Assistant

Conduct a comprehensive documentation gap analysis through iterative single-question exploration. Ask ONE question at a time, wait for the response, then decide whether to:

Go Deeper: Ask follow-up questions on the same topic
Take Note: Record a gap for later exploration
Move On: Proceed to the next topic area
Review: Summarize what we've learned and identify remaining gaps

The goal is to have focused conversations that build understanding incrementally rather than overwhelming with multiple questions.

Research Framework

1. Session Initiation

When starting a research session:

State the feature/component being researched
Scan existing documentation and code quickly
Ask the first question from the most critical area
Wait for response before proceeding

2. Question Flow

After each answer, explicitly choose one of these paths:

🔍 DEEPER: "Let me dig deeper into [specific aspect]..."
- Ask follow-up question on the same topic
- Explore edge cases or implementation details
- Clarify ambiguities in the response
📝 NOTE: "I'll note this gap: [description]..."
- Record incomplete information for later
- Mark areas needing further research
- Continue to different topic
➡️ NEXT: "Moving to [new topic area]..."
- Sufficient understanding achieved
- Proceed to different question category
- Keep momentum going
📊 REVIEW: "Let me summarize what we've covered..."
- List topics explored
- Identify remaining gaps
- Decide next focus area together

3. Question Categories (Priority Order)

Architecture & Design

Start here for new features

What is the high-level architecture of this feature?
How does it integrate with existing systems?
What are the key design patterns used?
What are the data flows and dependencies?
What are the scalability considerations?

Data Models

Critical for database-backed features

What data structures are involved?
What database collections/tables are used?
What are the relationships between entities?
What indexes or optimizations are needed?
What is the data lifecycle (creation, updates, deletion)?

Business Logic

Core functionality exploration

What are the core use cases?
What are the business rules and constraints?
What are the edge cases and error scenarios?
What validation is required?
What are the state transitions (if applicable)?

API & Interfaces

For external-facing features

What endpoints/interfaces are exposed?
What are the request/response formats?
What authentication/authorization is needed?
What are the rate limits or quotas?
What error codes and messages are used?

User Experience

For UI-heavy features

What React components are involved?
What is the user workflow?
What feedback mechanisms exist?
What accessibility considerations apply?
What performance expectations exist?

Testing & Quality

For ensuring reliability

What testing strategies are used?
What are the test coverage targets?
What integration points need testing?
What are the acceptance criteria?
What monitoring/observability exists?

Operations & Deployment

For production readiness

How is this feature deployed?
What configuration is required?
What are the resource requirements?
What backup/recovery mechanisms exist?
What are the rollback procedures?

Security & Compliance

For sensitive features

What security measures are in place?
What data privacy concerns exist?
What compliance requirements apply?
What audit trails are maintained?
What encryption/protection is used?

4. Single Question Format

Structure each question clearly:

🔍 [Category: Architecture/Data/Business Logic/etc.]

**Question**: [Your specific question - keep it focused and singular]

**Context**: [1-2 sentences on why this matters or what you've observed]

**What I'm Looking For**: [Expected type of answer - e.g., "specific workflow steps", "data structure", "yes/no with rationale"]

5. Response Processing

After receiving each answer:

Acknowledge: Briefly confirm understanding
Decide Path: Choose DEEPER/NOTE/NEXT/REVIEW
State Choice Explicitly: "🔍 Going deeper..." or "📝 Noting gap..." or "➡️ Moving to..."
Ask Next Question (or provide review if chosen)

Example Flow:

AI: 🔍 [Architecture]
    Question: How does instance isolation work at runtime?
    Context: Multiple instances from same tag need separate state.
    What I'm Looking For: Specific mechanisms or data structures used.

User: [Provides answer about instance runtime tracking]

AI: ✅ Got it - using instance-scoped agent pools.
    🔍 Going deeper: How are agent identities namespaced per instance?

User: [Explains agent ID prefixing]

AI: ✅ Clear on agent namespacing.
    📝 Noting gap: Need to document collision prevention strategy.
    ➡️ Moving to lifecycle management: What triggers instance state transitions?

Gap Tracking System

Maintain a running list of gaps during the session:

Identified Gaps

📝 [Topic Area]: Brief description of what's unclear or missing
📝 [Topic Area]: Another gap found
📝 [Topic Area]: Third gap

Explored Topics

✅ [Topic Area]: Sufficient understanding achieved
✅ [Topic Area]: Documented and clear

Deep Dive Areas

🔍 [Topic Area]: Currently exploring in depth
⏸️ [Topic Area]: Paused for later (if needed)

Update this list visibly every 3-5 questions to maintain awareness of progress.

Conversation Pacing

Keep momentum while allowing depth:

⏱️ One question at a time - No multi-question lists
🎯 Stay focused - Don't switch topics mid-exploration
🔄 Iterate deliberately - Each answer informs the next question
📊 Review periodically - Every 5-7 questions, check progress
🎬 User-driven pivots - User can request topic changes anytime

Red Flags to Watch For

When exploring a topic, call out these issues immediately:

🚩 Inconsistencies: "I notice the code says X but docs say Y..."
🚩 Assumptions: "This seems to assume Z - is that documented?"
🚩 Missing Context: "Why was this approach chosen over alternatives?"
🚩 Incomplete Specs: "We know A and B, but what about C?"
🚩 Outdated Info: "The code changed but docs didn't - which is correct?"
🚩 Vague Language: "What specifically does 'handle' mean here?"

When flagged, immediately ask clarifying question before continuing.

Example Question Sequence

Session Start:

AI: We're researching Agency Instance Management (MVP-PUB-007).
    I've scanned the docs and code. Starting with critical architecture.

    🔍 [Architecture & Design]
    
    **Question**: What's the core isolation mechanism between instances 
    running from the same tag?
    
    **Context**: Multiple instances need independent runtime state while 
    sharing immutable tag configuration.
    
    **What I'm Looking For**: Specific data structures or namespacing approach.

After First Answer:

User: Each instance has unique instance_id, agents are spawned with 
      instance-scoped IDs, separate runtime tracking in lifecycle manager.

AI: ✅ Got it - isolation via instance_id namespacing and separate tracking.
    
    🔍 Going deeper into agent spawning:
    
    **Question**: How exactly are agent IDs formatted to prevent collisions 
    between instances?
    
    **Context**: Need to ensure agent-1 from instance-A doesn't conflict 
    with agent-1 from instance-B.
    
    **What I'm Looking For**: ID format pattern or generation algorithm.

After Second Answer:

User: Agents get UUIDs, not sequential IDs. Each spawn creates unique ID.

AI: ✅ Clear - UUIDs eliminate collision risk.
    📝 Noting gap: Should document UUID format in data model docs.
    
    ➡️ Moving to lifecycle management:
    
    **Question**: What triggers the transition from "starting" to "running" 
    state?
    
    **Context**: Need to understand state machine for monitoring.
    
    **What I'm Looking For**: Specific condition or health check.

Periodic Review (after 6 questions):

AI: 📊 **REVIEW - Progress Check**
    
    **Explored Topics:**
    ✅ Instance isolation mechanism (instance_id namespacing)
    ✅ Agent ID collision prevention (UUIDs)
    ✅ State transitions (starting→running→stopped)
    ✅ Data persistence (agency_instances collection)
    
    **Noted Gaps:**
    📝 UUID format documentation in data models
    📝 Error recovery when agent spawn fails
    📝 Instance cleanup on agency deletion
    
    **Remaining Areas:**
    - Multi-instance concurrency limits
    - Health monitoring implementation
    - Tag immutability enforcement
    - UI workflow details
    
    **Next Steps**: Continue with health monitoring, or dive into a gap?

Completion Criteria

The research session is complete when:

✅ All critical question categories have been explored
✅ Major architectural components are understood
✅ Data flows and state machines are clear
✅ Edge cases and error scenarios are identified
✅ No blocking gaps remain (minor gaps noted for later)
✅ User confirms readiness to conclude
✅ Documentation can be written without major unknowns

Final Deliverable:

After session completion, provide a structured summary:

# Research Summary: [Feature Name]

## Topics Explored (with confidence level)
1. **Architecture** ⭐⭐⭐⭐⭐ Fully understood
2. **Data Models** ⭐⭐⭐⭐ Well understood, minor gaps
3. **Business Logic** ⭐⭐⭐ Moderate understanding
4. **API Design** ⭐⭐⭐⭐ Well understood
5. **User Experience** ⭐⭐ Needs more research

## Key Findings
- [Bullet point of important discovery]
- [Another key finding]

## Documented Gaps (For Future Work)
1. **[Gap Category]**: Description and why it matters
2. **[Gap Category]**: Description and why it matters

## Action Items
- [ ] Document [specific aspect] in [location]
- [ ] Implement [missing feature]
- [ ] Update [existing doc] with [new information]

## Ready for Implementation?
- [Yes/No with justification]

Usage Instructions

To start a research session:

Specify the feature/component: "Let's research [feature name]"
AI scans context: Reviews docs, code, and existing knowledge
AI asks first question: Single focused question from critical area
Answer the question: Provide as much or little detail as you want
AI responds with path: DEEPER/NOTE/NEXT/REVIEW + next question
Continue dialogue: One question at a time until complete
Request review anytime: Say "review progress" to see summary
Redirect as needed: Say "switch to [topic]" to change focus
Conclude when satisfied: Say "wrap up" for final summary

Session Control Commands:

💬 "review progress" - Show gap tracking summary
💬 "switch to [topic]" - Change focus area
💬 "go deeper" - Continue current topic exploration
💬 "skip this" - Note as gap and move on
💬 "wrap up" - Conclude session with summary
💬 "start over" - Reset and begin new research thread

Best Practices

For Effective Research:

✅ Be conversational - It's okay to say "I'm not sure" or "Let me check"
✅ Ask for clarification - If question is unclear, ask AI to rephrase
✅ Provide context - Share why something works a certain way
✅ Reference code/docs - Point to specific files when helpful
✅ Admit gaps honestly - Unknown areas become research opportunities
✅ Take breaks - Use REVIEW to pause and resume later
✅ Drive the pace - Tell AI to speed up or slow down

For AI Assistant:

✅ Stay focused - One question, wait for answer, process, next question
✅ Be explicit - Always state your chosen path (DEEPER/NOTE/NEXT/REVIEW)
✅ Track visibly - Update gap list every few questions
✅ Adapt dynamically - Follow interesting threads that emerge
✅ Synthesize periodically - Connect dots between topics
✅ Respect context - Don't ask what's already clearly documented
✅ Flag inconsistencies - Call out conflicts immediately

Example Session Initiation

User: Let's research instance management for MVP-PUB-007

AI: 🔍 **Pre-Research: File Size Check**
    
    Checking documentation status...
    $ wc -l documentation/3-SofwareDevelopment/mvp-details/{topic-file}.md
    884 lines
    
    🛑 STOP CONDITION TRIGGERED: File exceeds 500 lines!
    
    **Action Required**: Refactor before research
    
    Current structure:
    - instance-management.md (884 lines) ❌ EXCEEDS LIMIT
    - state-machine.md (779 lines) ❌ EXCEEDS LIMIT
    - README.md (324 lines) ✅ OK
    - integration-testing.md (304 lines) ✅ OK
    
    **Refactor Plan**:
    1. Split instance-management.md into:
       - data-models.md (models, database schema)
       - instance-lifecycle.md (service layer, state management)
       - instance-ui.md (React components, API handlers)
       - instance-dashboard.md (dashboard components)
    
    2. Split state-machine.md into:
       - publishing-states.md (agency lifecycle states)
       - tag-system.md (tag creation, restoration)
    
    Proceeding with refactor...
    
    [After refactor completes]
    
    ✅ **Refactor Complete - Starting Research Session**
    
    🔍 **Starting Research: Agency Instance Management (MVP-PUB-007)**
    
    Quick scan shows:
    - Data models documented in data-models.md
    - Service layer in instance-lifecycle.md
    - React components in instance-ui.md
    - Dashboard components in instance-dashboard.md
    
    Starting with most critical aspect:
    
    🔍 [Architecture & Design]
    
    **Question 1**: When an instance transitions from "starting" to "running", 
    what specific criteria should be met?
    
    **Context**: The documentation defines instance states but doesn't specify 
    the exact transition triggers.
    
    **What I'm Looking For**: Should ALL agents be successfully spawned, or 
    is there a threshold (e.g., 80% of agents) that would be acceptable?

[User answers, session continues...]

Remember: This is a collaborative exploration, not an interrogation. The goal is shared understanding through focused, iterative dialogue.

# Research & Documentation Gap Analysis Prompt ## Purpose This prompt guides a structured Q&A session to explore and complete documentation for any feature or architectural component in the **CodeValdSharedLib** library through **one question at a time**, allowing for deep dives into specific topics. --- ## 🔄 MANDATORY REFACTOR WORKFLOW (ENFORCE BEFORE ANY RESEARCH SESSION) **BEFORE starting any research or writing new task documentation:** ### Step 1: CHECK File Size ```bash wc -l documentation/3-SofwareDevelopment/mvp-details/{topic-file}.md ``` ### Step 2: IF >500 lines OR individual MVP-XXX.md files exist: **a. CREATE folder structure:** ```bash documentation/3-SofwareDevelopment/mvp-details/{domain-name}/ ├── README.md # Domain overview, architecture, task index (MAX 300 lines) ├── {topic-1}.md # Topic-based grouping of related tasks (MAX 500 lines) ├── {topic-2}.md # Topic-based grouping of related tasks (MAX 500 lines) ├── architecture/ # Optional: detailed technical designs │ ├── flow-diagrams.md │ ├── data-models.md │ └── state-machines.md └── examples/ # Optional: code samples, configs ├── sample-configs.yaml └── api-examples.md ``` **b. CREATE README.md** with: - Domain overview - Architecture summary - Task index with links **c. SPLIT content by TOPIC (NOT by task ID):** - Group related tasks into topic files - Examples: `webhooks.md`, `authentication.md`, `state-machines.md`, `instance-management.md` **d. MOVE architecture diagrams** → `architecture/` subfolder **e. MOVE examples** → `examples/` subfolder ### Step 3: ONLY THEN add new task content to appropriate topic file --- ## 🛑 STOP CONDITIONS (Do NOT proceed until fixed) - ❌ **Domain file exceeds 500 lines** → **MUST refactor first** - ❌ **README.md exceeds 300 lines** → **MUST split content** - ❌ **Individual `MVP-XXX.md` files exist** → **MUST consolidate by topic** - ❌ **Task file exceeds 200 lines** → **MUST split into subtopics** ### Find Your Task's Domain - **Small domains** (2-4 tasks, <500 lines): Single file like `authentication.md` - **Large domains** (5+ tasks OR >500 lines): MUST use folder structure ### Current Status Check Required Before starting research, AI must: 1. Check current file line count 2. List existing files in domain 3. Determine if refactor is needed 4. Execute refactor if triggered 5. ONLY THEN begin research questions --- ## Instructions for AI Assistant Conduct a comprehensive documentation gap analysis through **iterative single-question exploration**. Ask ONE question at a time, wait for the response, then decide whether to: - **Go Deeper**: Ask follow-up questions on the same topic - **Take Note**: Record a gap for later exploration - **Move On**: Proceed to the next topic area - **Review**: Summarize what we've learned and identify remaining gaps The goal is to have focused conversations that build understanding incrementally rather than overwhelming with multiple questions. ## Research Framework ### 1. Session Initiation When starting a research session: 1. **State the feature/component** being researched 2. **Scan existing documentation** and code quickly 3. **Ask the first question** from the most critical area 4. **Wait for response** before proceeding ### 2. Question Flow **After each answer, explicitly choose one of these paths:** - 🔍 **DEEPER**: "Let me dig deeper into [specific aspect]..." - Ask follow-up question on the same topic - Explore edge cases or implementation details - Clarify ambiguities in the response - 📝 **NOTE**: "I'll note this gap: [description]..." - Record incomplete information for later - Mark areas needing further research - Continue to different topic - ➡️ **NEXT**: "Moving to [new topic area]..." - Sufficient understanding achieved - Proceed to different question category - Keep momentum going - 📊 **REVIEW**: "Let me summarize what we've covered..." - List topics explored - Identify remaining gaps - Decide next focus area together ### 3. Question Categories (Priority Order) #### Architecture & Design **Start here for new features** - What is the high-level architecture of this feature? - How does it integrate with existing systems? - What are the key design patterns used? - What are the data flows and dependencies? - What are the scalability considerations? #### Data Models **Critical for database-backed features** - What data structures are involved? - What database collections/tables are used? - What are the relationships between entities? - What indexes or optimizations are needed? - What is the data lifecycle (creation, updates, deletion)? #### Business Logic **Core functionality exploration** - What are the core use cases? - What are the business rules and constraints? - What are the edge cases and error scenarios? - What validation is required? - What are the state transitions (if applicable)? #### API & Interfaces **For external-facing features** - What endpoints/interfaces are exposed? - What are the request/response formats? - What authentication/authorization is needed? - What are the rate limits or quotas? - What error codes and messages are used? #### User Experience **For UI-heavy features** - What React components are involved? - What is the user workflow? - What feedback mechanisms exist? - What accessibility considerations apply? - What performance expectations exist? #### Testing & Quality **For ensuring reliability** - What testing strategies are used? - What are the test coverage targets? - What integration points need testing? - What are the acceptance criteria? - What monitoring/observability exists? #### Operations & Deployment **For production readiness** - How is this feature deployed? - What configuration is required? - What are the resource requirements? - What backup/recovery mechanisms exist? - What are the rollback procedures? #### Security & Compliance **For sensitive features** - What security measures are in place? - What data privacy concerns exist? - What compliance requirements apply? - What audit trails are maintained? - What encryption/protection is used? ### 4. Single Question Format **Structure each question clearly:** ``` 🔍 [Category: Architecture/Data/Business Logic/etc.] **Question**: [Your specific question - keep it focused and singular] **Context**: [1-2 sentences on why this matters or what you've observed] **What I'm Looking For**: [Expected type of answer - e.g., "specific workflow steps", "data structure", "yes/no with rationale"] ``` ### 5. Response Processing **After receiving each answer:** 1. **Acknowledge**: Briefly confirm understanding 2. **Decide Path**: Choose DEEPER/NOTE/NEXT/REVIEW 3. **State Choice Explicitly**: "🔍 Going deeper..." or "📝 Noting gap..." or "➡️ Moving to..." 4. **Ask Next Question** (or provide review if chosen) **Example Flow:** ``` AI: 🔍 [Architecture] Question: How does instance isolation work at runtime? Context: Multiple instances from same tag need separate state. What I'm Looking For: Specific mechanisms or data structures used. User: [Provides answer about instance runtime tracking] AI: ✅ Got it - using instance-scoped agent pools. 🔍 Going deeper: How are agent identities namespaced per instance? User: [Explains agent ID prefixing] AI: ✅ Clear on agent namespacing. 📝 Noting gap: Need to document collision prevention strategy. ➡️ Moving to lifecycle management: What triggers instance state transitions? ``` ## Gap Tracking System **Maintain a running list of gaps during the session:** ### Identified Gaps - 📝 **[Topic Area]**: Brief description of what's unclear or missing - 📝 **[Topic Area]**: Another gap found - 📝 **[Topic Area]**: Third gap ### Explored Topics - ✅ **[Topic Area]**: Sufficient understanding achieved - ✅ **[Topic Area]**: Documented and clear ### Deep Dive Areas - 🔍 **[Topic Area]**: Currently exploring in depth - ⏸️ **[Topic Area]**: Paused for later (if needed) **Update this list visibly every 3-5 questions** to maintain awareness of progress. ## Conversation Pacing **Keep momentum while allowing depth:** - ⏱️ **One question at a time** - No multi-question lists - 🎯 **Stay focused** - Don't switch topics mid-exploration - 🔄 **Iterate deliberately** - Each answer informs the next question - 📊 **Review periodically** - Every 5-7 questions, check progress - 🎬 **User-driven pivots** - User can request topic changes anytime ## Red Flags to Watch For When exploring a topic, call out these issues immediately: - 🚩 **Inconsistencies**: "I notice the code says X but docs say Y..." - 🚩 **Assumptions**: "This seems to assume Z - is that documented?" - 🚩 **Missing Context**: "Why was this approach chosen over alternatives?" - 🚩 **Incomplete Specs**: "We know A and B, but what about C?" - 🚩 **Outdated Info**: "The code changed but docs didn't - which is correct?" - 🚩 **Vague Language**: "What specifically does 'handle' mean here?" **When flagged, immediately ask clarifying question before continuing.** ## Example Question Sequence **Session Start:** ``` AI: We're researching Agency Instance Management (MVP-PUB-007). I've scanned the docs and code. Starting with critical architecture. 🔍 [Architecture & Design] **Question**: What's the core isolation mechanism between instances running from the same tag? **Context**: Multiple instances need independent runtime state while sharing immutable tag configuration. **What I'm Looking For**: Specific data structures or namespacing approach. ``` **After First Answer:** ``` User: Each instance has unique instance_id, agents are spawned with instance-scoped IDs, separate runtime tracking in lifecycle manager. AI: ✅ Got it - isolation via instance_id namespacing and separate tracking. 🔍 Going deeper into agent spawning: **Question**: How exactly are agent IDs formatted to prevent collisions between instances? **Context**: Need to ensure agent-1 from instance-A doesn't conflict with agent-1 from instance-B. **What I'm Looking For**: ID format pattern or generation algorithm. ``` **After Second Answer:** ``` User: Agents get UUIDs, not sequential IDs. Each spawn creates unique ID. AI: ✅ Clear - UUIDs eliminate collision risk. 📝 Noting gap: Should document UUID format in data model docs. ➡️ Moving to lifecycle management: **Question**: What triggers the transition from "starting" to "running" state? **Context**: Need to understand state machine for monitoring. **What I'm Looking For**: Specific condition or health check. ``` **Periodic Review (after 6 questions):** ``` AI: 📊 **REVIEW - Progress Check** **Explored Topics:** ✅ Instance isolation mechanism (instance_id namespacing) ✅ Agent ID collision prevention (UUIDs) ✅ State transitions (starting→running→stopped) ✅ Data persistence (agency_instances collection) **Noted Gaps:** 📝 UUID format documentation in data models 📝 Error recovery when agent spawn fails 📝 Instance cleanup on agency deletion **Remaining Areas:** - Multi-instance concurrency limits - Health monitoring implementation - Tag immutability enforcement - UI workflow details **Next Steps**: Continue with health monitoring, or dive into a gap? ``` ## Completion Criteria **The research session is complete when:** - ✅ All critical question categories have been explored - ✅ Major architectural components are understood - ✅ Data flows and state machines are clear - ✅ Edge cases and error scenarios are identified - ✅ No blocking gaps remain (minor gaps noted for later) - ✅ User confirms readiness to conclude - ✅ Documentation can be written without major unknowns **Final Deliverable:** After session completion, provide a structured summary: ```markdown # Research Summary: [Feature Name] ## Topics Explored (with confidence level) 1. **Architecture** ⭐⭐⭐⭐⭐ Fully understood 2. **Data Models** ⭐⭐⭐⭐ Well understood, minor gaps 3. **Business Logic** ⭐⭐⭐ Moderate understanding 4. **API Design** ⭐⭐⭐⭐ Well understood 5. **User Experience** ⭐⭐ Needs more research ## Key Findings - [Bullet point of important discovery] - [Another key finding] ## Documented Gaps (For Future Work) 1. **[Gap Category]**: Description and why it matters 2. **[Gap Category]**: Description and why it matters ## Action Items - [ ] Document [specific aspect] in [location] - [ ] Implement [missing feature] - [ ] Update [existing doc] with [new information] ## Ready for Implementation? - [Yes/No with justification] ``` ## Usage Instructions **To start a research session:** 1. **Specify the feature/component**: "Let's research [feature name]" 2. **AI scans context**: Reviews docs, code, and existing knowledge 3. **AI asks first question**: Single focused question from critical area 4. **Answer the question**: Provide as much or little detail as you want 5. **AI responds with path**: DEEPER/NOTE/NEXT/REVIEW + next question 6. **Continue dialogue**: One question at a time until complete 7. **Request review anytime**: Say "review progress" to see summary 8. **Redirect as needed**: Say "switch to [topic]" to change focus 9. **Conclude when satisfied**: Say "wrap up" for final summary **Session Control Commands:** - 💬 `"review progress"` - Show gap tracking summary - 💬 `"switch to [topic]"` - Change focus area - 💬 `"go deeper"` - Continue current topic exploration - 💬 `"skip this"` - Note as gap and move on - 💬 `"wrap up"` - Conclude session with summary - 💬 `"start over"` - Reset and begin new research thread ## Best Practices **For Effective Research:** - ✅ **Be conversational** - It's okay to say "I'm not sure" or "Let me check" - ✅ **Ask for clarification** - If question is unclear, ask AI to rephrase - ✅ **Provide context** - Share why something works a certain way - ✅ **Reference code/docs** - Point to specific files when helpful - ✅ **Admit gaps honestly** - Unknown areas become research opportunities - ✅ **Take breaks** - Use REVIEW to pause and resume later - ✅ **Drive the pace** - Tell AI to speed up or slow down **For AI Assistant:** - ✅ **Stay focused** - One question, wait for answer, process, next question - ✅ **Be explicit** - Always state your chosen path (DEEPER/NOTE/NEXT/REVIEW) - ✅ **Track visibly** - Update gap list every few questions - ✅ **Adapt dynamically** - Follow interesting threads that emerge - ✅ **Synthesize periodically** - Connect dots between topics - ✅ **Respect context** - Don't ask what's already clearly documented - ✅ **Flag inconsistencies** - Call out conflicts immediately --- ## Example Session Initiation ``` User: Let's research instance management for MVP-PUB-007 AI: 🔍 **Pre-Research: File Size Check** Checking documentation status... $ wc -l documentation/3-SofwareDevelopment/mvp-details/{topic-file}.md 884 lines 🛑 STOP CONDITION TRIGGERED: File exceeds 500 lines! **Action Required**: Refactor before research Current structure: - instance-management.md (884 lines) ❌ EXCEEDS LIMIT - state-machine.md (779 lines) ❌ EXCEEDS LIMIT - README.md (324 lines) ✅ OK - integration-testing.md (304 lines) ✅ OK **Refactor Plan**: 1. Split instance-management.md into: - data-models.md (models, database schema) - instance-lifecycle.md (service layer, state management) - instance-ui.md (React components, API handlers) - instance-dashboard.md (dashboard components) 2. Split state-machine.md into: - publishing-states.md (agency lifecycle states) - tag-system.md (tag creation, restoration) Proceeding with refactor... [After refactor completes] ✅ **Refactor Complete - Starting Research Session** 🔍 **Starting Research: Agency Instance Management (MVP-PUB-007)** Quick scan shows: - Data models documented in data-models.md - Service layer in instance-lifecycle.md - React components in instance-ui.md - Dashboard components in instance-dashboard.md Starting with most critical aspect: 🔍 [Architecture & Design] **Question 1**: When an instance transitions from "starting" to "running", what specific criteria should be met? **Context**: The documentation defines instance states but doesn't specify the exact transition triggers. **What I'm Looking For**: Should ALL agents be successfully spawned, or is there a threshold (e.g., 80% of agents) that would be acceptable? [User answers, session continues...] ``` --- **Remember**: This is a **collaborative exploration**, not an interrogation. The goal is shared understanding through focused, iterative dialogue.

{ "prompt": "# Research & Documentation Gap Analysis Prompt\n\n## Purpose\nThis prompt guides a structured Q&A session to explore and complete documentation for any feature or architectural component in the **CodeValdSharedLib** library through **one question at a time**, allowing for deep dives into specific topics.\n\n---\n\n## 🔄 MANDATORY REFACTOR WORKFLOW (ENFORCE BEFORE ANY RESEARCH SESSION)\n\n**BEFORE starting any research or writing new task documentation:**\n\n### Step 1: CHECK File Size\n```bash\nwc -l documentation/3-SofwareDevelopment/mvp-details/{topic-file}.md\n```\n\n### Step 2: IF >500 lines OR individual MVP-XXX.md files exist:\n\n**a. CREATE folder structure:**\n```bash\ndocumentation/3-SofwareDevelopment/mvp-details/{domain-name}/\n├── README.md # Domain overview, architecture, task index (MAX 300 lines)\n├── {topic-1}.md # Topic-based grouping of related tasks (MAX 500 lines)\n├── {topic-2}.md # Topic-based grouping of related tasks (MAX 500 lines)\n├── architecture/ # Optional: detailed technical designs\n│ ├── flow-diagrams.md\n│ ├── data-models.md\n│ └── state-machines.md\n└── examples/ # Optional: code samples, configs\n ├── sample-configs.yaml\n └── api-examples.md\n```\n\n**b. CREATE README.md** with:\n- Domain overview\n- Architecture summary\n- Task index with links\n\n**c. SPLIT content by TOPIC (NOT by task ID):**\n- Group related tasks into topic files\n- Examples: `webhooks.md`, `authentication.md`, `state-machines.md`, `instance-management.md`\n\n**d. MOVE architecture diagrams** → `architecture/` subfolder\n\n**e. MOVE examples** → `examples/` subfolder\n\n### Step 3: ONLY THEN add new task content to appropriate topic file\n\n---\n\n## 🛑 STOP CONDITIONS (Do NOT proceed until fixed)\n\n- ❌ **Domain file exceeds 500 lines** → **MUST refactor first**\n- ❌ **README.md exceeds 300 lines** → **MUST split content**\n- ❌ **Individual `MVP-XXX.md` files exist** → **MUST consolidate by topic**\n- ❌ **Task file exceeds 200 lines** → **MUST split into subtopics**\n\n### Find Your Task's Domain\n\n- **Small domains** (2-4 tasks, <500 lines): Single file like `authentication.md`\n- **Large domains** (5+ tasks OR >500 lines): MUST use folder structure\n\n### Current Status Check Required\n\nBefore starting research, AI must:\n1. Check current file line count\n2. List existing files in domain\n3. Determine if refactor is needed\n4. Execute refactor if triggered\n5. ONLY THEN begin research questions\n\n---\n\n## Instructions for AI Assistant\n\nConduct a comprehensive documentation gap analysis through **iterative single-question exploration**. Ask ONE question at a time, wait for the response, then decide whether to:\n- **Go Deeper**: Ask follow-up questions on the same topic\n- **Take Note**: Record a gap for later exploration\n- **Move On**: Proceed to the next topic area\n- **Review**: Summarize what we've learned and identify remaining gaps\n\nThe goal is to have focused conversations that build understanding incrementally rather than overwhelming with multiple questions.\n\n## Research Framework\n\n### 1. Session Initiation\nWhen starting a research session:\n1. **State the feature/component** being researched\n2. **Scan existing documentation** and code quickly\n3. **Ask the first question** from the most critical area\n4. **Wait for response** before proceeding\n\n### 2. Question Flow\n\n**After each answer, explicitly choose one of these paths:**\n\n- 🔍 **DEEPER**: \"Let me dig deeper into [specific aspect]...\"\n - Ask follow-up question on the same topic\n - Explore edge cases or implementation details\n - Clarify ambiguities in the response\n\n- 📝 **NOTE**: \"I'll note this gap: [description]...\"\n - Record incomplete information for later\n - Mark areas needing further research\n - Continue to different topic\n\n- ➡️ **NEXT**: \"Moving to [new topic area]...\"\n - Sufficient understanding achieved\n - Proceed to different question category\n - Keep momentum going\n\n- 📊 **REVIEW**: \"Let me summarize what we've covered...\"\n - List topics explored\n - Identify remaining gaps\n - Decide next focus area together\n\n### 3. Question Categories (Priority Order)\n\n#### Architecture & Design\n**Start here for new features**\n- What is the high-level architecture of this feature?\n- How does it integrate with existing systems?\n- What are the key design patterns used?\n- What are the data flows and dependencies?\n- What are the scalability considerations?\n\n#### Data Models\n**Critical for database-backed features**\n- What data structures are involved?\n- What database collections/tables are used?\n- What are the relationships between entities?\n- What indexes or optimizations are needed?\n- What is the data lifecycle (creation, updates, deletion)?\n\n#### Business Logic\n**Core functionality exploration**\n- What are the core use cases?\n- What are the business rules and constraints?\n- What are the edge cases and error scenarios?\n- What validation is required?\n- What are the state transitions (if applicable)?\n\n#### API & Interfaces\n**For external-facing features**\n- What endpoints/interfaces are exposed?\n- What are the request/response formats?\n- What authentication/authorization is needed?\n- What are the rate limits or quotas?\n- What error codes and messages are used?\n\n#### User Experience\n**For UI-heavy features**\n- What React components are involved?\n- What is the user workflow?\n- What feedback mechanisms exist?\n- What accessibility considerations apply?\n- What performance expectations exist?\n\n#### Testing & Quality\n**For ensuring reliability**\n- What testing strategies are used?\n- What are the test coverage targets?\n- What integration points need testing?\n- What are the acceptance criteria?\n- What monitoring/observability exists?\n\n#### Operations & Deployment\n**For production readiness**\n- How is this feature deployed?\n- What configuration is required?\n- What are the resource requirements?\n- What backup/recovery mechanisms exist?\n- What are the rollback procedures?\n\n#### Security & Compliance\n**For sensitive features**\n- What security measures are in place?\n- What data privacy concerns exist?\n- What compliance requirements apply?\n- What audit trails are maintained?\n- What encryption/protection is used?\n\n### 4. Single Question Format\n\n**Structure each question clearly:**\n\n```\n🔍 [Category: Architecture/Data/Business Logic/etc.]\n\n**Question**: [Your specific question - keep it focused and singular]\n\n**Context**: [1-2 sentences on why this matters or what you've observed]\n\n**What I'm Looking For**: [Expected type of answer - e.g., \"specific workflow steps\", \"data structure\", \"yes/no with rationale\"]\n```\n\n### 5. Response Processing\n\n**After receiving each answer:**\n\n1. **Acknowledge**: Briefly confirm understanding\n2. **Decide Path**: Choose DEEPER/NOTE/NEXT/REVIEW\n3. **State Choice Explicitly**: \"🔍 Going deeper...\" or \"📝 Noting gap...\" or \"➡️ Moving to...\"\n4. **Ask Next Question** (or provide review if chosen)\n\n**Example Flow:**\n```\nAI: 🔍 [Architecture]\n Question: How does instance isolation work at runtime?\n Context: Multiple instances from same tag need separate state.\n What I'm Looking For: Specific mechanisms or data structures used.\n\nUser: [Provides answer about instance runtime tracking]\n\nAI: ✅ Got it - using instance-scoped agent pools.\n 🔍 Going deeper: How are agent identities namespaced per instance?\n\nUser: [Explains agent ID prefixing]\n\nAI: ✅ Clear on agent namespacing.\n 📝 Noting gap: Need to document collision prevention strategy.\n ➡️ Moving to lifecycle management: What triggers instance state transitions?\n```\n\n## Gap Tracking System\n\n**Maintain a running list of gaps during the session:**\n\n### Identified Gaps\n- 📝 **[Topic Area]**: Brief description of what's unclear or missing\n- 📝 **[Topic Area]**: Another gap found\n- 📝 **[Topic Area]**: Third gap\n\n### Explored Topics\n- ✅ **[Topic Area]**: Sufficient understanding achieved\n- ✅ **[Topic Area]**: Documented and clear\n\n### Deep Dive Areas\n- 🔍 **[Topic Area]**: Currently exploring in depth\n- ⏸️ **[Topic Area]**: Paused for later (if needed)\n\n**Update this list visibly every 3-5 questions** to maintain awareness of progress.\n\n## Conversation Pacing\n\n**Keep momentum while allowing depth:**\n\n- ⏱️ **One question at a time** - No multi-question lists\n- 🎯 **Stay focused** - Don't switch topics mid-exploration\n- 🔄 **Iterate deliberately** - Each answer informs the next question\n- 📊 **Review periodically** - Every 5-7 questions, check progress\n- 🎬 **User-driven pivots** - User can request topic changes anytime\n\n## Red Flags to Watch For\n\nWhen exploring a topic, call out these issues immediately:\n\n- 🚩 **Inconsistencies**: \"I notice the code says X but docs say Y...\"\n- 🚩 **Assumptions**: \"This seems to assume Z - is that documented?\"\n- 🚩 **Missing Context**: \"Why was this approach chosen over alternatives?\"\n- 🚩 **Incomplete Specs**: \"We know A and B, but what about C?\"\n- 🚩 **Outdated Info**: \"The code changed but docs didn't - which is correct?\"\n- 🚩 **Vague Language**: \"What specifically does 'handle' mean here?\"\n\n**When flagged, immediately ask clarifying question before continuing.**\n\n## Example Question Sequence\n\n**Session Start:**\n```\nAI: We're researching Agency Instance Management (MVP-PUB-007).\n I've scanned the docs and code. Starting with critical architecture.\n\n 🔍 [Architecture & Design]\n \n **Question**: What's the core isolation mechanism between instances \n running from the same tag?\n \n **Context**: Multiple instances need independent runtime state while \n sharing immutable tag configuration.\n \n **What I'm Looking For**: Specific data structures or namespacing approach.\n```\n\n**After First Answer:**\n```\nUser: Each instance has unique instance_id, agents are spawned with \n instance-scoped IDs, separate runtime tracking in lifecycle manager.\n\nAI: ✅ Got it - isolation via instance_id namespacing and separate tracking.\n \n 🔍 Going deeper into agent spawning:\n \n **Question**: How exactly are agent IDs formatted to prevent collisions \n between instances?\n \n **Context**: Need to ensure agent-1 from instance-A doesn't conflict \n with agent-1 from instance-B.\n \n **What I'm Looking For**: ID format pattern or generation algorithm.\n```\n\n**After Second Answer:**\n```\nUser: Agents get UUIDs, not sequential IDs. Each spawn creates unique ID.\n\nAI: ✅ Clear - UUIDs eliminate collision risk.\n 📝 Noting gap: Should document UUID format in data model docs.\n \n ➡️ Moving to lifecycle management:\n \n **Question**: What triggers the transition from \"starting\" to \"running\" \n state?\n \n **Context**: Need to understand state machine for monitoring.\n \n **What I'm Looking For**: Specific condition or health check.\n```\n\n**Periodic Review (after 6 questions):**\n```\nAI: 📊 **REVIEW - Progress Check**\n \n **Explored Topics:**\n ✅ Instance isolation mechanism (instance_id namespacing)\n ✅ Agent ID collision prevention (UUIDs)\n ✅ State transitions (starting→running→stopped)\n ✅ Data persistence (agency_instances collection)\n \n **Noted Gaps:**\n 📝 UUID format documentation in data models\n 📝 Error recovery when agent spawn fails\n 📝 Instance cleanup on agency deletion\n \n **Remaining Areas:**\n - Multi-instance concurrency limits\n - Health monitoring implementation\n - Tag immutability enforcement\n - UI workflow details\n \n **Next Steps**: Continue with health monitoring, or dive into a gap?\n```\n\n## Completion Criteria\n\n**The research session is complete when:**\n\n- ✅ All critical question categories have been explored\n- ✅ Major architectural components are understood\n- ✅ Data flows and state machines are clear\n- ✅ Edge cases and error scenarios are identified\n- ✅ No blocking gaps remain (minor gaps noted for later)\n- ✅ User confirms readiness to conclude\n- ✅ Documentation can be written without major unknowns\n\n**Final Deliverable:**\n\nAfter session completion, provide a structured summary:\n\n```markdown\n# Research Summary: [Feature Name]\n\n## Topics Explored (with confidence level)\n1. **Architecture** ⭐⭐⭐⭐⭐ Fully understood\n2. **Data Models** ⭐⭐⭐⭐ Well understood, minor gaps\n3. **Business Logic** ⭐⭐⭐ Moderate understanding\n4. **API Design** ⭐⭐⭐⭐ Well understood\n5. **User Experience** ⭐⭐ Needs more research\n\n## Key Findings\n- [Bullet point of important discovery]\n- [Another key finding]\n\n## Documented Gaps (For Future Work)\n1. **[Gap Category]**: Description and why it matters\n2. **[Gap Category]**: Description and why it matters\n\n## Action Items\n- [ ] Document [specific aspect] in [location]\n- [ ] Implement [missing feature]\n- [ ] Update [existing doc] with [new information]\n\n## Ready for Implementation?\n- [Yes/No with justification]\n```\n\n## Usage Instructions\n\n**To start a research session:**\n\n1. **Specify the feature/component**: \"Let's research [feature name]\"\n2. **AI scans context**: Reviews docs, code, and existing knowledge\n3. **AI asks first question**: Single focused question from critical area\n4. **Answer the question**: Provide as much or little detail as you want\n5. **AI responds with path**: DEEPER/NOTE/NEXT/REVIEW + next question\n6. **Continue dialogue**: One question at a time until complete\n7. **Request review anytime**: Say \"review progress\" to see summary\n8. **Redirect as needed**: Say \"switch to [topic]\" to change focus\n9. **Conclude when satisfied**: Say \"wrap up\" for final summary\n\n**Session Control Commands:**\n\n- 💬 `\"review progress\"` - Show gap tracking summary\n- 💬 `\"switch to [topic]\"` - Change focus area\n- 💬 `\"go deeper\"` - Continue current topic exploration\n- 💬 `\"skip this\"` - Note as gap and move on\n- 💬 `\"wrap up\"` - Conclude session with summary\n- 💬 `\"start over\"` - Reset and begin new research thread\n\n## Best Practices\n\n**For Effective Research:**\n\n- ✅ **Be conversational** - It's okay to say \"I'm not sure\" or \"Let me check\"\n- ✅ **Ask for clarification** - If question is unclear, ask AI to rephrase\n- ✅ **Provide context** - Share why something works a certain way\n- ✅ **Reference code/docs** - Point to specific files when helpful\n- ✅ **Admit gaps honestly** - Unknown areas become research opportunities\n- ✅ **Take breaks** - Use REVIEW to pause and resume later\n- ✅ **Drive the pace** - Tell AI to speed up or slow down\n\n**For AI Assistant:**\n\n- ✅ **Stay focused** - One question, wait for answer, process, next question\n- ✅ **Be explicit** - Always state your chosen path (DEEPER/NOTE/NEXT/REVIEW)\n- ✅ **Track visibly** - Update gap list every few questions\n- ✅ **Adapt dynamically** - Follow interesting threads that emerge\n- ✅ **Synthesize periodically** - Connect dots between topics\n- ✅ **Respect context** - Don't ask what's already clearly documented\n- ✅ **Flag inconsistencies** - Call out conflicts immediately\n\n---\n\n## Example Session Initiation\n\n```\nUser: Let's research instance management for MVP-PUB-007\n\nAI: 🔍 **Pre-Research: File Size Check**\n \n Checking documentation status...\n $ wc -l documentation/3-SofwareDevelopment/mvp-details/{topic-file}.md\n 884 lines\n \n 🛑 STOP CONDITION TRIGGERED: File exceeds 500 lines!\n \n **Action Required**: Refactor before research\n \n Current structure:\n - instance-management.md (884 lines) ❌ EXCEEDS LIMIT\n - state-machine.md (779 lines) ❌ EXCEEDS LIMIT\n - README.md (324 lines) ✅ OK\n - integration-testing.md (304 lines) ✅ OK\n \n **Refactor Plan**:\n 1. Split instance-management.md into:\n - data-models.md (models, database schema)\n - instance-lifecycle.md (service layer, state management)\n - instance-ui.md (React components, API handlers)\n - instance-dashboard.md (dashboard components)\n \n 2. Split state-machine.md into:\n - publishing-states.md (agency lifecycle states)\n - tag-system.md (tag creation, restoration)\n \n Proceeding with refactor...\n \n [After refactor completes]\n \n ✅ **Refactor Complete - Starting Research Session**\n \n 🔍 **Starting Research: Agency Instance Management (MVP-PUB-007)**\n \n Quick scan shows:\n - Data models documented in data-models.md\n - Service layer in instance-lifecycle.md\n - React components in instance-ui.md\n - Dashboard components in instance-dashboard.md\n \n Starting with most critical aspect:\n \n 🔍 [Architecture & Design]\n \n **Question 1**: When an instance transitions from \"starting\" to \"running\", \n what specific criteria should be met?\n \n **Context**: The documentation defines instance states but doesn't specify \n the exact transition triggers.\n \n **What I'm Looking For**: Should ALL agents be successfully spawned, or \n is there a threshold (e.g., 80% of agents) that would be acceptable?\n\n[User answers, session continues...]\n```\n\n---\n\n**Remember**: This is a **collaborative exploration**, not an interrogation. The goal is shared understanding through focused, iterative dialogue.", "variables": [], "notes": "Before starting research, AI must: 1. Check current file line count 2. List existing files in domain 3. Determine if refactor is needed 4. Execute refactor if triggered 5. ONLY THEN begin research questions", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/aosanya/CodeValdSharedLib", "path": ".github/prompts/research.prompt.md", "ref": "d4d37e20bdb022c49dfa85a3eb495801fd9591de", "url": "https://github.com/aosanya/CodeValdSharedLib/blob/d4d37e20bdb022c49dfa85a3eb495801fd9591de/.github/prompts/research.prompt.md", "key": "aosanya/CodeValdSharedLib/.github/prompts/research.prompt.md" } } }

research

About