document-guideline

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

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

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:

```markdown

# Skills Directory

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

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

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

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:

```markdown

# validate_target_dir.sh

Script for validating target directories before SDK initialization.

Command-line usage

```bash

./validate_target_dir.sh

```

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

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

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:

```markdown

# Documentation Linter Test Suite

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

documentation completeness.

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

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:

```bash

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)

```

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

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