syntaxis/.claude/DOC_REVIEW_RULES.md

Documentation Review Rules

Standards for cleaning and maintaining documentation across all projects.

---

🎯 Core Rules

1. ❌ Remove Absolute User Paths

Rule: No hardcoded user home or development paths in documentation.

Pattern to Remove:

• /Users/Akasha/Development/<project>
• /Users/Akasha/Tools/...
• /Users/Akasha/.coder/...
• Any machine-specific absolute paths

Replacement:

• Use relative paths: cd vapora, ./scripts/, crates/
• Use home directory notation: ~/.config/, ~/projects/
• Use placeholders: <your-dev-directory>, <project-root>

Example:

# ❌ BAD
cd /Users/Akasha/Development/syntaxis
cargo build

# ✅ GOOD
# Navigate to project root
cargo build

---

2. ❌ No References to .claude or claude Directories

Rule: Do NOT mention .claude/, .claude/info/, or related directories in user-facing documentation.

Pattern to Remove:

• .claude/CLAUDE.md or CLAUDE.md references in README
• .claude/info/PHASE_X_COMPLETION.md links
• .claude/summaries/fase-X.md references
• .coder/ directory mentions (internal project tracking)
• "See CLAUDE.md for..." instructions
• References to internal Claude Code configuration

Replacement:

• Remove entirely from user-facing docs
• Keep only in internal/development documentation
• Link to public-facing docs: README.md, docs/ARCHITECTURE.md, etc.

Example:

# ❌ BAD
See `CLAUDE.md` for complete project overview
See `.claude/info/PHASE_9_COMPLETION.md` for details
See `.coder/summaries/fase-1-backend.md` for implementation

# ✅ GOOD
See `README.md` for project overview
See `docs/ARCHITECTURE.md` for system design
See `docs/QUICKSTART.md` for getting started

---

3. ❌ Remove Phase/Release References

Rule: No references to development phases, completion status, or internal timelines.

Pattern to Remove:

• "Phase 1-12", "Phase 8-9", "Phases 1-7"
• "Week 1-4", "Week 5-8", etc.
• Phase completion badges
• Phase-specific documentation links

Replacement:

• Describe functionality directly: "Advanced Features", "Core Capabilities"
• Remove phase-specific docs from user-facing tables
• Use feature-based organization

Example:

# ❌ BAD
## Phase 9: Advanced Resilience & Observability ✅
- Phase 9a: Real async SSH integration (8 tests)
- Phase 9b: Connection pooling (10 tests)

# ✅ GOOD
## Advanced Features
- Real async SSH integration
- Automatic connection pooling

---

4. ❌ Remove Test Coverage Metrics

Rule: Don't advertise specific test counts or coverage percentages in user-facing docs.

Pattern to Remove:

• "691+ tests passing"
• "332+ tests (100% pass rate)"
• "64 tests", "155/155 passing"
• Coverage percentages in badges
• Test count tables

Replacement:

• Use generic language: "Comprehensive tests", "Fully tested", "Complete test coverage"
• Keep detailed test info only in internal documentation

Example:

# ❌ BAD
[![Tests](https://img.shields.io/badge/tests-332%2B%20passing-brightgreen.svg)]

**Test Coverage**:
- TUI Tests: 52 passing ✅
- Dashboard Tests: 12 passing ✅
- Total: 64 tests

# ✅ GOOD
✅ **Comprehensive tests** — All critical paths tested
✅ **100% documented** — All public APIs documented with rustdoc

---

5. ❌ Remove Phase-Specific Documentation Links

Rule: Don't link to phase completion documents or internal tracking in README/docs.

Pattern to Remove:

• .coder/info/PHASE_9_COMPLETION.md
• .coder/info/README_PHASE_8.md
• .coder/summaries/fase-1-backend.md
• .coder/init/PHASE_1_COMPLETE.md

Keep:

• Main documentation: README.md, docs/ARCHITECTURE.md, docs/QUICKSTART.md
• User-facing guides only

Example:

# ❌ BAD
| Phase 8 Features | [.coder/info/README_PHASE_8.md](.coder/info/README_PHASE_8.md) |
| Phase 9 Details | [.coder/info/PHASE_9_COMPLETION.md](.coder/info/PHASE_9_COMPLETION.md) |

# ✅ GOOD
| Project Overview | [README.md](README.md) |
| System Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Installation Guide | [docs/docs/installation-guide.md](docs/docs/installation-guide.md) |

---

6. ❌ Remove Internal Tool Paths

Rule: Don't reference external tool paths in documentation.

Pattern to Remove:

• /Users/Akasha/Tools/doc-lifecycle-manager
• /Users/Akasha/Tools/tracking-manager
• /Users/Akasha/Tools/dev-system

Replacement:

• Generic reference: "External project", "Related project"
• Link to public repo if available

Example:

# ❌ BAD
**Project Location**: `/Users/Akasha/Tools/doc-lifecycle-manager`

# ✅ GOOD
**Project Location**: External project (doc-lifecycle-manager)

---

📋 Files to Review

Always Check These:

• ✅ README.md (root)
• ✅ QUICKSTART.md
• ✅ docs/*.md
• ✅ Root-level guide files (SETUP.md, DEPLOYMENT.md, etc.)

Exclude From Review:

• ❌ .claude/ directory (internal Claude Code instructions)
• ❌ .coder/ directory (internal project tracking)
• ❌ CLAUDE.md (internal instructions for Claude Code)
• ❌ DEPENDENCIES.md (dependency listing)
• ❌ guides/archive/ (historical reference)

---

🔍 Review Checklist

When reviewing documentation, check for:

Path Check

• No /Users/Akasha/Development/... paths
• No /Users/Akasha/Tools/... paths
• Uses relative paths: cd vapora, ./scripts/
• Uses home notation: ~/.config/, ~/projects/

Claude/Internal Check

• No .claude/ directory references
• No CLAUDE.md references
• No .coder/ directory references
• No "See CLAUDE.md" or similar instructions
• No Claude Code internal configuration mentioned

Phase Check

• No "Phase X" references in user-facing docs
• No "Week X-Y" timelines
• No phase completion badges
• No phase-specific documentation tables

Test Coverage Check

• No specific test count numbers ("332+ tests")
• No test pass rate percentages ("100% passing")
• Uses generic: "Comprehensive tests", "Fully tested"
• Test metrics only in internal documentation

Documentation Link Check

• No .coder/ links in README/docs
• No .claude/ links anywhere in user docs
• No internal phase completion files linked
• Only user-facing documentation listed
• Links are to main docs: README, QUICKSTART, ARCHITECTURE

Internal Tool Check

• No specific tool paths referenced
• External dependencies referenced generically
• Public repo links where available

---

📝 Examples by Project

✅ Correct Pattern - README.md

# Project Name

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)]
[![Status](https://img.shields.io/badge/status-production%20ready-brightgreen.svg)]

**Description** of what the project does without mentioning phases or test counts.

## Features

✅ **Feature Group 1**
- Feature detail
- Feature detail

✅ **Feature Group 2**
- Feature detail

## Quick Start

```bash
# Build the project
cargo build --release

Documentation

• Quick Start
• Architecture
• CLI Guide

### ✅ Correct Pattern - Code Blocks in Docs

```bash
# ✅ GOOD - Relative paths
cd project-name
cargo build --release

# ✅ GOOD - Home directory
cp configs/database-default.toml ~/.config/project/database.toml

# ✅ GOOD - Relative from root
cd crates/subproject
cargo test

---

🚀 How to Use These Rules

For Interactive Review:

# Check a markdown file against these rules
claude-code review-docs <file.md> --rules DOC_REVIEW_RULES.md

For Batch Review:

# Review all markdown in a directory
claude-code review-docs docs/ --rules DOC_REVIEW_RULES.md --recursive

In CI/CD:

# Example: pre-commit hook
- name: Review Documentation
  run: |
    claude-code review-docs README.md docs/ \
      --rules .claude/DOC_REVIEW_RULES.md \
      --fail-on-violations

---

📚 Related Documentation

• See individual project README for specific conventions
• See docs/ARCHITECTURE.md for technical details
• See docs/QUICKSTART.md for getting started

---

Version: 1.0 Last Updated: 2025-11-19 Status: Active - Use for all documentation reviews