Reference Document Architecture

Reference Document Architecture

Executive Summary

This document defines the complete reference document structure for the opinionated-python-development skill implementing Claude Code progressive disclosure pattern to optimize token usage while maintaining comprehensive guidance.

The architecture follows three-level loading:

• Level 2 (SKILL.md) core orchestration logic and decision trees
• Level 3 (Reference Documents) deep content loaded on-demand

Key Design Principles:

• Progressive disclosure minimize token consumption
• Modular architecture enable independent framework updates
• Scenario-specific loading only relevant content accessed
• Token budget management estimated sizes and optimization strategies
• Cross-reference integrity bidirectional linking with validation
• Version independence documents evolve independently

1. Complete File Structure

1.1 Directory Tree

python3-development/
├── metadata.json                           # Level 1: Skill metadata (1 KB)
├── SKILL.md                                # Level 2: Main orchestrator (15 KB)
│
├── docs/                                   # Level 3: Reference documents
│   │
│   ├── scenarios/                          # Scenario-specific guides
│   │   ├── cli-human-facing.md            # Typer + Rich (12 KB)
│   │   ├── cli-portable.md                # argparse (10 KB)
│   │   ├── tui-application.md             # Textual (15 KB) [FUTURE]
│   │   ├── module-library.md              # Modules and libraries (12 KB)
│   │   └── standalone-script.md           # PEP 723 scripts (10 KB)
│   │
│   ├── standards/                          # Universal standards
│   │   ├── type-hints.md                  # Python 3.11+ type annotations (8 KB)
│   │   ├── testing.md                     # pytest patterns (10 KB)
│   │   ├── validation.md                  # 6-layer validation pipeline (8 KB)
│   │   ├── documentation.md               # Docstring standards (6 KB)
│   │   ├── error-handling.md              # Exception patterns (7 KB)
│   │   ├── critical-code-criteria.md      # Mutation testing decision matrix (5 KB)
│   │   ├── requirements-schema.md         # Spec-analyst requirements format (6 KB)
│   │   ├── api-versioning.md              # API versioning strategy (5 KB)
│   │   ├── monitoring-baseline.md         # Monitoring requirements (6 KB)
│   │   └── dependency-versioning.md       # Dependency version pinning (5 KB)
│   │
│   ├── frameworks/                         # Framework-specific documentation
│   │   ├── typer-rich/
│   │   │   ├── standards.md               # MUST/NEVER requirements (10 KB)
│   │   │   ├── patterns.md                # Recommended patterns (15 KB)
│   │   │   ├── examples.md                # Complete working examples (12 KB)
│   │   │   └── integration-guide.md       # Integration with testing/validation (8 KB)
│   │   │
│   │   ├── argparse/
│   │   │   ├── standards.md               # MUST/NEVER requirements (8 KB)
│   │   │   ├── patterns.md                # Recommended patterns (10 KB)
│   │   │   ├── examples.md                # Complete working examples (10 KB)
│   │   │   └── integration-guide.md       # Integration with testing/validation (7 KB)
│   │   │
│   │   └── textual/                        # [FUTURE]
│   │       ├── standards.md               # MUST/NEVER requirements (12 KB)
│   │       ├── patterns.md                # Recommended patterns (18 KB)
│   │       ├── examples.md                # Complete working examples (15 KB)
│   │       └── integration-guide.md       # Integration with testing/validation (10 KB)
│   │
│   ├── processes/                          # Workflows and methodologies
│   │   ├── pep723-workflow.md             # 6-step PEP 723 creation (8 KB)
│   │   ├── tdd-workflow.md                # Test-driven development (7 KB)
│   │   ├── linting-resolution.md          # 9-step systematic linting resolution (10 KB)
│   │   ├── spec-chain.md                  # Requirements → Planning workflow (9 KB)
│   │   ├── code-review-workflow.md        # Create → Review → Lint → Architecture (8 KB)
│   │   ├── universal-dev-workflow.md      # Research → Analyze → Implement → Verify (7 KB)
│   │   └── framework-addition.md          # Adding new frameworks template (10 KB)
│   │
│   ├── tools/                              # Tool registry and usage
│   │   ├── development-tools.md           # uv ruff mypy pyright (10 KB)
│   │   ├── testing-tools.md               # pytest ecosystem (12 KB)
│   │   ├── cli-frameworks.md              # Framework comparison matrix (8 KB)
│   │   ├── libraries.md                   # Supporting libraries (datasette arrow fabric) (10 KB)
│   │   ├── mcp-tools.md                   # MCP tools for research (8 KB)
│   │   └── validation-tools.md            # validate_pep723 pre-commit (7 KB)
│   │
│   └── templates/                          # Code templates and scaffolding
│       ├── pep723/
│       │   ├── cli-tool-typer.py          # Typer + Rich CLI template (3 KB)
│       │   ├── cli-tool-argparse.py       # argparse CLI template (2 KB)
│       │   ├── data-processor.py          # Data processing script template (2.5 KB)
│       │   └── api-client.py              # API client script template (2.5 KB)
│       │
│       ├── testing/
│       │   ├── conftest.py                # pytest configuration (2 KB)
│       │   ├── test-template.py           # AAA pattern test template (2 KB)
│       │   └── fixture-examples.py        # Common fixture patterns (3 KB)
│       │
│       └── packaging/
│           ├── pyproject.toml             # Package configuration template (2 KB)
│           ├── src-layout.txt             # Directory structure guide (1 KB)
│           └── .pypirc.template           # Publishing configuration (1 KB)
│
├── commands/                               # Slash commands (optional CLI interface)
│   ├── new-cli-tool.md                    # /new-cli-tool command (4 KB)
│   ├── add-pep723.md                      # /add-pep723 command (3 KB)
│   ├── validate-script.md                 # /validate-script command (3 KB)
│   └── review-code.md                     # /review-code command (4 KB)
│
└── skill-metadata/                         # Skill infrastructure (existing)
    ├── taxonomy.md                         # Organizational structure (50 KB)
    ├── pattern-extraction.md               # Cross-cutting analysis (100 KB)
    ├── PRD.md                             # Product requirements (25 KB)
    ├── NFR.md                             # Non-functional requirements (25 KB)
    ├── CHANGELOG.md                        # Version history (growing)
    ├── gap-tracking.yml                    # Gap resolution tracking (2 KB)
    └── discovery/                          # Source discovery reports (13 files)
        └── [13 discovery reports]          # ~30 KB each

1.2 Token Budget Analysis

Total Documentation Size: ~480 KB (120000 tokens estimated)

By Category:

• Level 1 Metadata: 1 KB (<250 tokens)
• Level 2 Orchestrator: 15 KB (~3750 tokens)
• Scenarios: 59 KB (~14750 tokens)
• Standards: 66 KB (~16500 tokens)
• Frameworks: 145 KB (~36250 tokens)
• Processes: 59 KB (~14750 tokens)
• Tools: 55 KB (~13750 tokens)
• Templates: 20 KB (~5000 tokens)
• Infrastructure: 200 KB (~50000 tokens)

Performance Compliance (NFR-PERF-3):

• Requirement: Total skill documentation <300000 tokens
• Actual: ~120000 tokens (40% of budget)
• Status: PASS ✅

Progressive Loading Efficiency (NFR-PERF-4):

• Simple CLI tool creation: <75 KB target <100 KB actual (PASS ✅)
  • Load: metadata.json (1 KB) + SKILL.md (15 KB) + cli-human-facing.md (12 KB) + typer-rich/standards.md (10 KB) + pep723-workflow.md (8 KB) + cli-tool-typer.py (3 KB) = 49 KB
• Code review: <60 KB target <50 KB actual (PASS ✅)
  • Load: metadata.json (1 KB) + SKILL.md (15 KB) + validation.md (8 KB) + type-hints.md (8 KB) + testing.md (10 KB) = 42 KB
• Linting resolution: <90 KB target <75 KB actual (PASS ✅)
  • Load: metadata.json (1 KB) + SKILL.md (15 KB) + linting-resolution.md (10 KB) + type-hints.md (8 KB) + development-tools.md (10 KB) + mcp-tools.md (8 KB) = 52 KB

2. Document Templates

2.1 Scenario Document Template

File: docs/scenarios/{scenario-name}.md

Structure:

---
title: "{Scenario Name}"
category: scenarios
scenario: [scenario-id]
python_versions: [3.11, 3.12, 3.13, 3.14]
dependencies: [list of required tools]
related_docs:
  - @docs/frameworks/{framework}/standards.md
  - @docs/standards/type-hints.md
  - @docs/standards/testing.md
  - @docs/processes/universal-dev-workflow.md
version: "1.0.0"
last_updated: "2025-10-21"
---

# {Scenario Name}

## Quick Reference (TL;DR)

[3-5 bullet points summarizing key requirements]

**When to use**: [One sentence describing when this scenario applies]

**Core requirements**:

- [MUST requirement 1]
- [MUST requirement 2]
- [NEVER requirement 1]

**Estimated reading time**: [X minutes]

---

## When to Use This Guide

### Decision Criteria

Use this scenario when:

- [Criterion 1 with yes/no test]
- [Criterion 2 with yes/no test]
- [Criterion 3 with yes/no test]

Do NOT use when:

- [Anti-criterion 1]
- [Anti-criterion 2]

### Decision Flowchart

```mermaid
[Flowchart showing decision path to this scenario]
```

````markdown
**Related scenarios**: [Links to alternative/related scenarios]

---

## Core Requirements (MUST/NEVER)

### MUST Requirements

**[Requirement Category 1]**:

- MUST [specific requirement]
  - Rationale: [Why this is required]
  - Evidence: @[source-document]#[section]
  - Validation: [How to verify compliance]

**[Requirement Category 2]**:

- MUST [specific requirement]
  - Rationale: [Why this is required]
  - Evidence: @[source-document]#[section]
  - Validation: [How to verify compliance]

### NEVER Requirements

- NEVER [prohibited action]
  - Rationale: [Why this is prohibited]
  - Alternative: [What to do instead]
  - Evidence: @[source-document]#[section]

---

## Recommended Patterns

### Pattern 1: [Pattern Name]

**Purpose**: [What this pattern achieves]

**When to use**: [Specific circumstances]

**Example**:

```python
# Complete working example
```

**Explanation**: [Step-by-step breakdown]

**Testing**:

```python
# Test case for this pattern
```

**Evidence**: @pattern-extraction.md#L[lines]

---

## Complete Examples

### Example 1: [Example Title]

**Scenario**: [Specific use case]

**Requirements**:

- [Requirement 1]
- [Requirement 2]

**Solution**:

```python
[Complete working code with PEP 723 metadata if applicable]
```

**Validation**:

```bash
# Commands to validate this example
```

**Expected Output**:

```text
[What success looks like]
```

---

## Common Pitfalls

### Pitfall 1: [Common Mistake]

**Symptom**: [How this manifests]

**Root Cause**: [Why developers make this mistake]

**Solution**: [Correct approach]

**Prevention**: [How to avoid in future]

---

## Related Resources

### Standards

- @docs/standards/type-hints.md - Type annotation requirements
- @docs/standards/testing.md - Testing standards
- @docs/standards/validation.md - Validation pipeline

### Frameworks

- @docs/frameworks/{framework}/standards.md - Framework-specific requirements

### Processes

- @docs/processes/universal-dev-workflow.md - General development workflow

### Tools

- @docs/tools/{tool-category}.md - Required tools for this scenario

---

## Validation Checklist

Before delivery, verify:

- [ ] All MUST requirements satisfied
- [ ] Zero NEVER violations
- [ ] Type hints: mypy --strict passes
- [ ] Linting: ruff check passes (zero suppressions)
- [ ] Testing: pytest --cov-fail-under=80 passes
- [ ] Documentation: All public APIs have Google-style docstrings
- [ ] [Scenario-specific check 1]
- [ ] [Scenario-specific check 2]

---

**Document Metadata**:

- Category: scenarios
- Estimated tokens: [~X000]
- Dependencies: [List of documents this references]
- Reverse dependencies: [Documents that reference this]
- Last validated: [Date all examples tested]
````

2.2 Standards Document Template

File: docs/standards/{standard-name}.md

Structure:

---
title: "{Standard Name}"
category: standards
applies_to: [all | cli | library | script]
python_versions: [3.11, 3.12, 3.13, 3.14]
related_docs:
  - @docs/scenarios/[related-scenarios].md
  - @docs/tools/[related-tools].md
version: "1.0.0"
last_updated: "2025-10-21"
---

# {Standard Name}

## Quick Reference

**Applies to**: [All scenarios | Specific scenarios]

**Core Rule**: [One-sentence summary of standard]

**Validation**: [Tool/command to verify compliance]

---

## Standard Definition

### What This Standard Requires

[Detailed explanation of the standard]

**Evidence**:

- PEP [number]: [PEP title and key points]
  - URL: https://peps.python.org/pep-[number]/
- @pattern-extraction.md#L[lines]: [Pattern evidence]
- @taxonomy.md#L[lines]: [Taxonomy reference]

### Rationale

[Why this standard exists and its benefits]

**Impact**:

- Developer experience: [How this helps developers]
- Code quality: [How this improves code]
- Tooling support: [How tools leverage this]

---

## Requirements

### MUST Requirements

**Requirement 1**: [Specific requirement]

- Applies to: [Scope]
- Validation: [How to check]
- Violation consequence: [What breaks if violated]

**Requirement 2**: [Specific requirement]

- Applies to: [Scope]
- Validation: [How to check]
- Violation consequence: [What breaks if violated]

### NEVER Requirements

**Prohibition 1**: [What is forbidden]

- Alternative: [What to do instead]
- Rationale: [Why this is prohibited]
- Detection: [How to find violations]

---

## Before and After Examples

### Example 1: [Common Scenario]

**Before (Non-compliant)**:

```python
# Code violating standard
```

Issues:

• [Issue 1]
• [Issue 2]

After (Compliant):

# Code following standard

Improvements:

• [Improvement 1]
• [Improvement 2]

Tool Configuration

Enforcement Tools

Tool 1: [Tool Name]:

# pyproject.toml or configuration file
[tool.toolname]
option = "value"

Tool 2: [Tool Name]:

# Command-line usage
tool-name --flag value

Common Violations and Fixes

Violation 1: [Violation Pattern]

Detection:

# How to detect this violation

Error Message:

[Typical error message]

Fix:

# Corrected code

Migration Guide

From Legacy Pattern

Legacy Pattern (Python 3.8-3.10):

# Old approach

Modern Pattern (Python 3.11+):

# New approach

Migration Steps:

1. [Step 1]
2. [Step 2]
3. [Validation step]

Validation Checklist

• All code follows standard requirements
• Zero violations detected by validation tools
• Migration complete from legacy patterns
• Tool configuration applied
• Pre-commit hooks configured

Document Metadata:

• Category: standards
• Universal: [yes/no]
• Enforcement level: MUST/SHOULD/MAY
• Validation tools: [List of tools]

### 2.3 Framework Document Template

**File**: docs/frameworks/{framework-name}/standards.md

**Structure**:
```markdown
---
title: "{Framework Name} Standards"
category: frameworks
framework: {framework-id}
version_required: "{version}"
python_versions: [3.11, 3.12, 3.13, 3.14]
scenario: [scenario-id]
related_docs:
  - @docs/scenarios/{scenario}.md
  - @docs/standards/type-hints.md
  - @docs/standards/testing.md
version: "1.0.0"
last_updated: "2025-10-21"
---

# {Framework Name} Standards

## Quick Reference

**Framework**: {Framework Name}
**Version**: {Required Version}
**Use Case**: [When to use this framework]
**Installation**: `uv pip install {framework-name}>={version}`

**Core Requirements**:
- [MUST requirement 1]
- [MUST requirement 2]
- [NEVER requirement 1]

---

## Framework Overview

### When to Use {Framework Name}

Use this framework when:
- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

Do NOT use when:
- [Anti-criterion 1]
- [Anti-criterion 2]

**Alternative frameworks**: [List with comparison]

---

## Installation and Setup

### Installation

**PEP 723 Script**:
```python
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "{framework-name}>={version}",
# ]
# ///

Package (pyproject.toml):

[project]
dependencies = [
    "{framework-name}>={version}",
]

Configuration

Required Configuration:

# Configuration code

Optional Configuration:

# Optional enhancements

MUST Requirements

Requirement 1: [Requirement Name]

Rule: MUST [specific requirement]

Rationale: [Why this is required]

Example:

# Compliant code

Validation:

# How to verify

Evidence: @pattern-extraction.md#L[lines]

NEVER Requirements

Prohibition 1: [Prohibition Name]

Rule: NEVER [prohibited action]

Rationale: [Why this is prohibited]

Alternative: [What to do instead]

Detection:

# How to detect violations

Core Patterns

Pattern 1: [Pattern Name]

Purpose: [What this accomplishes]

Implementation:

# Complete working pattern

Testing:

# How to test this pattern

Common Variations:

• [Variation 1]
• [Variation 2]

Integration with Universal Standards

Type Annotations

[How this framework integrates with type hints standard]

Example:

# Framework-specific typing patterns

Testing

[How to test code using this framework]

Example:

# Test patterns for this framework

Validation

[How validation tools work with this framework]

Configuration:

# Framework-specific validation config

Common Pitfalls

Pitfall 1: [Common Mistake]

Problem: [What goes wrong]

Solution: [Correct approach]

Prevention: [How to avoid]

Best Practices

1. [Best practice 1]

   • Rationale: [Why]
   • Example: [Code example]

2. [Best practice 2]

   • Rationale: [Why]
   • Example: [Code example]

Version Compatibility

External Resources

• Official Documentation: [URL]
• GitHub Repository: [URL]
• Issue Tracker: [URL]
• Examples Repository: [URL]

Document Metadata:

• Category: frameworks
• Framework: {framework-name}
• Required Version: {version}
• Isolated from other frameworks: [yes/no]

### 2.4 Process Document Template

**File**: docs/processes/{process-name}.md

**Structure**:
```markdown
---
title: "{Process Name}"
category: processes
applies_to: [scenarios or "all"]
related_docs:
  - @docs/scenarios/[related-scenarios].md
  - @docs/tools/[tools-used].md
version: "1.0.0"
last_updated: "2025-10-21"
---

# {Process Name}

## Quick Reference

**Purpose**: [One-sentence process description]

**When to use**: [Circumstances requiring this process]

**Duration**: [Estimated time]

**Prerequisites**:
- [Prerequisite 1]
- [Prerequisite 2]

---

## Process Overview

### Objectives

**Primary Goal**: [Main outcome]

**Secondary Goals**:
- [Goal 1]
- [Goal 2]

### Success Criteria

Process succeeds when:
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

---

## Process Steps

### Phase 1: [Phase Name]

**Objective**: [What this phase accomplishes]

**Duration**: [Time estimate]

**Steps**:

**Step 1.1: [Step Name]**
- Action: [What to do]
- Tools: [Tools needed]
- Output: [What is produced]
- Validation: [How to verify]

**Step 1.2: [Step Name]**
- Action: [What to do]
- Tools: [Tools needed]
- Output: [What is produced]
- Validation: [How to verify]

**Phase 1 Deliverables**:
- [Deliverable 1]
- [Deliverable 2]

### Phase 2: [Phase Name]

[Same structure as Phase 1]

---

## Workflow Diagram

```mermaid
graph TD
    Start([Start Process]) --> Step1[Step 1]
    Step1 --> Decision{Decision Point?}
    Decision -->|Yes| Step2A[Option A]
    Decision -->|No| Step2B[Option B]
    Step2A --> End([Process Complete])
    Step2B --> End

Tools Required

Tool 1: [Tool Name]

Purpose: [Why this tool is needed]

Installation: [How to install]

Usage:

# Command examples

Configuration: @docs/tools/{tool-category}.md

Examples

Example 1: [Example Scenario]

Context: [Situation requiring this process]

Execution:

# Commands executed

Output:

# Expected results

Validation:

# Verification commands

Common Issues

Issue 1: [Common Problem]

Symptom: [How to recognize]

Root Cause: [Why this happens]

Solution: [How to resolve]

Prevention: [How to avoid]

Process Variations

Variation 1: [Scenario-Specific Variant]

When to use: [Circumstances]

Differences from standard process:

• [Difference 1]
• [Difference 2]

Modified steps: [Which steps change]

Quality Gates

Before completing process:

• All required steps executed
• All deliverables produced
• Validation checks pass
• Documentation complete
• Review completed (if applicable)

Related Processes

• @docs/processes/{related-process}.md - [Relationship]
• @docs/processes/{complementary-process}.md - [Relationship]

Document Metadata:

• Category: processes
• Estimated duration: [time]
• Complexity: [low/medium/high]
• Prerequisites: [list]

### 2.5 Tool Document Template

**File**: docs/tools/{tool-category}.md

**Structure**:
```markdown
---
title: "{Tool Category} Tools"
category: tools
related_docs:
  - @docs/standards/validation.md
  - @docs/scenarios/[scenarios-using-these-tools].md
version: "1.0.0"
last_updated: "2025-10-21"
---

# {Tool Category} Tools

## Quick Reference

**Category**: {Tool Category}

**Tools in this category**:
- [Tool 1] - [One-line description]
- [Tool 2] - [One-line description]
- [Tool 3] - [One-line description]

**Installation summary**:
```bash
uv pip install {tool1} {tool2} {tool3}

Tool 1: {Tool Name}

Overview

Purpose: [What this tool does]

Use Cases:

• [Use case 1]
• [Use case 2]

Required by: [Scenarios requiring this tool]

Installation

via uv (recommended):

uv pip install {tool-name}

via pip:

pip install {tool-name}

Version requirement: {version-spec}

License: {license-type}

Configuration

pyproject.toml:

[tool.{tool-name}]
option1 = "value1"
option2 = true

Command-line:

{tool-name} --option value

Usage

Basic usage:

# Simple command
{tool-name} <arguments>

Common patterns:

# Pattern 1: [Description]
{tool-name} --flag1 --flag2 arg

# Pattern 2: [Description]
{tool-name} --different-flags arg

Integration with other tools:

# Chaining tools
{tool-name} | other-tool

Examples

Example 1: [Scenario]:

# Command
{tool-name} --specific-option value

# Expected output
[Output description]

Example 2: [Scenario]:

# Python API usage
from {tool_name} import feature
feature.method(args)

Troubleshooting

Issue 1: [Common Problem]:

• Symptom: [What you see]
• Cause: [Why it happens]
• Solution: [How to fix]

External Resources

• Official Documentation: [URL]
• GitHub Repository: [URL]
• Issue Tracker: [URL]

Tool Comparison Matrix

Integration Patterns

Pattern 1: Pre-commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: { repository-url }
    rev: { version }
    hooks:
      - id: { tool-name }
        args: [--flag]

Pattern 2: CI/CD Pipeline

# .gitlab-ci.yml or .github/workflows/
steps:
  - name: Run {tool-name}
    run: {tool-name} --ci-mode

Document Metadata:

• Category: tools
• Tools documented: [count]
• Installation verified: [date]

---

## 3. Progressive Loading Sequences

### 3.1 Loading Sequence Flowchart

```mermaid
graph TD
    UserQuery[User Query] --> LoadMetadata[Load metadata.json<br/>Level 1: <1 KB]
    LoadMetadata --> LoadOrchestrator[Load SKILL.md<br/>Level 2: ~15 KB]
    LoadOrchestrator --> DetermineScenario{Determine<br/>Scenario}

    DetermineScenario -->|CLI Human-Facing| LoadCLI[Load CLI Scenario Docs]
    DetermineScenario -->|Portable Script| LoadPortable[Load Portable Docs]
    DetermineScenario -->|Library| LoadLibrary[Load Library Docs]
    DetermineScenario -->|PEP 723 Script| LoadPEP723[Load PEP 723 Docs]

    LoadCLI --> LoadCLIDocs[1. cli-human-facing.md<br/>2. typer-rich/standards.md<br/>3. pep723-workflow.md<br/>4. validation.md]
    LoadPortable --> LoadPortableDocs[1. cli-portable.md<br/>2. argparse/standards.md<br/>3. validation.md]
    LoadLibrary --> LoadLibraryDocs[1. module-library.md<br/>2. testing.md<br/>3. validation.md<br/>4. api-versioning.md]
    LoadPEP723 --> LoadPEP723Docs[1. standalone-script.md<br/>2. pep723-workflow.md<br/>3. validation.md]

    LoadCLIDocs --> LoadTemplates{Need<br/>Templates?}
    LoadPortableDocs --> LoadTemplates
    LoadLibraryDocs --> LoadTemplates
    LoadPEP723Docs --> LoadTemplates

    LoadTemplates -->|Yes| FetchTemplates[Load relevant templates<br/>Level 3: 2-3 KB each]
    LoadTemplates -->|No| ExecuteTask[Execute Task]
    FetchTemplates --> ExecuteTask

    ExecuteTask --> Validate[Run Validation Pipeline]
    Validate --> DeliverResult[Deliver Result]

3.2 Common Query Loading Patterns

Query: "Create a new CLI tool with Typer and Rich"

Loading Sequence:

1. metadata.json (1 KB) - Skill identification
2. SKILL.md (15 KB) - Routing logic determines "Human-Facing CLI"
3. docs/scenarios/cli-human-facing.md (12 KB) - Scenario guide
4. docs/frameworks/typer-rich/standards.md (10 KB) - Framework requirements
5. docs/processes/pep723-workflow.md (8 KB) - Creation workflow
6. docs/templates/pep723/cli-tool-typer.py (3 KB) - Code template

Total Loaded: 49 KB (~12250 tokens) NFR Target: <75 KB Status: PASS ✅ (66% of budget)

Execution Time (NFR-PERF-1):

• Metadata load: <1s
• SKILL.md + routing: <2s
• Scenario + framework docs: <3s
• Templates: <1s
• Total: <7s (target <6s - MARGINAL ⚠️)

Optimization: Cache SKILL.md after first load reduce to <6s total

Query: "Fix type checking errors in my code"

Loading Sequence:

1. metadata.json (1 KB) - Skill identification
2. SKILL.md (15 KB) - Routing to validation/type-checking
3. docs/standards/type-hints.md (8 KB) - Type annotation standards
4. docs/processes/linting-resolution.md (10 KB) - Resolution workflow
5. docs/tools/development-tools.md (10 KB) - mypy pyright usage

Total Loaded: 44 KB (~11000 tokens) NFR Target: <60 KB Status: PASS ✅ (73% of budget)

Execution Time: <5s (well within target)

Query: "Add comprehensive tests to my module"

Loading Sequence:

1. metadata.json (1 KB) - Skill identification
2. SKILL.md (15 KB) - Routing to testing
3. docs/standards/testing.md (10 KB) - Testing standards
4. docs/processes/tdd-workflow.md (7 KB) - TDD process
5. docs/tools/testing-tools.md (12 KB) - pytest ecosystem
6. docs/templates/testing/conftest.py (2 KB) - Configuration template
7. docs/templates/testing/test-template.py (2 KB) - Test template

Total Loaded: 49 KB (~12250 tokens) NFR Target: <100 KB Status: PASS ✅ (49% of budget)

Execution Time: <6s

Query: "Review my code for quality issues"

Loading Sequence:

1. metadata.json (1 KB) - Skill identification
2. SKILL.md (15 KB) - Routing to code review
3. docs/standards/validation.md (8 KB) - Validation pipeline
4. docs/standards/type-hints.md (8 KB) - Type standards
5. docs/standards/testing.md (10 KB) - Test standards
6. docs/standards/documentation.md (6 KB) - Docstring standards

Total Loaded: 48 KB (~12000 tokens) NFR Target: <60 KB Status: PASS ✅ (80% of budget)

Execution Time: <5s

Query: "Plan architecture for new Python project"

Loading Sequence:

1. metadata.json (1 KB) - Skill identification
2. SKILL.md (15 KB) - Routing to spec-chain
3. docs/processes/spec-chain.md (9 KB) - Requirements workflow
4. docs/scenarios/module-library.md (12 KB) - Library guidance
5. docs/standards/api-versioning.md (5 KB) - API standards
6. docs/standards/monitoring-baseline.md (6 KB) - Monitoring requirements
7. docs/tools/cli-frameworks.md (8 KB) - Framework comparison

Total Loaded: 56 KB (~14000 tokens) NFR Target: <200 KB (project planning allocated more budget) Status: PASS ✅ (28% of budget)

Execution Time: <6s

3.3 Caching Strategy

Claude Code Caching Behavior (assumed):

• Recently accessed documents remain in context
• Frequently accessed documents cached across sessions
• Cache invalidation on document updates

Optimization Strategy:

Tier 1: Always Cache (accessed in 80%+ queries):

• metadata.json (1 KB)
• SKILL.md (15 KB)
• docs/standards/validation.md (8 KB)
• docs/standards/type-hints.md (8 KB)

Total Tier 1: 32 KB - Keep in hot cache

Tier 2: Scenario Cache (accessed for specific scenarios):

• docs/scenarios/cli-human-facing.md (12 KB) - Most common scenario
• docs/frameworks/typer-rich/standards.md (10 KB) - Most common framework
• docs/processes/pep723-workflow.md (8 KB) - Common workflow

Total Tier 2: 30 KB - Cache when scenario active

Tier 3: On-Demand (less frequent access):

• All other documentation
• Load as needed clear from cache after use

Performance Impact:

• Cold start (no cache): 5-7s
• Warm cache (Tier 1): 3-4s
• Hot cache (Tier 1 + Tier 2): 2-3s

NFR Compliance: Warm cache achieves <6s target ✅

4. Cross-Reference Strategy

4.1 Reference Types

@ File References:

@docs/scenarios/cli-human-facing.md - Full document reference @docs/standards/type-hints.md#python-311-generics - Section reference @pattern-extraction.md#L429-L461 - Line range reference

Anchor Links:

[See Type Hints Standard](#type-hints-standard) - Internal document link [Related Process](../processes/tdd-workflow.md#red-phase) - Cross-document section link

Bidirectional Linking: Every reference MUST have reverse reference in target document

Example:

# In docs/scenarios/cli-human-facing.md

Related frameworks: @docs/frameworks/typer-rich/standards.md

# In docs/frameworks/typer-rich/standards.md

Used by scenarios: @docs/scenarios/cli-human-facing.md

4.2 Cross-Reference Map

graph TD
    SKILL[SKILL.md] --> Scenarios[docs/scenarios/]
    SKILL --> Standards[docs/standards/]
    SKILL --> Processes[docs/processes/]

    Scenarios --> Frameworks[docs/frameworks/]
    Scenarios --> Standards
    Scenarios --> Processes
    Scenarios --> Templates[docs/templates/]

    Frameworks --> Standards
    Frameworks --> Tools[docs/tools/]
    Frameworks --> Templates

    Processes --> Standards
    Processes --> Tools
    Processes --> Templates

    Standards -.->|validates| Scenarios
    Tools -.->|used by| Frameworks
    Templates -.->|implements| Scenarios

Validation: Automated script checks all @ references resolve to existing files/sections

4.3 Cross-Reference Validation Tool

#!/usr/bin/env python3
"""Validate cross-references in skill documentation."""

from pathlib import Path
import re
from dataclasses import dataclass

@dataclass
class Reference:
    """A cross-reference in documentation."""
    source_file: Path
    source_line: int
    target_path: str
    target_section: str | None
    target_lines: tuple[int, int] | None

def extract_references(doc_path: Path) -> list[Reference]:
    """Extract all @ references from document."""
    content = doc_path.read_text()
    references = []

    # Pattern: @path/to/file.md or @path#section or @path#L123-L456
    pattern = r'@([^\s#]+)(?:#([^\s]+))?'

    for line_num, line in enumerate(content.splitlines(), 1):
        matches = re.finditer(pattern, line)
        for match in matches:
            target_path = match.group(1)
            target_ref = match.group(2)

            # Parse section vs line reference
            target_section = None
            target_lines = None

            if target_ref:
                if target_ref.startswith('L'):
                    # Line range reference
                    line_match = re.match(r'L(\d+)(?:-L(\d+))?', target_ref)
                    if line_match:
                        start = int(line_match.group(1))
                        end = int(line_match.group(2)) if line_match.group(2) else start
                        target_lines = (start, end)
                else:
                    # Section reference
                    target_section = target_ref

            references.append(Reference(
                source_file=doc_path,
                source_line=line_num,
                target_path=target_path,
                target_section=target_section,
                target_lines=target_lines,
            ))

    return references

def validate_reference(ref: Reference, skill_root: Path) -> dict[str, any]:
    """Validate a single reference."""
    result = {
        "valid": False,
        "file_exists": False,
        "section_exists": False,
        "lines_exist": False,
        "error": None,
    }

    # Check file exists
    target_file = skill_root / ref.target_path
    if not target_file.exists():
        result["error"] = f"File not found: {ref.target_path}"
        return result

    result["file_exists"] = True

    # Check section/lines exist
    if ref.target_section:
        content = target_file.read_text()
        # Look for section header
        section_pattern = rf'^#+\s+.*{re.escape(ref.target_section)}'
        if re.search(section_pattern, content, re.MULTILINE | re.IGNORECASE):
            result["section_exists"] = True
        else:
            result["error"] = f"Section not found: {ref.target_section}"
            return result

    if ref.target_lines:
        content_lines = target_file.read_text().splitlines()
        start, end = ref.target_lines
        if start <= len(content_lines) and end <= len(content_lines):
            result["lines_exist"] = True
        else:
            result["error"] = f"Line range {start}-{end} exceeds file length {len(content_lines)}"
            return result

    result["valid"] = True
    return result

def validate_all_references(skill_root: Path) -> dict[str, list]:
    """Validate all references in skill documentation."""
    all_refs = []
    broken_refs = []

    # Scan all markdown files
    for doc_path in skill_root.rglob("*.md"):
        refs = extract_references(doc_path)
        all_refs.extend(refs)

        for ref in refs:
            validation = validate_reference(ref, skill_root)
            if not validation["valid"]:
                broken_refs.append({
                    "reference": ref,
                    "validation": validation,
                })

    return {
        "total_references": len(all_refs),
        "broken_references": broken_refs,
        "broken_count": len(broken_refs),
        "success_rate": (len(all_refs) - len(broken_refs)) / len(all_refs) if all_refs else 1.0,
    }

# Usage in pre-commit hook
if __name__ == "__main__":
    skill_root = Path("~/repos/claude_skills/opinionated-python-development")
    results = validate_all_references(skill_root)

    print(f"Cross-Reference Validation:")
    print(f"  Total references: {results['total_references']}")
    print(f"  Broken references: {results['broken_count']}")
    print(f"  Success rate: {results['success_rate':.1%}")

    if results['broken_count'] > 0:
        print("\nBroken References:")
        for broken in results['broken_references']:
            ref = broken['reference']
            val = broken['validation']
            print(f"  {ref.source_file}:{ref.source_line}")
            print(f"    Target: {ref.target_path}")
            print(f"    Error: {val['error']}")

        exit(1)  # Fail build if broken references

    exit(0)

Integration: Add to pre-commit hooks and CI/CD pipeline

NFR Compliance: NFR-MAINT-4 requires cross-reference validation ✅

5. Token Budget Management

5.1 Document Size Targets

Size Constraints (NFR-PERF-3):

Conversion Factor: ~4 chars/token (empirical for code/markdown)

5.2 Size Optimization Strategies

Strategy 1: External Examples

• Move large code examples to templates directory
• Reference examples rather than embedding
• Reduces scenario/framework document size

Strategy 2: Targeted Loading

• Load only relevant framework (not all frameworks)
• Load only required standard (not all standards)
• Progressive disclosure at section level

Strategy 3: Content Compression

• Use tables instead of prose where appropriate
• Use mermaid diagrams for complex relationships
• Link to authoritative sources rather than duplicating

Strategy 4: Lazy Loading

• Load "Common Pitfalls" section only when requested
• Load "Migration Guide" only for legacy code
• Load "External Resources" only when needed

5.3 Size Monitoring

Automated Size Tracking:

#!/bin/bash
# monitor-doc-sizes.sh

echo "Document Size Report"
echo "===================="
echo

for category in scenarios standards frameworks processes tools templates; do
    echo "$category:"
    find docs/$category -name "*.md" -exec sh -c '
        size=$(wc -c < "$1")
        tokens=$((size / 4))
        name=$(basename "$1")
        printf "  %-30s %6d bytes %5d tokens\n" "$name" "$size" "$tokens"
    ' _ {} \;
    echo
done

# Check for oversized documents
echo "Oversized Documents (>20 KB):"
find docs -name "*.md" -size +20k -exec sh -c '
    size=$(wc -c < "$1")
    tokens=$((size / 4))
    printf "  ⚠️  %s: %d bytes (%d tokens)\n" "$1" "$size" "$tokens"
' _ {} \;

CI/CD Integration: Run size monitor on every commit fail if documents exceed targets by >20%

6. Content Update Strategy

6.1 Version Management

Document Versioning:

• Each document has independent version in frontmatter
• Follows semantic versioning (MAJOR.MINOR.PATCH)
• MAJOR: Breaking changes to document structure/requirements
• MINOR: New content additions examples patterns
• PATCH: Clarifications typo fixes formatting

Skill Versioning:

• Skill has overall version in metadata.json
• Skill version bumps when multiple documents updated
• Skill MAJOR bump: Breaking changes to core requirements
• Skill MINOR bump: New scenarios/frameworks added
• Skill PATCH bump: Documentation improvements

Example:

# In docs/scenarios/cli-human-facing.md
---
version: "

…(truncated)