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:

```markdown
# [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.**