Read Documentation - Documentation Reading with Access Logging

When to Use This Skill

Use this skill when:

•You need to read project documentation from the ./docs folder
•You want to understand architecture, design decisions, or implementation details
•You're looking for guidance on how to implement something
•You need to learn about specific components or subsystems
•The user asks you to "check the docs" or "read the documentation"

Core Philosophy

Track What's Useful: Every documentation access is logged with a helpfulness score to understand which docs are valuable and which need improvement. When docs are missing or inadequate, request new documentation.

Documentation Location

All project documentation is located in:

code

./docs/

Browse this directory to find relevant documentation files.

Workflow

Phase 1: Find Relevant Documentation

•

List available docs

bash

find ./docs -type f -name "*.md" | sort

•
Search for relevant topics
bash
```
grep -r "keyword" ./docs/
```
Use Grep tool with appropriate patterns to find docs about specific topics.
•
Read the documentation Use the Read tool to view the documentation file.

Phase 2: Log Your Access

After reading a documentation file, you MUST append an access log entry to the end of that file.

Access Log Format:

code

2025-12-26T10:41:33Z +1 Accessed to understand rendering issues

Components:

•Timestamp: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ in UTC)
•Score: One of +1, +0, or -1
•Comment: Short description of why you accessed the doc

Scoring Guidelines:

•+1: The doc was helpful and contained the information you needed
•+0: The doc was somewhat relevant but didn't fully answer your question
•-1: The doc was not helpful, outdated, or contained incorrect information

Implementation: Use the helper script for atomic append operations:

bash

# Log documentation access
.claude/scripts/log-doc-access.sh ./docs/architecture.md +1 "Accessed to understand BVH acceleration structure"

The helper script handles UTC timestamp generation and atomic appending automatically.

Phase 3: Request Missing or Inadequate Documentation

If any of the following are true:

•No relevant documentation exists for your topic
•Documentation is incomplete and missing key information
•Documentation is out of date and no longer matches the code

Then you MUST add a documentation request to ./docs/documentation-requests.md.

When to Request Documentation:

•No docs found: You searched but couldn't find any documentation on the topic
•Incomplete docs: The doc exists but is missing critical details you need
•Outdated docs: The doc contradicts the actual code or describes old behavior
•Scored -1 or +0: If you logged a -1 or +0 score, consider whether a doc request is needed

Documentation Request Format:

code

## [Topic/Component Name]
- **Requested**: 2025-12-26T10:41:33Z
- **Requested by**: Agent working on [brief context]
- **Reason**: [Why documentation is needed]
- **Current state**: [None/Incomplete/Outdated]
- **Needed information**: [What should be documented]

Implementation: Use atomic append to add the request:

bash

cat >> ./docs/documentation-requests.md << 'EOF'

## BVH Split Algorithm Details
- **Requested**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
- **Requested by**: Agent debugging BVH performance issue
- **Reason**: Need detailed explanation of median-split algorithm implementation
- **Current state**: Incomplete (./docs/bvh.md mentions it but lacks details)
- **Needed information**: Step-by-step algorithm, when to use SAH vs median, performance characteristics
EOF

Important: If you logged access with -1 or +0 score, ALSO add a documentation request explaining what was missing.

Phase 4: Use the Information

Apply the information you learned from the documentation (or work around the gaps) to complete your task.

Complete Example - Documentation Found and Helpful

bash

# Step 1: Find relevant docs
find ./docs -type f -name "*.md"

# Step 2: Read the documentation
# (Use Read tool to view ./docs/rendering.md)

# Step 3: Log access
.claude/scripts/log-doc-access.sh ./docs/rendering.md +1 "Accessed to learn about progressive rendering passes"

# Step 4: Use the information in your work

Complete Example - Documentation Missing

bash

# Step 1: Search for docs on texture mapping
grep -r "texture" ./docs/

# Step 2: No relevant docs found!

# Step 3: Add documentation request
cat >> ./docs/documentation-requests.md << 'EOF'

## Texture Mapping Implementation
- **Requested**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
- **Requested by**: Agent implementing texture support
- **Reason**: No documentation exists on how textures are loaded and applied
- **Current state**: None
- **Needed information**: Texture loading, UV coordinate handling, sampling methods, supported formats
EOF

# Step 4: Inform user and proceed based on code inspection

Complete Example - Documentation Outdated

bash

# Step 1: Read ./docs/materials.md
# (Use Read tool)

# Step 2: Notice the doc describes old Material interface, but code has changed

# Step 3: Log access with -1 score
.claude/scripts/log-doc-access.sh ./docs/materials.md -1 "Information outdated, Material interface has changed"

# Step 4: Add documentation request
cat >> ./docs/documentation-requests.md << 'EOF'

## Material Interface (Update Needed)
- **Requested**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
- **Requested by**: Agent implementing new material type
- **Reason**: Documentation describes old interface that no longer matches code
- **Current state**: Outdated (./docs/materials.md)
- **Needed information**: Updated interface with new BSDF methods, PDF_f function, current material types
EOF

# Step 5: Proceed based on actual code

Access Log Examples

Helpful documentation (+1)

code

2025-12-26T10:41:33Z +1 Accessed to understand rendering issues
2025-12-26T11:15:20Z +1 Needed info on BVH construction algorithm
2025-12-26T14:22:45Z +1 Referenced for BDPT implementation details

Somewhat helpful (+0)

code

2025-12-26T10:45:12Z +0 Partial information about texture mapping
2025-12-26T13:30:00Z +0 Found overview but needed more detail

Note: Consider adding a documentation request for missing details

Not helpful (-1)

code

2025-12-26T11:00:00Z -1 Information was outdated, code has changed
2025-12-26T15:45:30Z -1 Doc didn't cover the topic I needed

Note: You MUST add a documentation request when logging -1

Important Notes

Atomic Appends

Always use atomic operations when appending:

•Use .claude/scripts/log-doc-access.sh for access logs (handles atomicity automatically)
•Use cat >> file << 'EOF' for multi-line documentation requests
•Do NOT read the file, modify it in memory, and write it back
•This prevents race conditions when multiple agents access docs simultaneously

Always Log Access

You MUST log every documentation access, even if:

•The doc wasn't helpful (use -1)
•You only skimmed it (use +0)
•You accessed it multiple times (log each access)

Always Request Missing Docs

You MUST add a documentation request when:

•No relevant docs exist
•Docs are incomplete (scored +0 or -1)
•Docs are outdated (scored -1)

Don't silently work around missing docs - request them so they can be created!

Comment Quality

Keep comments short but informative:

•✅ Good: "Accessed to understand BVH split algorithm"
•✅ Good: "Needed info on BDPT light path construction"
•✅ Good: "Checking how materials are defined"
•❌ Bad: "Read the doc"
•❌ Bad: "Information needed"

Timestamp Format

The helper script automatically generates timestamps in UTC timezone and ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). This ensures consistent timestamps regardless of system timezone.

Benefits of Access Logging and Requests

The system helps:

•Identify valuable documentation - High +1 scores show what's useful
•Find gaps - Documentation requests reveal missing topics
•Detect outdated docs - Multiple -1 scores and requests indicate problems
•Track usage patterns - See which topics are frequently consulted
•Prioritize documentation work - Most-requested docs should be written first
•Improve documentation - Comments reveal what people are looking for

Integration with Other Skills

This skill works well with:

•fix-bug skill: Read docs to understand how systems should work before debugging
•docs-maintainer agent: Access logs and requests guide documentation improvements
•Feature development: Consult architecture docs before implementing

Example Workflow - Complete Session

code

User: "How does the BDPT integrator handle light paths?"

1. Search for BDPT documentation:
   grep -r "BDPT" ./docs/

2. Found ./docs/integrators.md, read it:
   (Use Read tool)

3. Doc explains basic BDPT but lacks light path details:
   - Log access with +0 score:
     .claude/scripts/log-doc-access.sh ./docs/integrators.md +0 "Found BDPT overview but lacks light path details"

   - Add documentation request:
     cat >> ./docs/documentation-requests.md << 'EOF'

## BDPT Light Path Construction (Details Needed)
- **Requested**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
- **Requested by**: Agent explaining BDPT to user
- **Reason**: Documentation explains BDPT concept but not implementation details
- **Current state**: Incomplete (./docs/integrators.md)
- **Needed information**: Light path construction algorithm, connection strategies, MIS weight calculation, splat handling
EOF

4. Examine code to fill in gaps and explain to user

Common Pitfalls to Avoid

•Don't forget to log - Every read must be logged
•Don't forget to request - Missing/inadequate docs need requests
•Don't use non-atomic operations - Always use echo >> file or cat >> file
•Don't use local timezone - Always use UTC with date -u
•Don't write vague comments - Be specific about why you accessed the doc
•Don't skip logging on -1 - Negative scores are valuable feedback
•Don't skip requesting on -1/+0 - Document what was inadequate

Special Considerations

Multiple Accesses

If you access the same doc multiple times in one task, log each access:

bash

# First access - found overview
.claude/scripts/log-doc-access.sh ./docs/renderer.md +0 "Initial overview of renderer architecture"

# Second access - found specific detail
.claude/scripts/log-doc-access.sh ./docs/renderer.md +1 "Found tile worker pool implementation details"

Documentation Requests File

The ./docs/documentation-requests.md file may not exist initially. That's okay - your first append will create it:

bash

cat >> ./docs/documentation-requests.md << 'EOF'
# Documentation Requests

This file tracks requests for new or improved documentation.

## First Request Topic
...
EOF

Parallel Agents

The atomic append operations (helper script and cat >>) are safe for parallel access:

•Each agent's append is independent
•No need for locks or synchronization
•Logs and requests may be out of chronological order (that's okay)

Request Deduplication

Don't worry about duplicate requests - it's better to log multiple requests for the same missing doc than to miss documenting what's needed. Multiple requests indicate high priority!