Document Guideline

Document Guideline

This skill instructs AI agents on how to maintain comprehensive documentation throughout the development lifecycle. It defines documentation standards that are enforced via pre-commit linting for structural requirements, while providing guidance on content quality and workflow integration.

Documentation Philosophy

Good documentation is:

• Comprehensive: Covers all code files, folders, and high-level designs
• Enforced: Structural requirements validated automatically via pre-commit linting
• Design-first: Documentation written before implementation (following TDD approach)
• Milestone-friendly: Documentation-code inconsistency acceptable during incremental development
• Self-descriptive: Each file, folder, and component documents its purpose and interfaces

Documentation Types

This project maintains three levels of documentation:

1. High-level design documents (docs/*) - Architecture and design decisions
2. Folder organization (folder README.md files) - Purpose and file organization
3. Code interface documentation (.md companions to source files) - External and internal APIs

High-Level Design Documentation

Location: docs/* directory

Purpose: Document architectural decisions, design rationale, and high-level project structure.

When to create/update:

• During planning phase (before implementation)
• When making architectural decisions
• When introducing new subsystems or major features
• When documenting workflows or processes

Not enforced by linting: Creating design documents requires human judgment about what constitutes a "high-level design" versus implementation details.

Content guidelines:

• Focus on the "why" (design rationale) not just the "what"
• Document alternatives considered and trade-offs
• Include diagrams, workflows, or examples where helpful
• Keep design docs synchronized with actual implementation

Examples of good design documents:

• docs/git-msg-tags.md - Documents commit message tag standards
• docs/developer.md - Developer workflow and contribution guidelines
• docs/options.md - SDK configuration options and usage

When NOT to create design docs:

• For simple implementation details (put in code .md files instead)
• For temporary decisions or experiments
• For information that duplicates existing documentation

Folder Organization Documentation

Requirement: Every folder (except hidden folders like .git) MUST have a README.md file.

Enforced by: Pre-commit linting (scripts/lint-documentation.sh)

Purpose: Document folder purpose and file organization so developers can quickly understand the codebase structure.

When to create:

• When creating a new folder in the project
• Before committing any code that introduces a new directory

Required content:

1. Folder purpose: What is this folder for? (1-2 sentences)
2. File organization: What types of files are in this folder?
3. Key files: Brief description of important files (optional)

Examples of good folder README.md:

# Skills Directory

This directory contains all Claude Code skills that define AI agent behavior.

## Organization

Each skill is in its own subdirectory with a `SKILL.md` file:
- `commit-msg/` - Skill for creating meaningful git commits
- `fork-dev-branch/` - Skill for creating development branches
- `milestone/` - Skill for incremental implementation with milestone commits

## Adding New Skills

Create a new subdirectory and add a `SKILL.md` file with frontmatter defining
the skill name and description.

Format flexibility:

• Can be brief (3-5 lines) for simple folders
• Can be detailed for complex subsystems
• Should reference key files if there are many files

Source Code Interface Documentation

Requirement: Every source code file MUST have a corresponding .md file documenting its interfaces.

File types requiring documentation (enforced by linting):

• Python: *.py → *.md
• C/C++: *.c, *.cpp, *.cxx, *.cc → *.md

Enforced by: Pre-commit linting (scripts/lint-documentation.sh)

Naming convention: Same prefix as source file

• foo.py → foo.md
• bar.cpp → bar.md
• baz.c → baz.md

Required sections:

1. External Interfaces (Public APIs)

Document all interfaces exposed to external callers:

• Public functions/methods with signatures
• Public classes/structures with key attributes
• Module-level exports or entry points
• Expected inputs and outputs
• Error conditions and exceptions

2. Internal Helpers (Private APIs)

Document internal implementation details:

• Private functions and their purpose
• Internal data structures
• Helper utilities
• Algorithms or complex logic explanations

Example interface documentation:

# validate_target_dir.sh

Script for validating target directories before SDK initialization.

## External Interface

### Command-line usage
```bash
./validate_target_dir.sh <target_dir> <mode>

Parameters:

• target_dir: Path to directory to validate
• mode: Either "init" or "update"

Exit codes:

• 0: Validation passed
• 1: Validation failed (directory issues)
• 2: Invalid arguments

Output: Error messages to stderr listing validation failures

Internal Helpers

check_directory_exists()

Validates that the target directory exists.

check_write_permissions()

Validates that the user has write access to the directory.

check_conflicting_files()

Scans for files that would conflict with SDK initialization. Returns list of conflicting file paths.

validate_init_mode()

Specific validation for "init" mode (directory must be empty or non-existent).

validate_update_mode()

Specific validation for "update" mode (directory must have existing SDK structure).

**When implementation changes**:
- Update interface documentation to match
- During milestones, temporary doc-code mismatch is acceptable (see below)
- Before final delivery, all documentation must match implementation

## Test Documentation

**Requirement**: Every test case **MUST** have documentation explaining what it tests.

**Enforced by**: Pre-commit linting (`scripts/lint-documentation.sh`)

**Format options**:
1. **Inline comments** within the test file (preferred for simple tests)
2. **Companion `.md` file** (for complex test suites)

**Required content**:
- What is being tested (feature or behavior)
- Expected outcome
- Any setup or preconditions

**Example with inline comments**:

```bash
#!/bin/bash
# Test suite for documentation linting
# Tests that the linter correctly identifies missing documentation

set -e

# Test 1: Linter passes with complete documentation
# Expected: Exit code 0, no errors
test_complete_documentation() {
    # Setup: Create temporary directory with all docs present
    ...
}

# Test 2: Linter fails when folder missing README.md
# Expected: Exit code 1, error message lists folder
test_missing_folder_readme() {
    ...
}

Example with companion .md file:

For test_documentation_lint.sh, create test_documentation_lint.md:

# Documentation Linter Test Suite

Tests for `scripts/lint-documentation.sh` to verify it correctly validates
documentation completeness.

## Test Cases

### test_complete_documentation
**Purpose**: Verify linter passes when all documentation is present
**Setup**: Temporary directory with source files and corresponding .md files
**Expected**: Exit code 0, no error output

### test_missing_folder_readme
**Purpose**: Verify linter catches folders without README.md
**Setup**: Create folder without README.md
**Expected**: Exit code 1, error message listing the folder

...

Linting check:

• For bash test files (test_*.sh), linter checks for either:
  • Inline comments following pattern # Test N: or # Test: or function comments
  • Companion .md file with same prefix

Documentation-Code Consistency During Milestones

Design-First TDD Workflow

This project follows strict design-first test-driven development:

1. Phase 1: Documentation - Update all relevant documentation first
2. Phase 2: Tests - Write test cases based on documentation
3. Phase 3: Implementation - Write code to make tests pass

Acceptable Documentation-Code Inconsistency

During milestone commits, documentation and code may be temporarily inconsistent:

Why this happens:

• Documentation describes the final intended state
• Implementation is incrementally catching up to match documentation
• Tests are written based on documentation (may not all pass yet)

When it's acceptable:

• During milestone commits: Documentation complete, implementation in progress
• On development branches: Work is ongoing, not ready for final delivery
• With explicit test status: Milestone commits show N/M tests passed

When it's NOT acceptable:

• Final delivery commits: All tests must pass, docs must match code
• Merging to main branch: Complete consistency required
• Production releases: Documentation must accurately reflect implementation

Pre-commit Linting and Milestones

The documentation linter (scripts/lint-documentation.sh) runs as part of the pre-commit hook and validates:

• All folders have README.md
• All source files have corresponding .md files
• All test files have documentation

Bypassing the linter:

For milestone commits where documentation is complete but implementation is incomplete:

git commit --no-verify -m "milestone: ..."

The --no-verify flag bypasses all pre-commit hooks, including:

• Documentation linting
• Test execution

IMPORTANT: Only bypass for milestone commits on development branches. Never bypass for final delivery commits or commits to main branch.

Milestone progression example:

Milestone 1: Documentation complete (bypass linting OK)
- All .md files created and document final interfaces
- Implementation: 0% complete
- Tests: 0/10 passed (expected, no implementation yet)
- Commit with: --no-verify

Milestone 2: Partial implementation (bypass linting OK)
- Documentation: Still accurate for final state
- Implementation: 60% complete
- Tests: 6/10 passed
- Commit with: --no-verify

Delivery: All tests pass (NO bypass)
- Documentation: Matches implementation exactly
- Implementation: 100% complete
- Tests: 10/10 passed
- Commit without: --no-verify (linter must pass)

Integration with Other Skills

This documentation guideline integrates with other project skills:

Integration with plan-guideline skill

When creating implementation plans, the plan-guideline skill references these documentation standards:

• Step 1 in plans should always be documentation updates
• Plans should list specific .md files to create/update
• Plans should note which documentation is enforced by linting

Integration with milestone skill

The milestone skill uses these guidelines for incremental development:

• Milestone 1 always creates documentation first
• --no-verify bypass acceptable for milestone commits
• Milestone commits track test progress (N/M tests passed)
• Final delivery requires all linting to pass

Integration with commit-msg skill

The commit-msg skill considers documentation standards:

• Commits updating only documentation use [docs] tag
• Milestone commits note test status in message
• Delivery commits confirm all lints pass

Summary

Enforced by linting (structural requirements):

• ✅ Folder README.md existence
• ✅ Source code .md file correspondence
• ✅ Test documentation presence

Guided by skill (content quality):

• High-level design document creation
• Interface documentation completeness
• Explanation clarity and usefulness

Workflow integration:

• Documentation written first (design-first TDD)
• Temporary doc-code mismatch OK during milestones
• All documentation must match code at delivery