# Documentation Reading Guide

This guide explains when Claude Code should read which documentation files. The `.claude/` directory follows a deliberate two-tier structure optimized for both thorough understanding and quick reference.

---

## Documentation Structure

| Directory | Purpose | When to Read |
|-----------|---------|--------------|
| `standards/` | **Authoritative reference docs** (MUST-READ) | At session start, read thoroughly |
| `knowledge/` | **Quick-lookup tips** indexed by topic | Reference as needed during tasks |

---

## Session Start: Read These First

**At the beginning of every Claude Code session, read these files IN ORDER:**

1. **`.claude/CLAUDE.md`** - Project-specific instructions and quick reference
2. **`.claude/standards/CLAUDE_CODE_RULES.md`** - Non-negotiable rules (~600 lines)
3. **`.claude/standards/ENGINEERING_STANDARDS.md`** - Coding standards (~550 lines)

These establish the foundational rules that govern all operations.

---

## Task-Based Documentation Lookup

### Before ANY Operation
| Task | Read This |
|------|-----------|
| Session start | `standards/CLAUDE_CODE_RULES.md`, `standards/ENGINEERING_STANDARDS.md` |
| Any code change | Verify branch (`.claude/CLAUDE.md` checklist) |
| Before `pip install` | `knowledge/python/virtual-environments.md` |

### Git Operations
| Task | Read This |
|------|-----------|
| Creating a branch | `knowledge/pr-feedback/branch-creation.md` |
| Making commits | `knowledge/git/atomic-commits.md`, `knowledge/git/commit-messages.md` |
| Creating a PR | `knowledge/git/pull-request-workflow.md`, `knowledge/git/pr-titles-and-descriptions.md` |

### PR Feedback Iteration
| Task | Read This |
|------|-----------|
| Classifying feedback | `knowledge/pr-feedback/priority-rules.md` |
| Determining intent | `knowledge/pr-feedback/intent-detection.md` |
| Handling conflicts | `knowledge/pr-feedback/conflict-handling.md` |
| Bot vs human feedback | `knowledge/pr-feedback/source-handling.md` |
| Before acting | `knowledge/pr-feedback/feedback-verification.md` |
| Full iteration workflow | `knowledge/pr-feedback/iterate-pr-feedback.md` |

### Python Development
| Task | Read This |
|------|-----------|
| Setting up venv | `standards/VIRTUAL_ENVIRONMENT_SETUP.md` |
| Quick venv reference | `knowledge/python/virtual-environments.md` |
| Type hints | `knowledge/python/type-hints.md` |

### Testing
| Task | Read This |
|------|-----------|
| Running tests | `knowledge/testing/pytest-basics.md` |
| Test organization | `knowledge/testing/test-structure.md` |

### Infrastructure
| Task | Read This |
|------|-----------|
| Understanding IaC | `knowledge/infrastructure/configuration-as-code.md` |
| Before deploying | `knowledge/infrastructure/financial-governance.md` |
| Pulumi changes | `knowledge/infrastructure/pulumi-guide.md` |
| Environment setup | `knowledge/infrastructure/environment-variables.md` |

### Documentation
| Task | Read This |
|------|-----------|
| Updating docs | `knowledge/documentation/keeping-docs-updated.md` |
| Doc automation | `standards/DOCUMENTATION_AUTOMATION.md` |

---

## Quick Reference vs Deep Read

### When to Read Thoroughly (standards/)
- **Session start** - Always read CLAUDE_CODE_RULES.md and ENGINEERING_STANDARDS.md
- **New project setup** - Read VIRTUAL_ENVIRONMENT_SETUP.md, SETTINGS_GUIDE.md
- **Major changes** - Re-read relevant standards before architectural decisions

### When to Scan Quickly (knowledge/)
- **Specific command needed** - Look up the exact git/pytest/etc command
- **Pattern reminder** - Quick check on commit message format
- **Troubleshooting** - Find the specific fix for a known issue

---

## File Size Guidelines

| Type | Max Lines | Purpose |
|------|-----------|---------|
| `standards/` files | ~600 | Complete reference, read once |
| `knowledge/` files | ~150 | Quick lookup, scan as needed |

If you need comprehensive understanding, read `standards/`.
If you need a quick command or pattern, check `knowledge/`.

---

## Related Files

### For Claude Code Configuration
- `.claude/settings.json` - Tool permissions and model settings
- `.claude/standards/SETTINGS_GUIDE.md` - Explains the settings

### For Slash Commands
- `.claude/commands/` - Custom slash commands
- `.claude/prompts/` - AI instruction templates

### For Automation
- `.claude/scripts/` - Helper scripts
- `.claude/hooks/` - Git and session hooks

---

## Summary

```
Session Start:
├── Read: CLAUDE.md → standards/CLAUDE_CODE_RULES.md → standards/ENGINEERING_STANDARDS.md
└── Then: Check venv, check branch, ready to work

During Tasks:
├── Quick lookup: knowledge/<topic>/<file>.md
└── Deep reference: standards/<file>.md

PR Iteration:
└── Read: knowledge/pr-feedback/ (all files for comprehensive iteration)
```

---

**Remember**: `standards/` = "read thoroughly once", `knowledge/` = "look up as needed"
