# Reference Document Architecture > 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… - Skill: `tools-only/reference-document-architecture-3` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/reference-document-architecture-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/reference-document-architecture-3/raw - Safety review: pending (external: skill-scanner WARNING, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/reference-document-architecture-3 --- # 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 ```text 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**: `````markdown --- 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**: ````markdown --- 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)**: ```python # Code following standard ``` **Improvements**: - [Improvement 1] - [Improvement 2] --- ## Tool Configuration ### Enforcement Tools **Tool 1: [Tool Name]**: ```toml # pyproject.toml or configuration file [tool.toolname] option = "value" ``` **Tool 2: [Tool Name]**: ```bash # Command-line usage tool-name --flag value ``` --- ## Common Violations and Fixes ### Violation 1: [Violation Pattern] **Detection**: ```bash # How to detect this violation ``` **Error Message**: ```text [Typical error message] ``` **Fix**: ```python # Corrected code ``` --- ## Migration Guide ### From Legacy Pattern **Legacy Pattern** (Python 3.8-3.10): ```python # Old approach ``` **Modern Pattern** (Python 3.11+): ```python # 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)**: ```toml [project] dependencies = [ "{framework-name}>={version}", ] ``` ### Configuration **Required Configuration**: ```python # Configuration code ``` **Optional Configuration**: ```python # Optional enhancements ``` --- ## MUST Requirements ### Requirement 1: [Requirement Name] **Rule**: MUST [specific requirement] **Rationale**: [Why this is required] **Example**: ```python # Compliant code ``` **Validation**: ```bash # 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**: ```bash # How to detect violations ``` --- ## Core Patterns ### Pattern 1: [Pattern Name] **Purpose**: [What this accomplishes] **Implementation**: ```python # Complete working pattern ``` **Testing**: ```python # 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**: ```python # Framework-specific typing patterns ``` ### Testing [How to test code using this framework] **Example**: ```python # Test patterns for this framework ``` ### Validation [How validation tools work with this framework] **Configuration**: ```toml # 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 | Framework Version | Python Version | Status | Notes | | ----------------- | -------------- | --------- | -------------------- | | {version}+ | 3.11-3.14 | Supported | Current | | {older-version} | 3.11-3.13 | Legacy | Migrate to {version} | --- ## 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**: ```bash # Command examples ``` **Configuration**: @docs/tools/{tool-category}.md --- ## Examples ### Example 1: [Example Scenario] **Context**: [Situation requiring this process] **Execution**: ```bash # Commands executed ``` **Output**: ``` # Expected results ``` **Validation**: ```bash # 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): ```bash uv pip install {tool-name} ``` **via pip**: ```bash pip install {tool-name} ``` **Version requirement**: {version-spec} **License**: {license-type} ### Configuration **pyproject.toml**: ```toml [tool.{tool-name}] option1 = "value1" option2 = true ``` **Command-line**: ```bash {tool-name} --option value ``` ### Usage **Basic usage**: ```bash # Simple command {tool-name} ``` **Common patterns**: ```bash # Pattern 1: [Description] {tool-name} --flag1 --flag2 arg # Pattern 2: [Description] {tool-name} --different-flags arg ``` **Integration with other tools**: ```bash # Chaining tools {tool-name} | other-tool ``` ### Examples **Example 1: [Scenario]**: ```bash # Command {tool-name} --specific-option value # Expected output [Output description] ``` **Example 2: [Scenario]**: ```python # 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 | Tool | Purpose | Speed | Features | Use When | | -------- | --------- | ------ | ------------- | ---------- | | {Tool 1} | [Purpose] | Fast | Basic | [Scenario] | | {Tool 2} | [Purpose] | Medium | Advanced | [Scenario] | | {Tool 3} | [Purpose] | Slow | Comprehensive | [Scenario] | --- ## Integration Patterns ### Pattern 1: Pre-commit Hooks ```yaml # .pre-commit-config.yaml repos: - repo: { repository-url } rev: { version } hooks: - id: { tool-name } args: [--flag] ``` ### Pattern 2: CI/CD Pipeline ```yaml # .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
Level 1: <1 KB] LoadMetadata --> LoadOrchestrator[Load SKILL.md
Level 2: ~15 KB] LoadOrchestrator --> DetermineScenario{Determine
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
2. typer-rich/standards.md
3. pep723-workflow.md
4. validation.md] LoadPortable --> LoadPortableDocs[1. cli-portable.md
2. argparse/standards.md
3. validation.md] LoadLibrary --> LoadLibraryDocs[1. module-library.md
2. testing.md
3. validation.md
4. api-versioning.md] LoadPEP723 --> LoadPEP723Docs[1. standalone-script.md
2. pep723-workflow.md
3. validation.md] LoadCLIDocs --> LoadTemplates{Need
Templates?} LoadPortableDocs --> LoadTemplates LoadLibraryDocs --> LoadTemplates LoadPEP723Docs --> LoadTemplates LoadTemplates -->|Yes| FetchTemplates[Load relevant templates
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**: ```markdown @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**: ```markdown [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**: ```markdown # 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 ```mermaid 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 ```python #!/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("./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): | Document Type | Target Size | Token Estimate | Enforcement | | ------------------- | ----------- | -------------- | ----------- | | Scenario | 10-15 KB | 2500-3750 | SHOULD | | Standard | 6-10 KB | 1500-2500 | SHOULD | | Framework/standards | 8-12 KB | 2000-3000 | SHOULD | | Framework/patterns | 12-18 KB | 3000-4500 | SHOULD | | Process | 7-10 KB | 1750-2500 | SHOULD | | Tool | 8-12 KB | 2000-3000 | SHOULD | | Template | 2-4 KB | 500-1000 | MUST | **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**: ```bash #!/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**: ```yaml # In docs/scenarios/cli-human-facing.md --- version: "1.2.0" # Document ve …(truncated)