# Markdown File Maintenance Guide

**Last Updated**: 2026-01-05  
**Purpose**: Guidelines for maintaining clean, organized markdown files

---

## File Organization Standards

### Root Directory (`/`)
**Should contain ONLY**:
- `README.md` - Main project README
- `PROJECT_STRUCTURE.md` - Project structure documentation

**Should NOT contain**:
- Status reports
- Completion reports
- Analysis reports
- Timestamped snapshots
- Temporary fix guides

### Documentation Directory (`docs/`)
**Should contain**:
- Permanent documentation
- Architecture guides
- Configuration guides
- Tutorials and how-tos
- API documentation

**Should NOT contain**:
- Status/completion reports (→ `reports/`)
- Temporary fix guides (→ `docs/09-troubleshooting/archive/`)
- Timestamped snapshots (→ `reports/archive/`)

### Reports Directory (`reports/`)
**Should contain**:
- All status reports
- All analysis reports
- All diagnostic reports
- Timestamped snapshots (in `archive/` subdirectories)

**Structure**:
```
reports/
├── status/          # Current status reports
├── analyses/        # Analysis reports
├── inventories/     # Inventory reports
└── archive/         # Archived reports by date
    └── YYYY-MM-DD/  # Date-specific archives
```

### Submodule Directories
**Each submodule should have**:
- `README.md` - Submodule documentation
- `docs/` - Submodule-specific documentation
- `reports/` or `archive/` - Status/completion files

---

## File Naming Conventions

### Documentation Files
- Use `UPPERCASE_WITH_UNDERSCORES.md`
- Be descriptive: `NETWORK_ARCHITECTURE.md` not `network.md`
- Use consistent prefixes:
  - `README.md` - Directory overview
  - `QUICK_START.md` - Quick start guide
  - `DEPLOYMENT.md` - Deployment guide
  - `TROUBLESHOOTING.md` - Troubleshooting guide

### Status/Report Files
- Use descriptive names: `SERVICE_STATUS.md` not `status.md`
- Avoid timestamps in filenames (use archive directories instead)
- Use consistent suffixes:
  - `*_STATUS.md` - Current status
  - `*_REPORT.md` - Analysis report
  - `*_SUMMARY.md` - Summary report

### Temporary Files
- Prefix with `TEMP_` or `ARCHIVE_`
- Move to archive directories promptly
- Delete after 90 days if no longer needed

---

## When to Create Files

### ✅ Create Documentation When:
- Documenting a new feature or component
- Creating a guide or tutorial
- Documenting architecture or design decisions
- Creating API documentation

### ✅ Create Reports When:
- Generating status reports
- Creating analysis reports
- Documenting diagnostic findings
- Creating inventory snapshots

### ❌ Don't Create Files For:
- Temporary notes (use issue tracker or notes app)
- One-time commands (use scripts)
- Duplicate status (update existing file)
- Placeholder content (wait until content is ready)

---

## When to Archive Files

### Archive When:
- File is older than 90 days AND superseded by newer version
- File is a timestamped snapshot
- File documents a completed task (not ongoing)
- File is a temporary fix guide (issue resolved)

### Archive Location:
- `reports/archive/YYYY-MM-DD/` - For dated reports
- `docs/09-troubleshooting/archive/` - For resolved troubleshooting guides
- `{submodule}/docs/archive/` - For submodule-specific archives

### Archive Naming:
- Keep original filename
- Add date prefix if needed: `YYYY-MM-DD_original-name.md`
- Create `README.md` in archive directory explaining contents

---

## When to Delete Files

### Safe to Delete:
- Duplicate files (keep most recent)
- Empty or placeholder files
- Files marked as deprecated
- Old temporary files (>90 days, archived)

### Never Delete:
- `README.md` files
- Active documentation
- Files referenced by other files
- Files in git history (use git to remove)

---

## Maintenance Checklist

### Weekly
- [ ] Review root directory for misplaced files
- [ ] Archive timestamped snapshots older than 7 days
- [ ] Check for duplicate status files

### Monthly
- [ ] Review `reports/` organization
- [ ] Archive completed status reports
- [ ] Update cross-references
- [ ] Check for broken links

### Quarterly
- [ ] Review archive directories
- [ ] Delete old temporary files (>90 days)
- [ ] Consolidate duplicate documentation
- [ ] Update file organization standards

---

## Automated Maintenance

### Analysis Scripts
```bash
# Analyze all markdown files
python3 scripts/analyze-markdown-files.py

# Check for inconsistencies
python3 scripts/check-content-inconsistencies.py

# Cleanup files
bash scripts/cleanup-markdown-files.sh
```

### Git Hooks (Optional)
Create `.git/hooks/pre-commit` to check for:
- Files in wrong directories
- Broken cross-references
- Placeholder content

---

## Common Issues and Solutions

### Issue: Too many files in root
**Solution**: Move status/report files to `reports/`

### Issue: Duplicate status files
**Solution**: Consolidate to single status file per component

### Issue: Broken cross-references
**Solution**: Update links or move files to correct location

### Issue: Outdated content
**Solution**: Archive or update with current information

### Issue: Temporary files accumulating
**Solution**: Archive or delete after 90 days

---

## Best Practices

1. **One Source of Truth**: Don't duplicate status information
2. **Clear Organization**: Follow directory structure standards
3. **Descriptive Names**: Use clear, consistent file names
4. **Regular Cleanup**: Archive or delete old files regularly
5. **Cross-Reference**: Keep links between related files updated
6. **Document Decisions**: Explain why files are organized as they are

---

## Quick Reference

### File Locations
| Type | Location |
|------|----------|
| Main README | `/README.md` |
| Project Structure | `/PROJECT_STRUCTURE.md` |
| Documentation | `/docs/` |
| Status Reports | `/reports/status/` |
| Analysis Reports | `/reports/analyses/` |
| Archived Reports | `/reports/archive/YYYY-MM-DD/` |
| Temporary Fixes | `/docs/09-troubleshooting/archive/` |

### Commands
```bash
# Count markdown files
find . -name "*.md" -type f | wc -l

# Find files in root
find . -maxdepth 1 -name "*.md" -type f

# Find duplicate names
find . -name "*.md" -type f | xargs basename | sort | uniq -d

# Check for broken links (requires markdown-link-check)
find . -name "*.md" -type f -exec markdown-link-check {} \;
```

---

## Questions?

- Review `MARKDOWN_FILES_COMPREHENSIVE_REPORT.md` for detailed analysis
- Check `CONTENT_INCONSISTENCIES.json` for specific issues
- Run analysis scripts for current status

---

**Maintained By**: Project Team  
**Last Review**: 2026-01-05