conditional-docs-setup

name	conditional-docs-setup
description	Set up conditional documentation loading to prevent context pollution. Use when organizing project docs, implementing progressive disclosure, or reducing CLAUDE.md token consumption with on-demand loading.
allowed-tools	Read, Write

Conditional Docs Setup Skill

Set up conditional documentation loading to prevent context pollution.

When to Use

• Setting up documentation for a new project
• Reducing context pollution in existing projects
• Creating just-in-time documentation loading
• Optimizing agent context usage

Core Concept

Load documentation only when conditions match the current task.

"IMPORTANT: Only read the documentation if any one of the conditions match your task."

Setup Workflow

Step 1: Inventory Documentation

List all documentation files in the project:

# Find documentation files
find . -name "*.md" -path "*/docs/*"
find . -name "README*"
find . -name "CONTRIBUTING*"

Step 2: Categorize by Purpose

Group documentation by what it helps with:

Category	Examples
Setup	README, INSTALL, CONTRIBUTING
API	api-reference, endpoints, schemas
Architecture	design-docs, system-overview
Features	feature-specific guides
Testing	test-patterns, fixtures

Step 3: Define Loading Conditions

For each document, identify when it's relevant:

- docs/api-reference.md
  - Conditions:
    - When working with API endpoints
    - When adding new routes
    - When modifying request/response formats

- docs/database-schema.md
  - Conditions:
    - When modifying database tables
    - When adding new models
    - When writing migrations

Step 4: Create Conditional Docs File

Create the conditional documentation manifest:

# Conditional Documentation

This helps determine what documentation to read based on
the specific changes you need to make in the codebase.

IMPORTANT: Only read documentation if conditions match your task.

---

- README.md
  - Conditions:
    - When first understanding the project
    - When setting up the development environment

- docs/api/endpoints.md
  - Conditions:
    - When working with REST endpoints
    - When adding new API routes

- docs/database/schema.md
  - Conditions:
    - When modifying database tables
    - When creating migrations

- docs/testing/patterns.md
  - Conditions:
    - When writing new tests
    - When debugging test failures

Step 5: Integrate with Commands

Add conditional docs check to planning commands:

## Relevant Documentation

Read `.claude/commands/conditional_docs.md` to check if your task
requires additional documentation. If your task matches any conditions
listed, include those documentation files.

Condition Writing Guidelines

Be Specific

# Good - Specific conditions
- When adding a new API endpoint
- When modifying user authentication

# Bad - Vague conditions
- When doing backend work
- When coding

Cover Common Scenarios

- docs/auth.md
  - Conditions:
    - When implementing login/logout
    - When adding new permissions
    - When debugging auth issues
    - When integrating OAuth
    - When working with sessions

Avoid Overlap

Each document should have distinct conditions:

# Good - Distinct conditions
- api-reference.md → API endpoints
- database-schema.md → Database tables

# Bad - Overlapping conditions
- api-reference.md → When doing backend work
- database-schema.md → When doing backend work

Maintenance Workflow

When Documentation is Added

1. Create the new documentation file
2. Add entry to conditional_docs.md
3. Define appropriate loading conditions

When Documentation is Updated

1. Review existing conditions
2. Add/remove conditions as needed
3. Update documentation content

When Documentation is Removed

1. Delete the documentation file
2. Remove entry from conditional_docs.md

Template: Conditional Docs File

# Conditional Documentation

This helps determine what documentation to read based on
the specific changes you need to make in the codebase.

IMPORTANT: Only read documentation if conditions match your task.
Excessive documentation loading wastes context and reduces focus.

---

## Project Setup

- README.md
  - Conditions:
    - When first understanding the project
    - When setting up development environment
    - When learning available commands

## Backend

- docs/api/reference.md
  - Conditions:
    - When working with API endpoints
    - When adding new routes

- docs/database/schema.md
  - Conditions:
    - When modifying database tables
    - When writing migrations

## Frontend

- docs/components/guide.md
  - Conditions:
    - When creating new components
    - When modifying UI patterns

## Testing

- docs/testing/patterns.md
  - Conditions:
    - When writing tests
    - When debugging test failures

Memory References

• @conditional-docs-pattern.md - Full pattern documentation
• @minimum-context-principle.md - Why this matters
• @one-agent-one-purpose.md - Context affects focus

Version History

• v1.0.0 (2025-12-26): Initial release

---

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101