Handoff template/ use it when you're running out of context
# Persisted Information Handoff Prompt Template
This is an ultra-thorough prompt template for creating `persisted_information.md` files when approaching context limits. Copy this structure and fill in all sections comprehensively.
---
## PROMPT TEMPLATE FOR CONTEXT HANDOFF
```markdown
# Project State & Persisted Information
**Session**: [Descriptive session name - what are we building?]
**Last Updated**: [YYYY-MM-DD HH:MM timezone]
**Context Reset**: [Why is this handoff happening? e.g., "Turn 15 approaching token limit", "Switching from Fast to Autonomous mode", "Multi-day session checkpoint"]
**Agent Mode**: [Fast/Autonomous/Architect - current mode]
---
## Current Task Status
### Primary Objective
[One clear sentence describing the main goal - what is the ultimate deliverable?]
### Current Phase
**Active Phase**: [Phase N: Descriptive name]
**Progress**: [X% complete - be specific]
**Current Step**: [Step N-M: Exact task being worked on]
**Turn Count**: [Current turn / Mode limit]
**Blockers**: [Any impediments or issues requiring attention]
### Task Context
[2-3 sentences on what led to this task, why it matters, and what success looks like]
### Recent Work (Last 3-5 Turns)
1. **Turn N**: [What was done - be specific about files changed and outcome]
2. **Turn N-1**: [Previous action and result]
3. **Turn N-2**: [Earlier work context]
---
## Critical Runtime State
### Known Issues & Errors
**RESOLVED**:
- ✅ [Issue description] - Fixed in [file.tsx] by [solution approach]
- ✅ [Another resolved issue with specific details]
**ACTIVE**:
- ⚠️ [Current error or warning] - Occurs in [component/file] when [trigger condition]
- ⚠️ [Another active issue needing attention]
**DEFERRED**:
- 🔄 [Issue postponed] - Reason for deferral and when to revisit
### Application Status
- **Server Status**: [Running cleanly / Has warnings / Has errors]
- **Port**: [5000 or other]
- **Build Status**: [Clean / Warnings / Errors]
- **Console State**: [No errors / Known warnings listed below]
- **Hot Reload**: [Working / Not working]
### Non-Blocking Warnings
```
[List any Tailwind warnings, TypeScript info messages, or other non-critical console output]
```
---
## Architecture Decisions
### Tech Stack
**Frontend**:
- Framework: [React 18, Next.js, etc.]
- Styling: [Tailwind CSS, styled-components, etc.]
- State: [React Query, Redux, Zustand, etc.]
- Routing: [wouter, React Router, Next router, etc.]
- UI Library: [shadcn/ui, Material-UI, custom, etc.]
**Backend**:
- Runtime: [Node.js Express, Fastify, etc.]
- Database: [PostgreSQL via Drizzle, Prisma, MongoDB, etc.]
- API Style: [REST, GraphQL, tRPC]
- Auth: [Replit Auth, custom JWT, OAuth, etc.]
**Build/Dev**:
- Build Tool: [Vite, webpack, etc.]
- TypeScript: [Enabled/Disabled, strict mode?]
- Testing: [Vitest, Jest, none]
### Design System
[Comprehensive description of styling approach]
- Color System: [HSL, RGB, CSS variables approach]
- Typography: [Font families, size scale]
- Spacing: [Token system, utilities used]
- Components: [Component library details, custom patterns]
- Dark Mode: [Implementation strategy]
- Responsive: [Breakpoint system]
### Key Patterns Established
1. **[Pattern Name]**: [Description of pattern and where it's used]
- Location: [File paths]
- Rationale: [Why this approach]
2. **[Another Pattern]**: [Details]
### Critical Architectural Constraints
- [Constraint 1: e.g., "Never modify server/vite.ts"]
- [Constraint 2: e.g., "Always use HSL colors, not hex"]
- [Constraint 3: e.g., "Database changes via Drizzle migrations only"]
---
## File System Map
### Critical Files & Their Purpose
**Core Configuration**:
- `[file.config.ts]` - [Purpose and key settings] (Last modified: [date/turn])
- `[another-config.ts]` - [Purpose] (Line count: [N], Status: [clean/has issues])
**Data Layer**:
- `shared/schema.ts` - [Database schema details, key tables]
- `server/db.ts` - [Database connection config]
- `server/routes.ts` - [API routes structure]
**Business Logic**:
- `server/services/[service].ts` - [What this service does] ([N] lines)
- `[another-service].ts` - [Purpose and scope]
**UI Components** (Showcase-Ready):
- `client/src/components/ui/[component].tsx` - [Component purpose] (Dependencies: [list])
- `client/src/lib/component-inventory.ts` - [Registry of [N] components with metadata]
**Pages/Routes**:
- `client/src/pages/[Page].tsx` - [Route and purpose]
- `client/src/App.tsx` - [Router structure, key providers]
**Utilities & Helpers**:
- `client/src/lib/[utility].ts` - [Utility purpose]
- `client/src/hooks/[hook].ts` - [Hook functionality]
### Files Modified This Session
```
[file1.tsx] (Turn N) - [What changed and why]
[file2.ts] (Turn N-2) - [Changes made]
[file3.css] (Turn N-3) - [Updates]
```
### Recently Created Files
```
[new-component.tsx] (Turn N-1) - [Purpose, dependencies, status]
[new-service.ts] (Turn N-4) - [What it does]
```
---
## Code Patterns & Conventions
### Import Patterns
```typescript
// Standard import alias pattern
import { Component } from "@/components/ui/component"
import { utility } from "@/lib/utils"
// Service imports
import { apiRequest } from "@/lib/queryClient"
```
### Component Structure
```typescript
// Standard component pattern used throughout project
interface [Component]Props {
// Always type props with interface
property: Type;
}
export function ComponentName({ property }: ComponentProps) {
// Hooks at top
const [state, setState] = useState<Type>(initial);
// Event handlers
const handleAction = () => {
// Implementation
};
// Return JSX with proper data-testid
return (
<div data-testid="component-name">
{/* Content */}
</div>
);
}
```
### Data Fetching Pattern
```typescript
// TanStack Query v5 object form (always used)
const { data, isLoading } = useQuery({
queryKey: ['resource', id],
queryFn: () => fetch(`/api/resource/${id}`).then(r => r.json())
});
// Mutations with apiRequest
const mutation = useMutation({
mutationFn: (data) => apiRequest('/api/resource', 'POST', data)
});
```
### Styling Conventions
```typescript
// HSL colors only (NEVER hex)
className="bg-[hsl(220,14.3%,95.9%)] text-[hsl(220,8.9%,46.1%)]"
// Dark mode variants explicit
className="bg-white dark:bg-black text-gray-900 dark:text-gray-100"
// Tailwind utilities, no custom CSS unless necessary
className="flex items-center gap-4 p-6 rounded-lg"
```
### Database Patterns
```typescript
// Schema definition (Drizzle)
export const tableName = pgTable('table_name', {
id: serial('id').primaryKey(),
field: varchar('field', { length: 255 }).notNull(),
arrayField: varchar('array_field').array(), // Array method, not wrapper
createdAt: timestamp('created_at').defaultNow()
});
// Insert schema with zod
export const insertTableSchema = createInsertSchema(tableName);
export type InsertTable = z.infer<typeof insertTableSchema>;
export type SelectTable = typeof tableName.$inferSelect;
```
### Error Handling Pattern
```typescript
// Consistent error handling
try {
const result = await operation();
return result;
} catch (error) {
console.error(`[Context]: ${error.message}`, error);
throw new Error(`Descriptive error for user`);
}
```
---
## Dependencies & Package Ecosystem
### Core Dependencies
```json
{
"react": "^18.x.x",
"typescript": "latest",
"vite": "latest",
"express": "^4.x.x",
"@tanstack/react-query": "^5.x.x"
}
```
### UI & Styling
```json
{
"tailwindcss": "latest",
"
@radix-ui/*": "[various versions - list key ones]",
"lucide-react": "[version]",
"framer-motion": "[version]"
}
```
### Database & Backend
```json
{
"drizzle-orm": "[version]",
"drizzle-kit": "[version]",
"@neondatabase/serverless": "[version]"
}
```
### Multi-Library Support (if applicable)
```json
{
"@mui/material": "[version]",
"
@chakra-ui/react": "[version]",
"antd": "[version]"
// [Document wrapper strategy to prevent conflicts]
}
```
### Known Dependency Issues
- **[package-name]**: [Issue description and workaround]
- **[another-package]**: [Compatibility notes]
---
## Task Breakdown & Progress
### Completed Phases
- ✅ **Phase 1: [Name]** (Steps 1-1 to 1-N) - [Brief outcome]
- ✅ **Phase 2: [Name]** (Steps 2-1 to 2-M) - [Result achieved]
- ✅ **Phase 3: [Name]** (Steps 3-1 to 3-K) - [Deliverable]
### In Progress
- 🔄 **Phase N: [Name]** (Step N-M in progress)
- ✅ Step N-1: [Completed step]
- ✅ Step N-2: [Completed step]
- 🔄 Step N-M: [Current step - specific details of what's being done]
- ⏳ Step N-M 1: [Next step]
- ⏳ Step N-M 2: [Following step]
### Pending Phases
- ⏳ **Phase N 1: [Name]** (Steps pending)
- Description: [What this phase will accomplish]
- Dependencies: [What must be done first]
- Estimated scope: [Complexity/size]
- ⏳ **Phase N 2: [Name]**
- [Similar details]
### Deferred Tasks
- 🔲 **[Task Name]**: [Why deferred, when to revisit]
- 🔲 **[Another Task]**: [Deferral reason]
---
## Data & State Context
### Sample Data Structures
```typescript
// Critical data shapes used throughout app
interface PrimaryEntity {
id: number;
field: string;
// [Document all fields and their purpose]
}
// [Include other key interfaces/types]
```
### Current Database State
- **Records**: [Approximately N records in primary tables]
- **Schema Version**: [Migration number or state]
- **Test Data**: [Presence and nature of seed data]
### API Endpoints Map
```
GET /api/resource - [Purpose]
POST /api/resource - [Purpose]
PATCH /api/resource/:id - [Purpose]
DELETE /api/resource/:id - [Purpose]
GET /api/other/:param - [Purpose]
```
---
## Integration & External Services
### Active Integrations
1. **[Service Name]** ([Integration type])
- Environment Variables: `SERVICE_API_KEY`, `SERVICE_CONFIG`
- Setup Status: [Configured/Pending/Issues]
- Usage: [Where and how it's used]
- Documentation: [Link to integration docs if in project]
2. **[Another Service]**
- [Similar details]
### Secrets & Environment Variables
```bash
# Required (configured in Replit Secrets)
API_KEY="[Description of what this is for]"
DATABASE_URL="[Database connection details]"
# Optional
FEATURE_FLAG="[Purpose]"
# Not yet configured
PENDING_SERVICE_KEY="[What this will be for]"
```
---
## Performance & Optimization
### Known Performance Considerations
- **[Optimization 1]**: [What was done and why]
- **[Consideration 2]**: [Performance pattern to maintain]
### Bundle Size Notes
- Total bundle: ~[N]MB
- Largest dependencies: [List top 3-5]
- Code splitting: [Strategy if implemented]
### Caching Strategy
- **Client-side**: [React Query settings, cache invalidation patterns]
- **Server-side**: [Any caching layers]
- **Static assets**: [CDN or build optimization]
---
## Testing & Validation
### Test Coverage
- **Unit Tests**: [N tests across M files]
- **Integration Tests**: [Coverage areas]
- **E2E Tests**: [If any exist]
### Manual Testing Checklist
- [ ] [Critical user flow 1]
- [ ] [Critical user flow 2]
- [ ] [Edge case scenario]
### Known Test Failures
- **[Test name]**: [Why it's failing, plan to fix]
---
## Deployment & Infrastructure
### Deployment Status
- **Production URL**: [If deployed]
- **Last Deploy**: [Date/time if applicable]
- **Deploy Command**: [How to deploy]
- **Environment**: [Replit deployment config]
### Deployment Configuration
```typescript
// .replit workflow or deployment settings
run = "[command]"
build = "[build command if any]"
```
### Environment-Specific Concerns
- **Development**: [Any dev-only features or settings]
- **Production**: [Production-specific config needed]
---
## User Communication & Preferences
### User Working Style
[Describe the user's communication preferences, level of detail desired, technical comfort level]
Example:
- Prefers surgical, precise responses
- Challenges assumptions - wants proof
- Values structured, systematic approaches
- Fast mode preference with 3-turn target
### Session Mode Preferences
- **Current Mode**: [Fast/Autonomous/Architect]
- **Mode Changes**: [When and why mode switches happened]
- **Optimal Mode for Remaining Work**: [Recommendation with rationale]
---
## Next Steps & Priorities
### Immediate Next Actions (Next 1-3 Turns)
1. **[Action 1]**: [Specific task with file(s) to modify]
- Why: [Rationale]
- Blockers: [None / List if any]
2. **[Action 2]**: [Next task]
- Dependencies: [What must happen first]
3. **[Action 3]**: [Following task]
### Short-term Goals (Next Phase)
- [Goal 1 with success criteria]
- [Goal 2 with deliverable]
- [Goal 3 with validation approach]
### Long-term Vision
[Where is this project headed? What's the end state?]
---
## Important Warnings & Gotchas
### DO NOT
- ❌ [Critical thing to avoid - e.g., "Modify server/vite.ts"]
- ❌ [Another constraint - e.g., "Use hex colors instead of HSL"]
- ❌ [Third constraint - e.g., "Write raw SQL migrations"]
### ALWAYS
- ✅ [Required practice - e.g., "Use @/ import alias"]
- ✅ [Another must-do - e.g., "Include data-testid on interactive elements"]
- ✅ [Third requirement - e.g., "Validate with zod before database insert"]
### CRITICAL PATTERNS TO PRESERVE
1. **[Pattern Name]**: [Why it's critical, where it's used]
2. **[Another Pattern]**: [Details on preservation]
---
## Disabled/Broken Components
### Temporarily Disabled
- **[Component Name]**: [File path]
- Issue: [Specific error or problem]
- Plan: [How/when to fix]
- Workaround: [Alternative approach being used]
### Deprecated
- **[Old Component]**: [Why replaced]
- Replacement: [New component path]
---
## Documentation & References
### Project Documentation Files
- `[DOC_FILE.md]` - [What it covers, last updated]
- `[
GUIDE.md]` - [Content overview]
- `[
REFERENCE.md]` - [Purpose]
### External Documentation Links
- [Service Name]: [URL to docs]
- [Library Name]: [Relevant docs section]
### Design References
- Figma: [Link if applicable]
- Design System: [Link to internal docs]
- Color Palette: [Link or inline definition]
---
## Session Metadata
### Token Usage
- **Estimated Tokens Used**: [Rough estimate if known]
- **Context Window**: [% filled]
- **Reason for Handoff**: [Approaching limit / Mode switch / Other]
### Session History
- **Session Started**: [Date/time]
- **Total Turns**: [N turns]
- **Major Milestones**:
- Turn N: [Milestone reached]
- Turn M: [Another achievement]
### Handoff Preparation
- **Files to Read First**: [Priority files for new context]
1. [file1.ts] - [Why it's critical to read]
2. [file2.tsx] - [Context it provides]
- **Commands to Run**: [Any startup/validation commands]
```bash
npm run dev # Verify app starts
npm run db:push # If schema changed
```
---
## Quick Continuation Checklist
When resuming from this handoff:
1. [ ] Read this entire persisted_information.md
2. [ ] Review "Critical Runtime State" section for current errors
3. [ ] Check "Current Task Status" for active work
4. [ ] Review "Next Steps & Priorities" for immediate actions
5. [ ] Scan "Important Warnings & Gotchas" for constraints
6. [ ] Verify "Files Modified This Session" for recent context
7. [ ] Check "Dependencies & Package Ecosystem" for any install needs
8. [ ] Review "Code Patterns & Conventions" before writing code
9. [ ] Read priority files listed in "Handoff Preparation"
10. [ ] Continue from "Current Step" in task breakdown
---
**END OF PERSISTED INFORMATION**
*This document should enable complete continuity of work without re-explanation or context loss.*
```
---
## Usage Instructions
1. **When to Create**: As you approach turn limits or before context resets
2. **How to Populate**: Copy template above, fill ALL sections thoroughly
3. **What to Include**: Every detail that would require re-explanation
4. **What to Emphasize**: Active work, blockers, critical patterns, constraints
5. **How to Validate**: Could another agent pick up and continue immediately?
## Key Principles
- **Completeness**: Include everything needed to continue without questions
- **Specificity**: Use exact file paths, line numbers, error messages
- **Context**: Explain not just WHAT but WHY decisions were made
- **Priorities**: Make next actions crystal clear
- **Warnings**: Highlight all constraints and gotchas prominently
---
This template ensures zero context loss during handoffs.