Organization Patterns & Conventions

Last Updated: 2025-11-15

Purpose: Guide for maintaining consistent file organization and documentation structure

📋 Overview

This document defines the patterns, conventions, and rules used to organize the repository. Follow these patterns when adding new files, creating indexes, or reorganizing content.

🗂️ Directory Structure Patterns

Root Directory

Documentation Files

README.md - Main project overview (always at root)
AGENTS.md - Repository guidelines for AI agents (always at root)
ROOT_FILES_INDEX.md - Index of root directory files
DATA_FILES_INDEX.md - Index of data files
CONFIGURATION_FILES_INDEX.md - Index of configuration files

Pattern: Root-level documentation files are high-level overviews or guidelines that should be immediately visible.

Configuration Files

.env - Active configuration (gitignored)
.env.example* - Configuration templates
package.json - Node.js package configuration
tsconfig.json - TypeScript configuration
ecosystem.config.cjs - PM2 configuration

Pattern: Configuration files stay at root for easy access.

Process Management

keep-alive.ts - Watchdog script (root for easy execution)

Pattern: Process management scripts at root for direct execution.

docs/ Directory Structure

docs/
├── Core Documentation (root of docs/)
│   ├── ARCHITECTURE.md
│   ├── EXECUTION_FLOW.md
│   ├── CONCEPTS.md
│   ├── CODE_STRUCTURE.md
│   ├── CONFIGURATION_GUIDE.md
│   ├── GETTING_STARTED.md
│   ├── MASTER_SYNTHESIS.md
│   ├── CHANGELOG_2025-11.md
│   ├── INDEX_OF_INDEXES.md ⭐
│   ├── DOCUMENTATION_INDEX.md
│   ├── CROSS_REFERENCE_MAP.md
│   ├── TIMELINE_INDEX.md
│   ├── MERGE_PLAN.md
│   ├── CURSOR_TODO.md
│   └── README.md
│
├── guides/                    # User guides (27 files)
│   ├── GUIDES_INDEX.md        # Category index
│   └── [guide files]
│
├── audits/                    # Audit reports (80+ files)
│   ├── AUDIT_INDEX.md         # Category index
│   └── [audit files]
│
├── analysis/                  # Analysis reports (80+ files)
│   ├── ANALYSIS_INDEX.md      # Category index
│   └── [analysis files]
│
├── research/                  # Research documents (4 files)
│   ├── RESEARCH_INDEX.md      # Category index
│   └── [research files]
│
└── prompts/                   # AI agent prompts (8 files)
    └── [prompt files]

Pattern: Each category has its own subdirectory with a dedicated index file.

📝 File Naming Conventions

Documentation Files

Core Documentation

UPPERCASE_WITH_UNDERSCORES.md - Core documentation files
- Examples: ARCHITECTURE.md, EXECUTION_FLOW.md, CONCEPTS.md
- Use for: Main documentation files that are frequently referenced

Index Files

CATEGORY_INDEX.md - Category-specific indexes
- Examples: GUIDES_INDEX.md, AUDIT_INDEX.md, ANALYSIS_INDEX.md
- Pattern: Always named [CATEGORY]_INDEX.md in the category directory

Date-Stamped Files

DESCRIPTION_YYYY-MM-DD.md - Date-stamped documentation
- Examples: POST_MORTEM_2025-11-13.md, AUDIT_2025-11-13.md
- Pattern: [DESCRIPTION]_[YYYY-MM-DD].md or [DESCRIPTION]_[YYYY-MM-DD]_[TIME].md

Time-Stamped Files

DESCRIPTION_YYYY-MM-DD_HHMM.md - Time-stamped documentation
- Examples: POST_MORTEM_2025-11-13_1111PST.md, AUDIT_2025-11-13_6PM.md
- Pattern: [DESCRIPTION]_[YYYY-MM-DD]_[TIME][TZ].md or [DESCRIPTION]_[YYYY-MM-DD]_[TIME].md

Session Notes

cursor_[description].md - Cursor session notes
- Examples: cursor_start_it_now.md, cursor_resume_merge_plan_discussion.md
- Pattern: cursor_[lowercase_with_underscores].md
- Location: docs/analysis/ (session notes are analysis files)

Planning Documents

DESCRIPTION.md - Planning and tracking documents
- Examples: MERGE_PLAN.md, CURSOR_TODO.md
- Pattern: UPPERCASE_WITH_UNDERSCORES.md
- Location: docs/ root (planning documents)

📚 Index Organization Patterns

Index File Structure

Every category index follows this structure:

# [Category] Index

Complete index of all [category] files, organized by [organization method].


---

## 📋 Quick Reference

### **Most [Important/Recent] [Items]**
- **[Item Name](path/to/file.md)** ⭐ - Brief description
- **[Item Name](path/to/file.md)** - Brief description

---

## 📚 [Category] by [Organization Method]

### **[Subcategory 1]**

#### **[Sub-subcategory]**
- **[Item Name](path/to/file.md)** - Description
  - Additional details
  - Key points

---

## 📅 [Category] by Date (if applicable)

### **YYYY-MM-DD**
- Item 1
- Item 2

---

## 📖 Related Documentation

- **[Related Index](../path/to/index.md)** - Description
- **[Related Guide](../path/to/guide.md)** - Description

---

**Total [Category] Files**: X

⭐ = Highly recommended / Most important

Index Organization Methods

By Category

Guides: Organized by category (Getting Started, Configuration, Running, etc.)
Audits: Organized by type (Post-Mortems, Comprehensive Audits, Code Reviews, etc.)

By Date

Audits: Organized by date (2025-11-13, 2025-11-12, etc.)
Analysis: Organized by date for date-specific reports

By Topic

Analysis: Organized by topic (Gas Strategy, Performance, Log Analysis, etc.)
Research: Organized by topic (RPC & Infrastructure, MEV & Optimization)

By Issue Type

Audits: Organized by issue type (Initialization, RPC, Balance, Gas, etc.)
Analysis: Organized by issue type for troubleshooting

🗂️ File Categorization Rules

Guides (`docs/guides/`)

Criteria: How-to guides, step-by-step instructions, user-facing documentation

Categories:

Getting Started - First-time setup, quick starts
Configuration & Setup - Configuration guides, timing setup
Running & Operations - Runbooks, operational guides
Troubleshooting - Problem-solving guides
Testing - Testing procedures
Optimization - Performance optimization guides
Reference - Reference materials, quick references

Pattern: User-facing, actionable content

Audits (`docs/audits/`)

Criteria: Code reviews, post-mortems, failure analysis, implementation notes

Categories:

Post-Mortems - Failure analysis, root cause analysis
Comprehensive Audits - Full system audits
Code Reviews - External code reviews (ChatGPT, Codex)
Implementation Notes - Implementation observations
Runtime Patch Notes - Runtime fixes and changes
Deep Failure Point Audits - Detailed failure analysis

Pattern: Analysis of failures, reviews, or implementation work

Analysis (`docs/analysis/`)

Criteria: Performance analysis, log analysis, optimization reports, status reports

Categories:

Gas Strategy & Optimization - Gas policy, cost analysis
Performance & Optimization - RPC optimization, runtime performance
Log Analysis - Log examination and analysis
Testing & Verification - Test results, verification reports
Fixes & Implementation - Fix reports, implementation status
Status & Reports - Status summaries, production reports
Session Notes & Planning - Session notes, planning documents

Pattern: Data analysis, performance reports, status updates

Research (`docs/research/`)

Criteria: External research, provider analysis, strategy research

Categories:

RPC & Infrastructure - RPC provider research, infrastructure analysis
MEV & Optimization - MEV strategies, optimization research

Pattern: External findings, provider research, strategy research

Prompts (`docs/prompts/`)

Criteria: AI agent prompts, collaboration prompts

Pattern: Prompts for AI agents (ChatGPT, Codex, etc.)

🔗 Cross-Reference Patterns

Cross-Reference Map (`docs/CROSS_REFERENCE_MAP.md`)

Purpose: Maps relationships between documents

Organization:

Issue-based cross-references (find all docs about a specific issue)
Timeline-based cross-references (find all docs from a specific date)
Implementation flow cross-references (follow implementation journeys)
Documentation cross-references (see how docs relate)

Pattern: Multi-dimensional relationship mapping

Timeline Index (`docs/TIMELINE_INDEX.md`)

Purpose: Chronological index of all documentation and events

Organization:

Complete timeline (hour-by-hour for recent dates)
Document creation timeline
Development phases
Key milestones

Pattern: Chronological organization

📊 Index Maintenance Patterns

When Adding a New File

Determine Category
- Guide → docs/guides/
- Audit → docs/audits/
- Analysis → docs/analysis/
- Research → docs/research/
- Prompt → docs/prompts/
Add to Category Index
- Open the appropriate [CATEGORY]_INDEX.md
- Add entry in appropriate section
- Follow existing formatting patterns
Update Master Indexes (if needed)
- Update docs/INDEX_OF_INDEXES.md if structure changes
- Update docs/DOCUMENTATION_INDEX.md if it's a major document
- Update docs/CROSS_REFERENCE_MAP.md if it relates to other documents
- Update docs/TIMELINE_INDEX.md with creation date
Update Counts
- Update file count in category index
- Update total count in master indexes if needed

When Creating a New Category

Create Directory
- Create docs/[category]/ directory
Create Index File
- Create docs/[category]/[CATEGORY]_INDEX.md
- Follow index file structure pattern
Update Master Indexes
- Add category to docs/INDEX_OF_INDEXES.md
- Add category to docs/DOCUMENTATION_INDEX.md
- Update structure diagram in docs/DOCUMENTATION_INDEX.md
Update Cross-References
- Add category to docs/CROSS_REFERENCE_MAP.md if applicable

🎯 Naming Pattern Examples

Date-Stamped Files

POST_MORTEM_2025-11-13.md                    # Date only
POST_MORTEM_2025-11-13_1111PST.md           # Date + time + timezone
AUDIT_2025-11-13_6PM.md                      # Date + time (informal)
CHATGPT_DEEP_RESEARCH_AUDIT_2025-11-13_6PM.md # Date + time (descriptive)

Pattern: [DESCRIPTION]_[YYYY-MM-DD][_TIME][TZ].md

Session Notes

cursor_start_it_now.md
cursor_continue_testing_and_integration.md
cursor_resume_merge_plan_discussion.md
cursor_find_steady_teddy_and_mibera_ids.md

Pattern: cursor_[lowercase_with_underscores].md

Location: docs/analysis/ (session notes are analysis files)

Planning Documents

MERGE_PLAN.md
CURSOR_TODO.md

Pattern: UPPERCASE_WITH_UNDERSCORES.md

Location: docs/ root (planning documents)

📋 Index Entry Patterns

Standard Entry

- **[Item Name](path/to/file.md)** - Brief description

Entry with Details

- **[Item Name](path/to/file.md)** - Brief description
  - Additional detail 1
  - Additional detail 2
  - Key point

Entry with Star (Important)

- **[Item Name](path/to/file.md)** ⭐ - Brief description

Entry with Type/Status

- **[Item Name](path/to/file.md)** ✅
  - **Type**: Type description
  - **Status**: Status description
  - **Key Findings**: Key points

🔍 File Location Decision Tree

Is it a user-facing how-to guide?
├─ YES → docs/guides/
└─ NO → Continue

Is it a code review, post-mortem, or failure analysis?
├─ YES → docs/audits/
└─ NO → Continue

Is it a performance analysis, log analysis, or status report?
├─ YES → docs/analysis/
└─ NO → Continue

Is it external research or provider analysis?
├─ YES → docs/research/
└─ NO → Continue

Is it an AI agent prompt?
├─ YES → docs/prompts/
└─ NO → Continue

Is it a planning or tracking document?
├─ YES → docs/ (root of docs/)
└─ NO → Continue

Is it core documentation (architecture, concepts, etc.)?
├─ YES → docs/ (root of docs/)
└─ NO → Review categorization criteria

✅ Verification Checklist

When adding or organizing files, verify:

File is in correct directory based on categorization rules
File name follows naming conventions
File is added to appropriate category index
Category index entry follows formatting patterns
File count updated in category index
Master indexes updated if needed
Cross-reference map updated if file relates to other documents
Timeline index updated with creation date
Documentation index updated if it's a major document

📖 Related Documentation

Organization Audit 2025-11-13 - Complete organization audit and verification
Index of Indexes - Master navigation hub
Documentation Index - Complete documentation index
Root Files Index - Root directory files

🎯 Quick Reference

Directory Patterns

docs/guides/ - User guides (27 files)
docs/audits/ - Audit reports (80+ files)
docs/analysis/ - Analysis reports (80+ files)
docs/research/ - Research documents (4 files)
docs/prompts/ - AI agent prompts (8 files)

Naming Patterns

Core docs: UPPERCASE_WITH_UNDERSCORES.md
Date-stamped: DESCRIPTION_YYYY-MM-DD.md
Time-stamped: DESCRIPTION_YYYY-MM-DD_HHMM.md
Session notes: cursor_[description].md
Index files: [CATEGORY]_INDEX.md

Index Patterns

Category index in each category directory
Master index at docs/INDEX_OF_INDEXES.md
Cross-reference map at docs/CROSS_REFERENCE_MAP.md
Timeline index at docs/TIMELINE_INDEX.md

Maintained By: Organization Patterns System
Review Frequency: As needed when patterns change

FilesExpand file tree

ORGANIZATION_PATTERNS.md

Latest commit

History

ORGANIZATION_PATTERNS.md

File metadata and controls

Organization Patterns & Conventions

📋 Overview

🗂️ Directory Structure Patterns

Root Directory

Documentation Files

Configuration Files

Process Management

docs/ Directory Structure

📝 File Naming Conventions

Documentation Files

Core Documentation

Index Files

Date-Stamped Files

Time-Stamped Files

Session Notes

Planning Documents

📚 Index Organization Patterns

Index File Structure

Index Organization Methods

By Category

By Date

By Topic

By Issue Type

🗂️ File Categorization Rules

Guides (docs/guides/)

Audits (docs/audits/)

Analysis (docs/analysis/)

Research (docs/research/)

Prompts (docs/prompts/)

🔗 Cross-Reference Patterns

Cross-Reference Map (docs/CROSS_REFERENCE_MAP.md)

Timeline Index (docs/TIMELINE_INDEX.md)

📊 Index Maintenance Patterns

When Adding a New File

When Creating a New Category

🎯 Naming Pattern Examples

Date-Stamped Files

Session Notes

Planning Documents

📋 Index Entry Patterns

Standard Entry

Entry with Details

Entry with Star (Important)

Entry with Type/Status

🔍 File Location Decision Tree

✅ Verification Checklist

📖 Related Documentation

🎯 Quick Reference

Directory Patterns

Naming Patterns

Index Patterns

Guides (`docs/guides/`)

Audits (`docs/audits/`)

Analysis (`docs/analysis/`)

Research (`docs/research/`)

Prompts (`docs/prompts/`)

Cross-Reference Map (`docs/CROSS_REFERENCE_MAP.md`)

Timeline Index (`docs/TIMELINE_INDEX.md`)