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