igny8/RULES.md

IGNY8 Documentation Rules

Version: 1.0
Last Updated: December 25, 2025
Purpose: Rules for maintaining consistent, accurate documentation

---

Core Principles

1. Single Source of Truth - One file per topic, no duplicates
2. Code is King - Documentation reflects actual code, not plans
3. Tables Over Prose - Use tables for lists of 3+ items
4. Code Paths Always - Every feature links to exact files
5. Brief But Complete - No fluff, every word has purpose

---

File Structure Rules

Root Folder (/)

Only these MD files allowed in root:

• CHANGELOG.md - Version history
• RULES.md - This file
• IGNY8-APP.md - Executive summary (non-technical)
• README.md - Project quickstart

DO NOT CREATE random MD files in root. All documentation goes in /docs/.

Docs Folder (/docs/)

docs/
├── INDEX.md                    # Master navigation (update when adding docs)
├── 00-SYSTEM/                  # Architecture, auth, tenancy
├── 10-MODULES/                 # One file per module
├── 20-API/                     # API endpoints and schemas
├── 30-FRONTEND/                # Pages, stores, components
├── 40-WORKFLOWS/               # Cross-module flows
└── 90-REFERENCE/               # Models, AI functions, troubleshooting

---

Document Templates

Module Document

Every module doc must include:

# [Module Name]

**Last Verified:** YYYY-MM-DD
**Status:** ✅ Active | ⏸️ Inactive
**Backend Path:** `backend/...`
**Frontend Path:** `frontend/...`

## Quick Reference
| What | File | Key Items |
|------|------|-----------|

## Data Models
[Tables with fields]

## API Endpoints
| Method | Path | Handler | Purpose |

## Business Logic
[Key operations with credit costs]

## Frontend Pages
[Routes and components]

## Common Issues
| Issue | Cause | Fix |

## Planned Changes
| Feature | Status | Description |

Status Values

For Planned Changes tables:

• ✅ Completed
• 🐛 Bug (known issue)
• 🔜 Planned (confirmed future work)
• ⏸️ Pending (waiting on dependency)
• ❌ Cancelled

---

Update Rules

When to Update Documentation

Event	Action
New feature added	Update relevant module doc
Bug fixed	Add to Common Issues if recurring
API endpoint changed	Update API endpoints table
Model changed	Update data models section
Config changed	Update relevant doc
Release	Update CHANGELOG.md

What to Update

Change Type	Files to Update
New module	Create module doc, update INDEX.md
New endpoint	Module doc + API/ENDPOINTS.md
New model	Module doc + 90-REFERENCE/MODELS.md
Frontend page	Module doc + 30-FRONTEND/PAGES.md
Bug fix	Common Issues in relevant doc

"Last Verified" Dates

Update Last Verified: date when:

• You confirm the doc matches current code
• After making changes to the doc
• During documentation reviews

---

Writing Style

Do

• Use present tense ("Creates" not "Will create")
• Use tables for any list of 3+ items
• Include exact file paths
• Link to related docs
• Keep sentences short

Don't

• Don't explain obvious things
• Don't use jargon without defining
• Don't duplicate info across files
• Don't use passive voice
• Don't leave TODOs in docs (use Planned Changes table)

Code Path Format

Backend: `backend/igny8_core/modules/planner/views.py:KeywordViewSet.bulk_delete`
Frontend: `frontend/src/pages/Planner/Keywords.tsx:handleBulkDelete`

---

AI Agent Instructions

When AI agents (Copilot, Claude, etc.) make changes:

After Code Changes

1. Identify which module(s) were modified
2. Update the relevant module doc(s)
3. If API changed, update API endpoints
4. If model changed, update MODELS.md
5. Update CHANGELOG.md for significant changes

What NOT to Do

• DO NOT create new MD files in root folder
• DO NOT create "summary" or "implementation" docs
• DO NOT duplicate existing documentation
• DO NOT add verbose explanations
• DO NOT leave placeholder content

Verification Checklist

After documentation update:

• File is in correct location (/docs/ structure)
• INDEX.md updated if new file added
• No duplicate information
• All code paths are accurate
• Tables used appropriately
• Last Verified date updated

---

Documentation Review Schedule

Frequency	Action
Per commit	Update affected docs
Weekly	Review recent changes vs docs
Monthly	Full audit: code vs docs
Per release	Update CHANGELOG.md, verify all docs

---

Quick Reference: File Locations

Topic	File
Master navigation	docs/INDEX.md
Architecture	docs/00-SYSTEM/ARCHITECTURE.md
Authentication	docs/00-SYSTEM/AUTH-FLOWS.md
Multi-tenancy	docs/00-SYSTEM/TENANCY.md
Planner module	docs/10-MODULES/PLANNER.md
Writer module	docs/10-MODULES/WRITER.md
Billing module	docs/10-MODULES/BILLING.md
Automation	docs/10-MODULES/AUTOMATION.md
Integrations	docs/10-MODULES/INTEGRATIONS.md
Settings	docs/10-MODULES/SYSTEM-SETTINGS.md
Linker (inactive)	docs/10-MODULES/LINKER.md
Optimizer (inactive)	docs/10-MODULES/OPTIMIZER.md
Publisher	docs/10-MODULES/PUBLISHER.md
API endpoints	docs/20-API/ENDPOINTS.md
All models	docs/90-REFERENCE/MODELS.md
Troubleshooting	docs/90-REFERENCE/TROUBLESHOOTING.md
Version history	CHANGELOG.md
Executive summary	IGNY8-APP.md

---

Enforcement

These rules are enforced by:

1. Code review checklist includes documentation
2. AI agents instructed to follow these rules
3. Monthly documentation audits
4. CHANGELOG must be updated for releases

When in doubt: Update the existing doc, don't create a new file.