igny8/master-docs/00-DOCUMENTATION-MANAGEMENT.md

# IGNY8 Documentation & Changelog Management System

**Last Updated:** 2025-01-XX  
**Purpose:** Complete guide for managing documentation versioning, changelog updates, and DRY principles. This document must be read by all AI agents at the start of any session.

---

## Table of Contents

1. [Versioning System](#versioning-system)
2. [Changelog Management](#changelog-management)
3. [Documentation Update Process](#documentation-update-process)
4. [DRY Principles & Standards](#dry-principles--standards)
5. [AI Agent Instructions](#ai-agent-instructions)

---

## Versioning System

### Version Format

**Format:** `MAJOR.MINOR.PATCH` (Semantic Versioning)

- **MAJOR**: Breaking changes, major feature additions, architecture changes
- **MINOR**: New features, new modules, significant enhancements
- **PATCH**: Bug fixes, small improvements, documentation updates

**Current Version:** `1.0.0`

### Version Tracking

**Location:** 
- Root `CHANGELOG.md` - Main version history
- Each documentation file header - Last updated date

**Version Update Rules:**
- **MAJOR**: Only updated when user confirms major release
- **MINOR**: Updated when user confirms new feature is complete
- **PATCH**: Updated when user confirms bug fix is complete

### Version Update Process

1. **Code Change Made**: Developer/AI makes code changes
2. **User Confirmation**: User confirms fix/feature is complete
3. **Version Update**: Update version in CHANGELOG.md
4. **Changelog Entry**: Add entry to CHANGELOG.md
5. **Documentation Update**: Update relevant documentation files if needed

**IMPORTANT**: Never update version or changelog without user confirmation that the change is complete and working.

---

## Changelog Management

### Changelog Location

**File:** `/CHANGELOG.md` (root directory)

### Changelog Structure

```markdown
## [Version] - YYYY-MM-DD

### Added
- New features, modules, or capabilities

### Changed
- Changes to existing features or behavior

### Fixed
- Bug fixes and corrections

### Deprecated
- Features that will be removed in future versions

### Removed
- Features that have been removed

### Security
- Security fixes and improvements
```

### Changelog Entry Format

Each entry must include:
- **Date**: YYYY-MM-DD format
- **Type**: Added, Changed, Fixed, Deprecated, Removed, Security
- **Description**: Clear, concise description of the change
- **Affected Areas**: Modules, components, or features affected
- **Documentation**: Reference to updated documentation files (if any)

### Example Changelog Entry

```markdown
## [1.0.1] - 2025-01-15

### Fixed
- Fixed keyword clustering issue where keywords were not properly linked to clusters
  - **Affected**: Planner Module, Keyword Clustering
  - **Documentation**: Updated 06-FUNCTIONAL-BUSINESS-LOGIC.md (Keyword Clustering section)

### Added
- Added bulk delete functionality for content ideas
  - **Affected**: Planner Module, Content Ideas
  - **Documentation**: Updated 06-FUNCTIONAL-BUSINESS-LOGIC.md (Content Ideas Management section)
```

### Changelog Update Rules

1. **Only Update After User Confirmation**: Never add changelog entries until user confirms the change is complete
2. **One Entry Per Change**: Each fix or feature gets its own entry
3. **Chronological Order**: Newest entries at the top
4. **Be Specific**: Include what was changed, why, and where
5. **Link Documentation**: Reference updated documentation files
6. **Version Bump**: Update version number when adding entries

### Changelog Categories

**Added**: New features, new modules, new endpoints, new functions
**Changed**: Modified existing features, updated workflows, refactored code
**Fixed**: Bug fixes, error corrections, issue resolutions
**Deprecated**: Features marked for removal (include migration path)
**Removed**: Features that have been completely removed
**Security**: Security patches, vulnerability fixes, access control updates

---

## Documentation Update Process

### When to Update Documentation

1. **New Feature Added**: Update relevant documentation files
2. **Feature Changed**: Update affected sections in documentation
3. **Bug Fixed**: Update documentation if behavior changed
4. **Workflow Modified**: Update workflow documentation
5. **API Changed**: Update API documentation
6. **Architecture Changed**: Update architecture documentation

### Documentation Files Structure

```
master-docs/                        # Master documentation (permanent reference)
├── 00-DOCUMENTATION-MANAGEMENT.md  # This file (management guide)
├── 01-TECH-STACK-AND-INFRASTRUCTURE.md
├── 02-APPLICATION-ARCHITECTURE.md
├── 03-FRONTEND-ARCHITECTURE.md
├── 04-BACKEND-IMPLEMENTATION.md
├── 05-AI-FRAMEWORK-IMPLEMENTATION.md
├── 06-FUNCTIONAL-BUSINESS-LOGIC.md  # Includes complete workflow documentation
├── API-COMPLETE-REFERENCE.md
└── WORDPRESS-PLUGIN-INTEGRATION.md

active-workflow-docs/               # Current state and active work (single file)
└── CURRENT_WORKFLOW_STATUS.md      # Single source of truth for current system state
```

**Note:** The `refactor-plan/` folder has been removed after consolidating relevant content into master docs.

### Documentation Update Checklist

- [ ] Identify which documentation file(s) need updating
- [ ] Update the relevant section(s)
- [ ] Update "Last Updated" date in file header
- [ ] Add changelog entry (after user confirmation)
- [ ] Verify all links still work
- [ ] Ensure consistency across all documentation

### Documentation Standards

1. **No Code Snippets**: Documentation focuses on workflows, features, and architecture
2. **Complete Coverage**: All features and workflows must be documented
3. **Accurate State**: Documentation must reflect current system state
4. **Clear Structure**: Use consistent headings and formatting
5. **Cross-References**: Link related sections and documents

---

## DRY Principles & Standards

### DRY (Don't Repeat Yourself) Philosophy

**Core Principle**: Use existing, predefined, standardized components, utilities, functions, and configurations instead of creating parallel systems or duplicating code.

### Frontend DRY Standards

#### Components

**MUST USE Existing Components:**
- **Templates**: Use 4 universal templates (DashboardTemplate, TablePageTemplate, FormPageTemplate, SystemPageTemplate)
- **UI Components**: Use components from `/frontend/src/components/`
- **Common Components**: Use ScrollToTop, GlobalErrorDisplay, LoadingStateMonitor
- **Form Components**: Use existing form components with props and configs

**DO NOT:**
- Create new templates when existing ones can be used
- Duplicate component logic
- Create parallel component systems
- Hardcode UI elements that can use config-driven approach

#### Configuration-Driven Development

**MUST USE Configuration Files:**
- **Page Configs**: `/frontend/src/config/pages/` - Define page structure
- **Snippet Configs**: `/frontend/src/config/snippets/` - Define reusable snippets
- **Route Configs**: `/frontend/src/config/routes.config.ts` - Define routes
- **API Configs**: Use existing API client patterns

**DO NOT:**
- Hardcode page structures
- Create pages without config files
- Duplicate configuration patterns

#### State Management

**MUST USE Existing Stores:**
- **Zustand Stores**: Use stores from `/frontend/src/stores/`
  - Auth Store, Site Store, Sector Store
  - Planner Store, Writer Store, Billing Store
  - Settings Store, Page Size Store, Column Visibility Store
- **React Contexts**: Use contexts from `/frontend/src/contexts/`
  - Theme Context, Sidebar Context, Header Metrics Context, Toast Context

**DO NOT:**
- Create new stores for existing functionality
- Duplicate state management logic
- Create parallel state systems

#### Utilities & Helpers

**MUST USE Existing Utilities:**
- **API Client**: Use `/frontend/src/services/api.ts` patterns
- **Hooks**: Use custom hooks from `/frontend/src/hooks/`
- **Utils**: Use utility functions from `/frontend/src/utils/`
- **Constants**: Use constants from `/frontend/src/constants/`

**DO NOT:**
- Create duplicate utility functions
- Implement API calls without using existing patterns
- Create new helper functions when existing ones work

#### CSS & Styling

**MUST USE:**
- **Tailwind CSS**: Use Tailwind utility classes
- **Existing Styles**: Use predefined styles and classes
- **Component Styles**: Use component-level styles from existing components
- **Theme System**: Use theme context for dark/light mode

**DO NOT:**
- Create custom CSS when Tailwind classes exist
- Duplicate styling patterns
- Create parallel style systems
- Hardcode colors or spacing values

### Backend DRY Standards

#### Base Classes

**MUST USE Existing Base Classes:**
- **AccountModelViewSet**: For account-isolated models
- **SiteSectorModelViewSet**: For site/sector-scoped models
- **AccountBaseModel**: For account-isolated models
- **SiteSectorBaseModel**: For site/sector-scoped models

**DO NOT:**
- Create new base classes when existing ones work
- Duplicate filtering logic
- Create parallel isolation systems

#### AI Framework

**MUST USE AI Framework:**
- **BaseAIFunction**: Inherit from this for all AI functions
- **AIEngine**: Use for executing AI functions
- **AICore**: Use for AI API calls
- **PromptRegistry**: Use for prompt management
- **run_ai_task**: Use this Celery task entry point

**DO NOT:**
- Create new AI function patterns
- Duplicate AI execution logic
- Create parallel AI systems

#### Utilities & Services

**MUST USE Existing Services:**
- **CreditService**: For credit management
- **Content Normalizer**: For content processing
- **AI Functions**: Use existing 5 AI functions
- **Middleware**: Use AccountContextMiddleware, ResourceTrackerMiddleware

**DO NOT:**
- Create duplicate service logic
- Implement credit management without CreditService
- Create parallel utility systems

### DRY Violation Detection

**Red Flags:**
- Creating new components when similar ones exist
- Duplicating API call patterns
- Creating new state management when stores exist
- Hardcoding values that should be config-driven
- Creating parallel systems for existing functionality

**Action Required:**
- Check existing components, utilities, and patterns first
- Refactor to use existing systems
- Update documentation if new patterns are truly needed

---

## AI Agent Instructions

### Mandatory Reading

**At the start of EVERY session, AI agents MUST:**
1. Read this file (`00-DOCUMENTATION-MANAGEMENT.md`)
2. Read root `README.md`
3. Read `CHANGELOG.md`
4. Understand versioning system
5. Understand changelog management
6. Understand DRY principles

### Versioning & Changelog Rules for AI Agents

1. **NEVER update version or changelog without user confirmation**
2. **ALWAYS ask user before adding changelog entries**
3. **ONLY update changelog after user confirms change is complete**
4. **ALWAYS follow changelog structure and format**
5. **ALWAYS reference updated documentation files in changelog**

### DRY Principles for AI Agents

1. **ALWAYS check for existing components/utilities before creating new ones**
2. **ALWAYS use configuration-driven approach when possible**
3. **ALWAYS use existing templates and base classes**
4. **NEVER create parallel systems**
5. **NEVER duplicate code that can be reused**

### Documentation Update Rules for AI Agents

1. **ALWAYS update documentation when making changes**
2. **ALWAYS update "Last Updated" date in file header**
3. **ALWAYS maintain consistency across documentation**
4. **ALWAYS verify links after updates**
5. **ALWAYS follow documentation standards**

### Workflow for AI Agents

**When Making Code Changes:**
1. Check existing components/utilities first (DRY)
2. Make code changes
3. Update relevant documentation
4. Wait for user confirmation
5. Add changelog entry (after confirmation)
6. Update version (if needed, after confirmation)

**When User Confirms Fix/Feature:**
1. Add changelog entry following structure
2. Update version if needed
3. Update documentation "Last Updated" dates
4. Verify all changes are documented

### Self-Explaining System

This documentation management system is designed to be self-explaining:
- **Clear Rules**: All rules are explicitly stated
- **Examples**: Examples provided for clarity
- **Structure**: Consistent structure across all documents
- **Cross-References**: Links between related documents
- **Standards**: Clear standards for all operations

**Any AI agent reading this file should understand:**
- How to manage versions
- How to update changelog
- How to follow DRY principles
- How to update documentation
- When to ask for user confirmation

---

## Summary

### Key Principles

1. **Versioning**: Semantic versioning, only update after user confirmation
2. **Changelog**: Structured entries, only after user confirmation
3. **Documentation**: Always update when making changes
4. **DRY**: Always use existing components, utilities, and patterns
5. **Confirmation**: Never update version/changelog without user confirmation

### Lock Status

**Documentation Management System**: ✅ **LOCKED**

This system is finalized and should not be changed without explicit user approval. All AI agents must follow these rules.

---

**Last Updated:** 2025-01-XX (Documentation structure updated)  
**Version:** 1.0.0  
**Status:** Locked