Universal Context Document (UCD) Generator

# Optimized Universal Context Document Generator Prompt

## Role/Persona
Act as a **Senior Technical Documentation Architect and Knowledge Transfer Specialist** with deep expertise in:
- AI-assisted software development and multi-agent collaboration
- Cross-platform AI context preservation and portability
- Agile methodologies and incremental delivery frameworks
- Technical writing for developer audiences
- Cybersecurity domain knowledge (relevant to user's background)

## Task/Action
Generate a comprehensive, **platform-agnostic Universal Context Document (UCD)** that captures the complete conversational history, technical decisions, and project state between the user and any AI system. This document must function as a **zero-information-loss knowledge transfer artifact** that enables seamless conversation continuation across different AI platforms (ChatGPT, Claude, Gemini, etc.) days or weeks later.

## Context: The Problem This Solves

**Challenge:** During extended brainstorming (in AI/LLM chat interfaces), coding sessions (IDE interfaces), and development sessions (5+ hours), valuable context accumulates through iterative dialogue, file changes (add, update, documenting, logging, refactoring, remove, debugging, testing, deploying), ideas evolve, decisions are made, and next steps are identified. However, when the user takes a break and returns later, this context is lost, requiring time-consuming re-establishment of background information.

**Solution:** The UCD acts as a "save state" for AI conversations, similar to version control for code. It must be:
- **Complete:** Captures ALL relevant context, decisions, and nuances
- **Portable:** Works across any AI platform without modification
- **Actionable:** Contains clear next steps for immediate continuation
- **Versioned:** Tracks progression across multiple sessions with metadata

**Domain Focus:** Primarily tech/IT/computer-related topics, with emphasis on software development, system architecture, and cybersecurity applications.

**Version Control Requirements:** Each UCD iteration must include:
- Version number (v1, v2, v3...)
- AI model used (chatgpt-4, claude-sonnet-4-5, gemini-pro, etc.)
- Generation date
- Format: `v[N]|[model]|[YYYY-MM-DD]`
- Example: `v3|claude-sonnet-4-5|2026-01-16`

## Critical Rules/Constraints

### 1. Completeness Over Brevity
- **No detail is too small.** Include conversational nuances, terminology definitions, rejected approaches, and the reasoning behind every decision.
- **Capture implicit knowledge:** Things the user assumes you know but hasn't explicitly stated.
- **Document the "why":** Every technical choice should include its rationale.

### 2. Platform Portability
- **AI-agnostic language:** Avoid phrases like "as we discussed earlier," "you mentioned," or "our conversation." 
- **Use declarative statements:** Write "User prefers X because Y" instead of "You prefer X."
- **No platform-specific features:** Don't reference capabilities unique to one AI (e.g., "upload this to ChatGPT memory").

### 3. Technical Precision
- **Use established terminology** from the conversation consistently.
- **Define acronyms and jargon** on first use.
- **Include relevant technical specifications:** Versions, configurations, environment details.
- **Reference external resources:** Documentation links, GitHub repos, API endpoints.

### 4. Structural Clarity
- **Hierarchical organization:** Use markdown headers (##, ###, ####) for easy parsing.
- **Consistent formatting:** Code blocks, bullet points, and numbered lists where appropriate.
- **Cross-referencing:** Link related sections within the document.

### 5. Actionability
- **Explicit "Next Steps":** Immediate actions required to continue work.
- **"Pending Decisions":** Open questions requiring user input.
- **"Context for Continuation":** What the next AI needs to know to pick up seamlessly.

### 6. Temporal Awareness
- **Timestamp key decisions** when relevant to project timeline.
- **Mark deprecated information:** If a decision was reversed, note both the original and current approach.
- **Distinguish between "now" and "future":** Clearly separate current phase work from deferred features.

## Output Format Structure

```markdown
# Universal Context Document: [Project Name]
**Version:** v[N]|[AI-model]|[YYYY-MM-DD]  
**Previous Version:** v[N-1]|[AI-model]|[YYYY-MM-DD] (if applicable)  
**Session Duration:** [Start time] - [End time]  
**Total Conversational Exchanges:** [Number]

---

## 1. Executive Summary
   ### 1.1 Project Vision and End Goal
   ### 1.2 Current Phase and Immediate Objectives
   ### 1.3 Key Accomplishments This Session
   ### 1.4 Critical Decisions Made

## 2. Project Overview
   ### 2.1 Vision and Mission Statement
   ### 2.2 Success Criteria and Measurable Outcomes
   ### 2.3 Timeline and Milestones
   ### 2.4 Stakeholders and Audience

## 3. Established Rules and Agreements
   ### 3.1 Development Methodology
   - Agile/Incremental/Waterfall approach
   - Sprint duration and review cycles
   - Definition of "done"
   
   ### 3.2 Technology Stack Decisions
   - **Backend:** Framework, language, version, rationale
   - **Frontend:** Framework, libraries, progressive enhancement strategy
   - **Database:** Type, schema approach, migration strategy
   - **Infrastructure:** Hosting, CI/CD, deployment pipeline
   
   ### 3.3 AI Agent Orchestration Framework
   - Agent roles and responsibilities
   - Collaboration protocols
   - Escalation paths for conflicts
   
   ### 3.4 Code Quality and Review Standards
   - Linting rules
   - Testing requirements (unit, integration, e2e)
   - Documentation standards
   - Version control conventions

## 4. Detailed Feature Context: [Current Feature Name]
   ### 4.1 Feature Description and User Stories
   ### 4.2 Technical Requirements (Functional and Non-Functional)
   ### 4.3 Architecture and Design Decisions
   - Component breakdown
   - Data flow diagrams (described textually)
   - API contracts
   
   ### 4.4 Implementation Status
   - Completed components
   - In-progress work
   - Blocked items
   
   ### 4.5 Testing Strategy
   ### 4.6 Deployment Plan
   ### 4.7 Known Issues and Technical Debt

## 5. Conversation Journey: Decision History
   ### 5.1 Timeline of Key Discussions
   - Chronological log of major topics and decisions
   
   ### 5.2 Terminology Evolution
   - Original terms → Refined terms → Final agreed-upon terminology
   
   ### 5.3 Rejected Approaches and Why
   - Document what DOESN'T work or wasn't chosen
   - Include specific reasons for rejection
   
   ### 5.4 Architectural Tensions and Trade-offs
   - Competing concerns
   - How conflicts were resolved
   - Compromise solutions

## 6. Next Steps and Pending Actions
   ### 6.1 Immediate Tasks (Next Session)
   - Prioritized list with acceptance criteria
   
   ### 6.2 Research Questions to Answer
   - Technical investigations needed
   - Performance benchmarks to run
   - External resources to consult
   
   ### 6.3 Information Required from User
   - Clarifications needed
   - Preferences to establish
   - Examples or samples to provide
   
   ### 6.4 Dependencies and Blockers
   - External factors affecting progress
   - Required tools or access

## 7. User Communication and Working Style
   ### 7.1 Preferred Communication Style
   - Verbosity level
   - Technical depth
   - Question asking preferences
   
   ### 7.2 Learning and Explanation Preferences
   - Analogies that resonate
   - Concepts that require extra explanation
   - Prior knowledge assumptions
   
   ### 7.3 Documentation Style Guide
   - Formatting preferences
   - Code comment expectations
   - README structure
   
   ### 7.4 Feedback and Iteration Approach
   - How user provides feedback
   - Revision cycle preferences

## 8. Technical Architecture Reference
   ### 8.1 System Architecture Diagram (Textual Description)
   ### 8.2 Backend Configuration
   - Framework setup
   - Environment variables
   - Database connection details
   - API structure
   
   ### 8.3 Frontend Architecture
   - Component hierarchy
   - State management approach
   - Routing configuration
   - Build and bundle process
   
   ### 8.4 CI/CD Pipeline
   - Build steps
   - Test automation
   - Deployment triggers
   - Environment configuration
   
   ### 8.5 Third-Party Integrations
   - APIs and services used
   - Authentication methods
   - Rate limits and quotas

## 9. Tools, Resources, and References
   ### 9.1 Development Environment
   - IDEs and editors
   - Local setup requirements
   - Development dependencies
   
   ### 9.2 AI Assistants and Their Roles
   - Which AI handles which tasks
   - Specialized agent configurations
   - Collaboration workflow
   
   ### 9.3 Documentation Platforms
   - Where docs are stored
   - Versioning strategy
   - Access and sharing
   
   ### 9.4 Version Control Strategy
   - Branching model
   - Commit message conventions
   - PR review process
   
   ### 9.5 External Resources
   - Documentation links
   - Tutorial references
   - Community resources
   - Relevant GitHub repositories

## 10. Open Questions and Ambiguities
   ### 10.1 Technical Uncertainties
   - Approaches under investigation
   - Performance concerns
   - Scalability questions
   
   ### 10.2 Design Decisions Pending
   - UX/UI choices not finalized
   - Feature scope clarifications
   
   ### 10.3 Alternative Approaches Under Consideration
   - Options being evaluated
   - Pros/cons analysis in progress

## 11. Glossary and Terminology
   ### 11.1 Project-Specific Terms
   - Custom vocabulary defined
   
   ### 11.2 Technical Acronyms
   - Expanded definitions
   
   ### 11.3 Established Metaphors and Analogies
   - Conceptual frameworks used in discussion

## 12. Continuation Instructions for AI Assistants
   ### 12.1 How to Use This Document
   - Read sections 1, 2, 6 first for quick context
   - Reference section 4 for current feature details
   - Consult section 5 to understand decision rationale
   
   ### 12.2 Key Context for Maintaining Conversation Flow
   - User's level of expertise
   - Topics that require sensitivity
   - Areas where user needs more explanation
   
   ### 12.3 Immediate Action Upon Ingesting This Document
   - Confirm understanding of current phase
   - Ask for any updates since last session
   - Propose next concrete step
   
   ### 12.4 Red Flags and Warnings
   - Approaches to avoid
   - Known pitfalls in this project
   - User's pain points from previous experiences

## 13. Meta: About This Document
   ### 13.1 Document Generation Context
   - When and why this UCD was created
   - Conversation exchanges captured
   
   ### 13.2 Next UCD Update Trigger
   - Conditions for generating v[N+1]
   - Typically every 10 exchanges or before long breaks
   
   ### 13.3 Document Maintenance
   - How to update vs. create new version
   - Archival strategy for old versions

---

## Appendices (If Applicable)

### Appendix A: Code Snippets
- Key code examples discussed
- Configuration files

### Appendix B: Data Schemas
- Database models
- API response formats

### Appendix C: UI Mockups (Textual Descriptions)
- Interface layouts described in detail

### Appendix D: Meeting Notes or External Research
- Relevant information gathered outside the conversation
```

---

## Concrete Example: Expected Level of Detail

### ❌ Insufficient Detail (Avoid This)
```
**Technology Stack:**
- Backend: Django
- Frontend: React
- Hosting: GitHub Pages
```

### ✅ Comprehensive Detail (Aim for This)
```
**Backend Framework: Django (v4.2)**

**Rationale:**  
User (Joem Bolinas, BSIT Cybersecurity student) selected Django for:
1. **Robust ORM:** Simplifies database interactions, critical for the Learning Journey feature's content management
2. **Built-in Admin Interface:** Allows quick content CRUD without building custom CMS
3. **Python Ecosystem:** Aligns with user's cybersecurity background (Python-heavy field) and enables integration with ML/data processing libraries for future features

**Architectural Tension:**  
Django is traditionally a server-side framework (requires a running web server), but user wants to deploy frontend to GitHub Pages, which only supports static hosting (HTML/CSS/JS files, no backend processing).

**Resolution Strategies Under Consideration:**
1. **Django as Static Site Generator:** Configure Django to export pre-rendered HTML files that can be deployed to GitHub Pages. Backend would run only during build time, not runtime.
   - **Pros:** Simple deployment, no server costs, fast performance
   - **Cons:** Dynamic features limited, rebuild required for content updates
   
2. **Decoupled Architecture:** Deploy Django REST API to a free tier cloud service (Render, Railway, PythonAnywhere) while keeping React frontend on GitHub Pages.
   - **Pros:** Fully dynamic, real-time content updates, enables future features like user accounts
   - **Cons:** Added complexity, potential latency, free tier limitations

**Current Status:** Pending research and experimentation. User needs to:
- Test Django's `distill` or `freeze` packages for static generation
- Evaluate free tier API hosting services for reliability
- Prototype both architectures with Learning Journey feature

**Decision Deadline:** Must be finalized before Phase 1 implementation begins (target: end of current week).

**User's Explicit Constraint:** Avoid premature optimization. User cited past experience where introducing React too early created complexity that slowed development. Preference is to start with Django template rendering + vanilla JS, migrate to React only when complexity justifies it.

**Future Implications:**  
If static generation is chosen, future features requiring real-time interactivity (e.g., commenting system, user dashboards) will necessitate architecture migration. This should be explicitly documented in the roadmap.
```

---

## Additional Guidance for Document Generation

### 1. Capture the User's Voice
- Use direct quotes when they clarify intent (e.g., "I want this to be like building a house—lay the foundation before adding walls")
- Note recurring phrases or metaphors that reveal thinking patterns
- Identify areas where user shows strong opinions vs. flexibility

### 2. Document the Invisible
- **Assumptions:** What does the user assume you know?
- **Domain Knowledge:** Industry-specific practices they follow without stating
- **Risk Tolerance:** Are they conservative or experimental with new tech?
- **Time Constraints:** Academic deadlines, part-time availability, etc.

### 3. Make It Scannable
- **TL;DR summaries** at the top of long sections
- **Status indicators:** ✅ Decided, 🔄 In Progress, ⏸️ Blocked, ❓ Pending
- **Bold key terms** for easy visual scanning
- **Color-coded priorities** if the platform supports it (High/Medium/Low)

### 4. Test for Portability
Ask yourself: "Could a completely different AI read this and continue the conversation without ANY additional context?" If no, add more detail.

### 5. Version History Management
When updating an existing UCD to create v[N+1]:
- **Section 1.3:** Highlight what changed since v[N]
- **Mark deprecated sections:** Strike through or note "SUPERSEDED - See Section X.X"
- **Link to previous version:** Include filename or storage location of v[N]

### 6. Handling Sensitive Information
- **Redact credentials:** Never include API keys, passwords, or tokens
- **Sanitize personal data:** Anonymize if necessary while preserving context
- **Note omissions:** If something was discussed but can't be included, note "Details omitted for security - user has separate secure record"

---

## Success Criteria for a High-Quality UCD

A well-crafted Universal Context Document should enable:

1. ✅ **Zero-friction continuation:** Next AI can resume the conversation as if no break occurred
2. ✅ **Platform switching:** User can move from ChatGPT → Claude → Gemini without re-explaining
3. ✅ **Long-term reference:** Document remains useful weeks or months later
4. ✅ **Team collaboration:** Could be shared with a human collaborator who'd understand the project
5. ✅ **Self-sufficiency:** User can read it themselves to remember where they left off
6. ✅ **Decision auditability:** Anyone can understand WHY choices were made, not just WHAT was decided

---

## Usage Instructions

**For AI Generating the UCD:**
1. Read the ENTIRE conversation history before writing
2. Prioritize the most recent 20% of exchanges (recency bias is appropriate)
3. When uncertain about a detail, mark it with `[VERIFY WITH USER]`
4. If the conversation covered multiple topics, create separate UCDs or clearly delineate topics with section boundaries
5. Generate the document, then self-review: "Would I be able to continue this conversation seamlessly if given only this document?"

**For User Receiving the UCD:**
1. Review the "Executive Summary" and "Next Steps" sections first
2. Skim section headers to verify completeness
3. Flag any misunderstandings or missing context
4. Request revisions before marking the UCD as "finalized"
5. Store versioned copies in a consistent location (e.g., `/docs/ucd/` in your project repo)

**For Next AI Reading the UCD:**
1. Start with Section 1 (Executive Summary) and Section 6 (Next Steps)
2. Read Section 12 (Continuation Instructions) carefully
3. Acknowledge your understanding: "I've reviewed the UCD v[N]. I understand we're currently [current phase], and the immediate goal is [next step]. Ready to continue—shall we [specific action]?"
4. Ask for updates: "Has anything changed since this UCD was generated on [date]?"

---

## Request to User (After Document Generation)

After generating your UCD, please review it and provide:
- ✅ Confirmation that all critical context is captured
- 🔄 Corrections for any misunderstandings
- ➕ Additional details or nuances to include
- 🎯 Feedback on structure and usability

This ensures the UCD genuinely serves its purpose as a knowledge transfer artifact.