diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2025-11-04 09:43:53 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2025-11-04 09:43:53 +0000 |
| commit | f286f627790b89d86c0b08c3569c287546433880 (patch) | |
| tree | 7012ee82d9429f0a03967f9ebf44a0b4c22eff27 | |
| parent | 5a0ca1ccb9022f75852c0b2a38e4114af069d53a (diff) | |
docs: clean up .txt files and add file format guidelines
- Archive 5 .txt files to docs/archive/
- AUDIT_FIX_SUMMARY.txt
- PROJECT_STATUS_VISUAL.txt
- SESSION_SUMMARY.txt
- TEST_VISUAL_SUMMARY.txt
- CLEANUP_VISUAL_SUMMARY.txt
- Update AGENTS.md with file format guidelines:
- When to use .txt (ASCII art only)
- When to use .md (all documentation)
- .txt lifecycle: create → use → archive immediately
- Added to cleanup triggers and checklists
Root directory now completely clean:
- 4 .md files (README, AGENTS, CURRENT_STATUS, CLEANUP_COMPLETE)
- 0 .txt files (all archived)
Archive contains:
- 33 .md files (historical documentation)
- 5 .txt files (visual summaries)
| -rw-r--r-- | AGENTS.md | 114 | ||||
| -rw-r--r-- | docs/archive/2025-11-03-test-visual-summary.txt (renamed from TEST_VISUAL_SUMMARY.txt) | 0 | ||||
| -rw-r--r-- | docs/archive/2025-11-04-audit-fix-summary.txt (renamed from AUDIT_FIX_SUMMARY.txt) | 0 | ||||
| -rw-r--r-- | docs/archive/2025-11-04-cleanup-visual-summary.txt (renamed from CLEANUP_VISUAL_SUMMARY.txt) | 0 | ||||
| -rw-r--r-- | docs/archive/2025-11-04-project-status-visual.txt (renamed from PROJECT_STATUS_VISUAL.txt) | 0 | ||||
| -rw-r--r-- | docs/archive/2025-11-04-session-summary.txt (renamed from SESSION_SUMMARY.txt) | 0 |
6 files changed, 106 insertions, 8 deletions
| @@ -30,6 +30,7 @@ ngit-grasp/ | |||
| 30 | ├── docs/archive/ # Completed session/phase docs | 30 | ├── docs/archive/ # Completed session/phase docs |
| 31 | │ ├── 2025-11-04-tag-migration.md | 31 | │ ├── 2025-11-04-tag-migration.md |
| 32 | │ ├── 2025-11-04-flake-migration.md | 32 | │ ├── 2025-11-04-flake-migration.md |
| 33 | │ ├── 2025-11-04-cleanup-visual-summary.txt # Visual summaries | ||
| 33 | │ └── 2025-11-03-architecture-investigation.md | 34 | │ └── 2025-11-03-architecture-investigation.md |
| 34 | │ | 35 | │ |
| 35 | ├── docs/learnings/ # Extracted knowledge (permanent) | 36 | ├── docs/learnings/ # Extracted knowledge (permanent) |
| @@ -47,6 +48,24 @@ ngit-grasp/ | |||
| 47 | └── history/ # Conversation history | 48 | └── history/ # Conversation history |
| 48 | ``` | 49 | ``` |
| 49 | 50 | ||
| 51 | ### File Type Guidelines | ||
| 52 | |||
| 53 | **Markdown (.md):** | ||
| 54 | - Primary format for all documentation | ||
| 55 | - Easy to read in plain text and rendered | ||
| 56 | - Supports code blocks, links, tables | ||
| 57 | - Version control friendly | ||
| 58 | |||
| 59 | **Text (.txt):** | ||
| 60 | - Only for visual ASCII art summaries | ||
| 61 | - Must be archived after session (never permanent) | ||
| 62 | - Examples: status boxes, visual diagrams | ||
| 63 | - Archive to `docs/archive/YYYY-MM-DD-name.txt` | ||
| 64 | |||
| 65 | **Other formats:** | ||
| 66 | - Avoid unless absolutely necessary | ||
| 67 | - If needed, document in README.md why | ||
| 68 | |||
| 50 | --- | 69 | --- |
| 51 | 70 | ||
| 52 | ## 📋 Document Lifecycle | 71 | ## 📋 Document Lifecycle |
| @@ -62,13 +81,16 @@ ngit-grasp/ | |||
| 62 | - `TAG_MIGRATION_COMPLETE.md` → Archive when next phase starts | 81 | - `TAG_MIGRATION_COMPLETE.md` → Archive when next phase starts |
| 63 | - `SESSION_2025_11_04_SUMMARY.md` → Archive at session end | 82 | - `SESSION_2025_11_04_SUMMARY.md` → Archive at session end |
| 64 | - `NEXT_STEPS.md` → Update continuously, archive when complete | 83 | - `NEXT_STEPS.md` → Update continuously, archive when complete |
| 84 | - `STATUS_VISUAL.txt` → Archive immediately after session | ||
| 65 | 85 | ||
| 66 | **Rules:** | 86 | **Rules:** |
| 67 | - ✅ Use descriptive names with dates: `YYYY-MM-DD-description.md` | 87 | - ✅ Use descriptive names with dates: `YYYY-MM-DD-description.md` |
| 68 | - ✅ Mark status clearly: `[WIP]`, `[COMPLETE]`, `[ARCHIVED]` | 88 | - ✅ Mark status clearly: `[WIP]`, `[COMPLETE]`, `[ARCHIVED]` |
| 69 | - ✅ Include date and context at top | 89 | - ✅ Include date and context at top |
| 90 | - ✅ Use `.md` for docs, `.txt` only for ASCII art summaries | ||
| 70 | - ❌ Don't let root accumulate more than 5-10 working docs | 91 | - ❌ Don't let root accumulate more than 5-10 working docs |
| 71 | - ❌ Don't create duplicates (merge or link instead) | 92 | - ❌ Don't create duplicates (merge or link instead) |
| 93 | - ❌ Don't keep `.txt` files in root (archive immediately) | ||
| 72 | 94 | ||
| 73 | ### 2. Permanent Documentation (docs/) | 95 | ### 2. Permanent Documentation (docs/) |
| 74 | 96 | ||
| @@ -132,7 +154,7 @@ ngit-grasp/ | |||
| 132 | 154 | ||
| 133 | ### When to Clean Up | 155 | ### When to Clean Up |
| 134 | 156 | ||
| 135 | **Trigger:** Root directory has >10 markdown files | 157 | **Trigger:** Root directory has >10 markdown files OR any .txt files |
| 136 | **Frequency:** End of each major phase or weekly | 158 | **Frequency:** End of each major phase or weekly |
| 137 | **Responsibility:** AI agents should proactively suggest cleanup | 159 | **Responsibility:** AI agents should proactively suggest cleanup |
| 138 | 160 | ||
| @@ -142,6 +164,9 @@ ngit-grasp/ | |||
| 142 | ```bash | 164 | ```bash |
| 143 | # Find old working docs | 165 | # Find old working docs |
| 144 | ls -lt *.md | head -20 | 166 | ls -lt *.md | head -20 |
| 167 | |||
| 168 | # Check for .txt files (should always be archived) | ||
| 169 | ls -la *.txt | ||
| 145 | ``` | 170 | ``` |
| 146 | 171 | ||
| 147 | 2. **Extract Learnings** | 172 | 2. **Extract Learnings** |
| @@ -151,8 +176,11 @@ ngit-grasp/ | |||
| 151 | 176 | ||
| 152 | 3. **Archive Completed Work** | 177 | 3. **Archive Completed Work** |
| 153 | ```bash | 178 | ```bash |
| 154 | # Move to archive with date prefix | 179 | # Archive markdown with date prefix |
| 155 | mv TAG_MIGRATION_COMPLETE.md docs/archive/2025-11-04-tag-migration.md | 180 | mv TAG_MIGRATION_COMPLETE.md docs/archive/2025-11-04-tag-migration.md |
| 181 | |||
| 182 | # Archive .txt files immediately | ||
| 183 | mv STATUS_VISUAL.txt docs/archive/2025-11-04-status-visual.txt | ||
| 156 | ``` | 184 | ``` |
| 157 | 185 | ||
| 158 | 4. **Delete Obsolete Documents** | 186 | 4. **Delete Obsolete Documents** |
| @@ -171,19 +199,23 @@ ngit-grasp/ | |||
| 171 | # Before cleanup (36 files in root!) | 199 | # Before cleanup (36 files in root!) |
| 172 | ls *.md | wc -l | 200 | ls *.md | wc -l |
| 173 | # 36 | 201 | # 36 |
| 202 | ls *.txt | wc -l | ||
| 203 | # 5 | ||
| 174 | 204 | ||
| 175 | # After cleanup (5-8 files in root) | 205 | # After cleanup (3-5 files in root) |
| 176 | ls *.md | 206 | ls *.md |
| 177 | # README.md | 207 | # README.md |
| 178 | # AGENTS.md | 208 | # AGENTS.md |
| 179 | # CHANGELOG.md | ||
| 180 | # CURRENT_STATUS.md | 209 | # CURRENT_STATUS.md |
| 181 | # NEXT_STEPS.md | 210 | |
| 211 | ls *.txt | ||
| 212 | # (none - all archived) | ||
| 182 | 213 | ||
| 183 | # Archived | 214 | # Archived |
| 184 | ls docs/archive/ | 215 | ls docs/archive/ |
| 185 | # 2025-11-04-tag-migration.md | 216 | # 2025-11-04-tag-migration.md |
| 186 | # 2025-11-04-flake-migration.md | 217 | # 2025-11-04-flake-migration.md |
| 218 | # 2025-11-04-cleanup-visual-summary.txt | ||
| 187 | # 2025-11-03-architecture-investigation.md | 219 | # 2025-11-03-architecture-investigation.md |
| 188 | # ... | 220 | # ... |
| 189 | 221 | ||
| @@ -319,6 +351,55 @@ When you: | |||
| 319 | 351 | ||
| 320 | --- | 352 | --- |
| 321 | 353 | ||
| 354 | ## 📄 File Format Guidelines | ||
| 355 | |||
| 356 | ### When to Use .txt Files | ||
| 357 | |||
| 358 | **Use .txt ONLY for:** | ||
| 359 | - ASCII art visual summaries | ||
| 360 | - Box diagrams with Unicode characters | ||
| 361 | - Terminal-style status displays | ||
| 362 | |||
| 363 | **Examples of appropriate .txt content:** | ||
| 364 | ``` | ||
| 365 | ╔════════════════════════════════════════╗ | ||
| 366 | ║ STATUS: ✅ COMPLETE ║ | ||
| 367 | ╚════════════════════════════════════════╝ | ||
| 368 | ``` | ||
| 369 | |||
| 370 | **Rules:** | ||
| 371 | - ✅ Create in root during session for visual impact | ||
| 372 | - ✅ Archive immediately after session ends | ||
| 373 | - ✅ Use descriptive names: `CLEANUP_VISUAL_SUMMARY.txt` | ||
| 374 | - ❌ Never keep .txt files in root long-term | ||
| 375 | - ❌ Don't use .txt for regular documentation | ||
| 376 | - ❌ Don't duplicate information (use .md instead) | ||
| 377 | |||
| 378 | **Lifecycle:** | ||
| 379 | ``` | ||
| 380 | Create .txt → Use in session → Archive immediately | ||
| 381 | ``` | ||
| 382 | |||
| 383 | ### When to Use .md Files | ||
| 384 | |||
| 385 | **Use .md for ALL documentation:** | ||
| 386 | - Architecture docs | ||
| 387 | - Session summaries | ||
| 388 | - Status reports | ||
| 389 | - Learnings | ||
| 390 | - Planning documents | ||
| 391 | - API documentation | ||
| 392 | - User guides | ||
| 393 | |||
| 394 | **Why markdown is preferred:** | ||
| 395 | - Renders nicely on GitHub/GitLab | ||
| 396 | - Supports code blocks with syntax highlighting | ||
| 397 | - Easy to link between documents | ||
| 398 | - Better for long-form content | ||
| 399 | - Version control friendly | ||
| 400 | |||
| 401 | --- | ||
| 402 | |||
| 322 | ## 📝 Writing Guidelines | 403 | ## 📝 Writing Guidelines |
| 323 | 404 | ||
| 324 | ### Markdown Style | 405 | ### Markdown Style |
| @@ -400,6 +481,11 @@ cargo build | |||
| 400 | - `YYYY-MM-DD-description.md` for working docs | 481 | - `YYYY-MM-DD-description.md` for working docs |
| 401 | - `topic-name.md` for permanent docs | 482 | - `topic-name.md` for permanent docs |
| 402 | 483 | ||
| 484 | 5. **Choose correct file format** | ||
| 485 | - Use `.md` for all documentation (default) | ||
| 486 | - Use `.txt` ONLY for ASCII art visual summaries | ||
| 487 | - Archive `.txt` files immediately after session | ||
| 488 | |||
| 403 | ### During Development | 489 | ### During Development |
| 404 | 490 | ||
| 405 | 1. **Update status markers** | 491 | 1. **Update status markers** |
| @@ -431,9 +517,11 @@ cargo build | |||
| 431 | 517 | ||
| 432 | ### Cleanup Time | 518 | ### Cleanup Time |
| 433 | 519 | ||
| 434 | 1. **Review all root .md files** | 520 | 1. **Review all root .md and .txt files** |
| 435 | 2. **Extract learnings to docs/learnings/** | 521 | 2. **Extract learnings to docs/learnings/** |
| 436 | 3. **Archive completed work to docs/archive/** | 522 | 3. **Archive completed work to docs/archive/** |
| 523 | - `.md` files: Extract learnings first | ||
| 524 | - `.txt` files: Archive immediately (no extraction needed) | ||
| 437 | 4. **Delete obsolete duplicates** | 525 | 4. **Delete obsolete duplicates** |
| 438 | 5. **Update links in active docs** | 526 | 5. **Update links in active docs** |
| 439 | 6. **Commit with clear message** | 527 | 6. **Commit with clear message** |
| @@ -472,10 +560,18 @@ cargo build | |||
| 472 | 560 | ||
| 473 | - [ ] Moved to docs/archive/ | 561 | - [ ] Moved to docs/archive/ |
| 474 | - [ ] Renamed with date prefix | 562 | - [ ] Renamed with date prefix |
| 475 | - [ ] ARCHIVED marker at top | 563 | - [ ] ARCHIVED marker at top (for .md files) |
| 476 | - [ ] Learnings extracted first | 564 | - [ ] Learnings extracted first (for .md files) |
| 477 | - [ ] Not referenced in active docs | 565 | - [ ] Not referenced in active docs |
| 478 | 566 | ||
| 567 | ### For .txt Files | ||
| 568 | |||
| 569 | - [ ] Contains only ASCII art/visual summaries | ||
| 570 | - [ ] Created in root for session use | ||
| 571 | - [ ] Archived immediately after session | ||
| 572 | - [ ] Not used for regular documentation | ||
| 573 | - [ ] Descriptive filename with purpose clear | ||
| 574 | |||
| 479 | --- | 575 | --- |
| 480 | 576 | ||
| 481 | ## 📚 Reference Documents | 577 | ## 📚 Reference Documents |
| @@ -517,6 +613,8 @@ cargo build | |||
| 517 | 6. **Use descriptive names** - Future you will thank you | 613 | 6. **Use descriptive names** - Future you will thank you |
| 518 | 7. **Check before creating** - Document might already exist | 614 | 7. **Check before creating** - Document might already exist |
| 519 | 8. **Update as you go** - Don't wait for cleanup time | 615 | 8. **Update as you go** - Don't wait for cleanup time |
| 616 | 9. **Use .md by default** - Only use .txt for ASCII art | ||
| 617 | 10. **Archive .txt immediately** - Don't let them linger | ||
| 520 | 618 | ||
| 521 | --- | 619 | --- |
| 522 | 620 | ||
diff --git a/TEST_VISUAL_SUMMARY.txt b/docs/archive/2025-11-03-test-visual-summary.txt index cc45261..cc45261 100644 --- a/TEST_VISUAL_SUMMARY.txt +++ b/docs/archive/2025-11-03-test-visual-summary.txt | |||
diff --git a/AUDIT_FIX_SUMMARY.txt b/docs/archive/2025-11-04-audit-fix-summary.txt index 9c056af..9c056af 100644 --- a/AUDIT_FIX_SUMMARY.txt +++ b/docs/archive/2025-11-04-audit-fix-summary.txt | |||
diff --git a/CLEANUP_VISUAL_SUMMARY.txt b/docs/archive/2025-11-04-cleanup-visual-summary.txt index 70ad35e..70ad35e 100644 --- a/CLEANUP_VISUAL_SUMMARY.txt +++ b/docs/archive/2025-11-04-cleanup-visual-summary.txt | |||
diff --git a/PROJECT_STATUS_VISUAL.txt b/docs/archive/2025-11-04-project-status-visual.txt index f945258..f945258 100644 --- a/PROJECT_STATUS_VISUAL.txt +++ b/docs/archive/2025-11-04-project-status-visual.txt | |||
diff --git a/SESSION_SUMMARY.txt b/docs/archive/2025-11-04-session-summary.txt index 3692edb..3692edb 100644 --- a/SESSION_SUMMARY.txt +++ b/docs/archive/2025-11-04-session-summary.txt | |||