Skip to content

Latest commit

 

History

History
261 lines (200 loc) · 7.46 KB

DOCS_CONVENTION.md

File metadata and controls

261 lines (200 loc) · 7.46 KB

Documentation Convention

Purpose: Ensure consistent, organized documentation that serves as a single source of truth for both AI agents and human developers.

Core Principle: Single Source of Truth

Problem Solved: Previous approach created 17+ markdown files with conflicting information (status reported as 40%, 70%, 85%, 95% in different files), causing confusion for AI agents and humans.

Solution: Maintain exactly 6 core documentation files in the root directory, with supporting docs in subdirectories.

Root Directory Documentation (6 Files Only)

1. README.md

Purpose: Main project documentation Audience: New users, potential contributors Content:

  • Project overview and features
  • Quick start examples
  • Installation instructions
  • Links to other documentation Update frequency: As features change

2. QUICKSTART.md

Purpose: Getting started guide Audience: New users Content:

  • Step-by-step setup
  • First query example
  • First GEO submission example
  • Common troubleshooting Update frequency: Rarely (stable after initial implementation)

3. IMPLEMENTATION_STATUS.md ⭐

Purpose: Single source of truth for project status Audience: Developers, AI agents, project managers Content:

  • Completion status by module
  • Current progress percentage
  • What works vs what doesn't
  • Next priorities Update frequency: Every time code changes

✅ Convention for AI Agents:

  • ALWAYS update this file when completing features
  • NEVER create alternative status files (no "STATUS_v2.md", "CURRENT_STATUS.md", etc.)
  • Use checkboxes: - [x] for done, - [ ] for pending
  • Update the overall percentage at the top

4. TESTING_STATUS.md ⭐

Purpose: Single source of truth for test status Audience: Developers, QA, AI agents Content:

  • Current test pass rate
  • Test coverage percentage
  • Failing tests and their causes
  • Recent improvements Update frequency: After test runs

✅ Convention for AI Agents:

  • ALWAYS update this file after fixing tests
  • NEVER create alternative test status files
  • Include specific numbers (142/158 passing, not "most")
  • Explain why tests fail (not blockers vs actual bugs)

5. ROADMAP.md

Purpose: Future plans and feature ideas Audience: All stakeholders Content:

  • Planned features by phase
  • Timeline estimates
  • Decision points Update frequency: Quarterly or as priorities change

6. VECTOR_SEARCH_GUIDE.md

Purpose: Advanced feature documentation Audience: Advanced users Content:

  • How to set up vector search
  • Benefits and trade-offs
  • Configuration examples Update frequency: Rarely (stable feature)

Subdirectory Documentation

docs/guides/

Purpose: User-facing guides and tutorials Files:

  • DEMO_HIGHLIGHTS.md - Demo script and tuning parameters
  • Future: Custom template guides, troubleshooting, etc.

docs/sessions/

Purpose: Development session notes from AI coding assistants Naming: SESSION_[topic]_YYYY-MM-DD.md Content:

  • Date, duration, objectives
  • Work completed, files modified
  • Key insights, remaining work ⚠️ Do NOT include:
  • Project status (goes in IMPLEMENTATION_STATUS.md)
  • Test status (goes in TESTING_STATUS.md)

docs/archive/

Purpose: Outdated or superseded documentation preserved for reference Content: Old status reports, replaced guides Rule: Files here should have a clear replacement indicated in archive README

Rules for AI Agents

✅ DO

  1. Update IMPLEMENTATION_STATUS.md when completing features or modules
  2. Update TESTING_STATUS.md after running tests or fixing test failures
  3. Create session notes in docs/sessions/ for context preservation
  4. Ask before creating new .md files in root directory (usually not needed)
  5. Use checkboxes for trackable items: - [x] done, - [ ] pending
  6. Include specific metrics: "142/158 tests passing" not "most tests pass"

❌ DON'T

  1. Never create alternative status files (STATUS_v2.md, NEW_STATUS.md, etc.)
  2. Never create files like: CURRENT_STATUS.md, LATEST_PROGRESS.md, TEST_REPORT.md
  3. Don't duplicate information across multiple files
  4. Don't leave conflicting information (if you update one file, update all references)
  5. Don't put session notes in root (use docs/sessions/)
  6. Don't create status files without explicit human approval

When Status Changes

Feature Completed

# In IMPLEMENTATION_STATUS.md

### 1. GraphRAG Module ✅ COMPLETE
Fully migrated and functional:
- [x] entity_extractor.py - Entity extraction from natural language
- [x] query_builder.py - Template-based Cypher generation
- [x] query_engine.py - High-level query API

Tests Fixed

# In TESTING_STATUS.md

**Current Status**: 150/158 tests passing (95% pass rate)
**Test Coverage**: 88% (710/807 lines covered)

**Recent Improvements (2026-01-23)**:
- Fixed database connection tests (13/13 passing)
- Fixed LLM utility tests (9/9 passing)
- Remaining: 8 generator tests (mock setup issues)

Session Completed

# In docs/sessions/SESSION_test_fixes_2026-01-23.md

# Session Summary - Test Fixes
**Date**: 2026-01-23
**Duration**: 2 hours
**Objectives**: Fix remaining test failures

## Work Completed
- Fixed database tests: 10/13 → 13/13
- Fixed LLM tests: 4/9 → 9/9
...

Documentation Review Checklist

Before committing documentation changes, verify:

  • IMPLEMENTATION_STATUS.md has accurate percentage at top
  • TESTING_STATUS.md has current test counts
  • No conflicting status information across files
  • No duplicate .md files in root directory
  • Session notes in docs/sessions/ (not root)
  • Outdated files moved to docs/archive/
  • README.md links are valid

Benefits of This Convention

✅ Single source of truth - No conflicting information ✅ AI-agent friendly - Clear rules for where to update ✅ Human-friendly - One place to check status ✅ Maintainable - Structured, predictable organization ✅ Scalable - Subdirectories for growing content

Emergency: Too Many Files

If you find yourself with >10 .md files in root:

  1. Identify which are status reports → merge into IMPLEMENTATION_STATUS.md
  2. Identify which are test reports → merge into TESTING_STATUS.md
  3. Move session notes → docs/sessions/
  4. Move user guides → docs/guides/
  5. Move outdated docs → docs/archive/
  6. Update README.md to reflect new structure

Example: Bad vs Good

❌ Bad (What We Had Before)

Root directory:
- IMPLEMENTATION_STATUS.md (says 100% complete)
- MIGRATION_PROGRESS.md (says 40% complete)
- COMPLETION_SUMMARY.md (says 70% complete)
- READY_TO_USE.md (says 85% complete)
- TEST_STATUS.md (says 127 passing)
- TEST_FIX_STATUS.md (says 142 passing)
- TEST_COVERAGE_REPORT.md (coverage details)

Problem: Which is correct? AI agents and humans confused.

✅ Good (What We Have Now)

Root directory:
- README.md (main docs)
- IMPLEMENTATION_STATUS.md (97% complete ← single source of truth)
- TESTING_STATUS.md (142/158 passing ← single source of truth)
- QUICKSTART.md (getting started)
- ROADMAP.md (future plans)
- VECTOR_SEARCH_GUIDE.md (advanced feature)

docs/archive/:
- MIGRATION_PROGRESS.md (superseded)
- COMPLETION_SUMMARY.md (superseded)
- READY_TO_USE.md (superseded)
- [etc]

Benefit: Clear, unambiguous, maintainable.

Created: 2026-01-23 Last Updated: 2026-01-23 Version: 1.0