# 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**:
```bash
# ❌ 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**:
```markdown
# ❌ 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**:
```markdown
# ❌ 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**:
```markdown
# ❌ 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**:
```markdown
# ❌ 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**:
```toml
# ❌ 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

```markdown
# 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](QUICKSTART.md)
- [Architecture](docs/ARCHITECTURE.md)
- [CLI Guide](docs/CLI_GUIDE.md)
```

### ✅ 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:
```bash
# Check a markdown file against these rules
claude-code review-docs <file.md> --rules DOC_REVIEW_RULES.md
```

### For Batch Review:
```bash
# Review all markdown in a directory
claude-code review-docs docs/ --rules DOC_REVIEW_RULES.md --recursive
```

### In CI/CD:
```yaml
# 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