igny8/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
2. Changelog Management
3. Documentation Update Process
4. DRY Principles & Standards
5. 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

## [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

## [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

docs/
├── 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
├── API-COMPLETE-REFERENCE.md
├── WORDPRESS-PLUGIN-INTEGRATION.md
├── planning/                       # Architecture & implementation planning
│   ├── IGNY8-HOLISTIC-ARCHITECTURE-PLAN.md
│   ├── IGNY8-IMPLEMENTATION-PLAN.md
│   ├── Igny8-phase-2-plan.md
│   ├── CONTENT-WORKFLOW-DIAGRAM.md
│   ├── ARCHITECTURE_CONTEXT.md
│   └── sample-usage-limits-credit-system
└── refactor/                        # Refactoring plans and documentation
    ├── README.md
    ├── routes/
    ├── folder-structure/
    └── migrations/

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
Version: 1.0.0
Status: Locked