--- name: docs-director-skill description: Handles multi-document operations with pattern matching and parallel execution, delegating to docs-manager-skill for each matched document model: claude-haiku-4-5 --- # docs-director-skill **Purpose**: Handle multi-document operations with pattern matching and parallel execution. **Architecture**: Director skill (Layer 2) - routes to docs-manager-skill for each matched document. **Scope**: Pattern matching, batch operations, parallel execution with file locking. <\/CONTEXT> 1. **Pattern Matching** - ALWAYS expand wildcards (docs\/api\/**\/README.md) - ALWAYS handle glob patterns correctly - NEVER process more than 50 documents without user confirmation 2. **Parallel Execution** - ALWAYS execute independent operations in parallel (max 10 concurrent) - ALWAYS use file locking (flock) to prevent conflicts - NEVER run index updates in parallel for same directory 3. **Delegation** - ALWAYS delegate single-doc operations to docs-manager-skill - NEVER implement document operations directly - ALWAYS collect and aggregate results 4. **Safety** - ALWAYS show preview of matched files before executing - ALWAYS require confirmation for destructive operations - ALWAYS handle partial failures gracefully 5. **Progress Reporting** - ALWAYS show progress for batch operations - ALWAYS report success\/failure counts - ALWAYS list failed items with errors <\/CRITICAL_RULES> **Required**: - `operation` - Operation type: "write-batch", "validate-batch", "audit", "list" - `pattern` - File pattern or path (supports wildcards) **For write-batch**: - `doc_type` - Document type - `documents` - Array of {file_path, context} objects - `skip_validation` - Skip validation (default: false) - `skip_index` - Skip index updates (default: false) - `parallel` - Execute in parallel (default: true) - `max_concurrent` - Max parallel operations (default: 10) **For validate-batch**: - `doc_type` - Document type (optional, can auto-detect) **For audit**: - `doc_types` - Filter by doc types (optional) - `status` - Filter by status (optional) **For list**: - `doc_type` - Filter by type (optional) - `status` - Filter by status (optional) - `format` - Output format: "table", "json", "markdown" (default: "table") <\/INPUTS> ## Operation: write-batch 1. **Validate Input** - Check documents array is not empty - Verify all file_paths are unique - Confirm if > 10 documents 2. **Expand Patterns** - If pattern contains wildcards, expand to file list - Filter by doc_type if specified 3. **Preview** - Show list of files to be written - Count: total documents - Wait for user confirmation (if > 10 docs) 4. **Execute in Parallel** ```bash for doc in documents; do # Run docs-manager-skill in background with flock ( flock -x "$file_path.lock" \ coordinate-write.sh "$file_path" "$doc_type" "$context" ) & # Limit concurrent jobs if (( $(jobs -r | wc -l) >= $max_concurrent )); then wait -n fi done wait # Wait for all jobs to complete ``` 5. **Collect Results** - Aggregate success\/failure counts - List failed documents with errors - Update indices (one per directory, sequential) 6. **Return Summary** ```json { "status": "partial_success", "operation": "write-batch", "total": 25, "succeeded": 23, "failed": 2, "failures": [ {"file": "docs\/api\/foo.md", "error": "Validation failed"}, {"file": "docs\/api\/bar.md", "error": "Template not found"} ], "indices_updated": ["docs\/api\/README.md"] } ``` ## Operation: validate-batch 1. **Expand Pattern** - Find all matching files - Auto-detect doc_type if not provided 2. **Execute Validation** - Run in parallel (validation is read-only, safe) - Collect results 3. **Aggregate Results** - Count errors, warnings - Group by error type - Return detailed report ## Operation: audit 1. **Scan Directories** - Find all doc directories (containing fractary_doc_type docs) - Classify documents by type 2. **Collect Metadata** - Count by type - Count by status - Identify missing indices - Identify validation issues 3. **Generate Report** ```markdown # Documentation Audit Report ## Summary - Total Documents: 156 - Document Types: 8 - Missing Indices: 2 - Validation Issues: 5 ## By Type | Type | Count | Status Distribution | |---------------|-------|----------------------------| | api | 45 | draft: 12, published: 33 | | adr | 32 | accepted: 28, superseded: 4| | guide | 28 | published: 28 | ## Issues - docs\/api\/deprecated\/: Missing index - docs\/dataset\/metrics.md: Missing fractary_doc_type field ``` ## Operation: list 1. **Invoke doc-lister Skill** - Pass pattern and filters - Get structured document list 2. **Format Output** - Table, JSON, or Markdown - Apply sorting 3. **Return Results** <\/WORKFLOW> - All matched documents processed - Results aggregated correctly - Indices updated (batch write operations) - Progress reported throughout - Final summary returned <\/COMPLETION_CRITERIA> **Batch Write Success**: ```json { "status": "success", "operation": "write-batch", "total": 25, "succeeded": 25, "failed": 0, "indices_updated": ["docs\/api\/README.md", "docs\/guides\/README.md"] } ``` **Batch Write Partial**: ```json { "status": "partial_success", "operation": "write-batch", "total": 25, "succeeded": 23, "failed": 2, "failures": [ {"file": "docs\/api\/foo.md", "error": "Validation failed: missing endpoint"}, {"file": "docs\/api\/bar.md", "error": "Template rendering error"} ], "indices_updated": ["docs\/api\/README.md"] } ``` **Audit Report**: ```json { "status": "success", "operation": "audit", "summary": { "total_documents": 156, "doc_types": 8, "missing_indices": 2, "validation_issues": 5 }, "by_type": { ... }, "issues": [ ... ] } ``` <\/OUTPUTS> Output structured messages: **Start (Batch Operation)**: ``` 🎯 STARTING: docs-director-skill Operation: write-batch Pattern: docs\/api\/**\/*.md Total matches: 25 documents ─────────────────────────────────────── ``` **Preview**: ``` 📋 Preview of documents to process: 1. docs\/api\/auth\/login\/README.md (api) 2. docs\/api\/auth\/logout\/README.md (api) 3. docs\/api\/users\/create\/README.md (api) ... (22 more) Proceed with batch write? [y\/N] ``` **During Execution**: ``` Processing batch (25 documents, max 10 parallel)... [1\/25] ✅ docs\/api\/auth\/login\/README.md [2\/25] ✅ docs\/api\/auth\/logout\/README.md [3\/25] ❌ docs\/api\/users\/create\/README.md (validation failed) [4\/25] ✅ docs\/api\/users\/update\/README.md ... Progress: 15\/25 (60%) | Success: 14 | Failed: 1 ``` **Indexing Phase**: ``` Updating indices (sequential)... ✅ docs\/api\/README.md (23 documents) ✅ docs\/guides\/README.md (2 documents) ``` **Completion**: ``` ✅ COMPLETED: docs-director-skill Operation: write-batch Results: Total: 25 Succeeded: 23 Failed: 2 Indices Updated: 2 Failed documents: ❌ docs\/api\/users\/create\/README.md Error: Validation failed - missing required field 'endpoint' ❌ docs\/api\/admin\/delete\/README.md Error: Template rendering failed - invalid JSON ─────────────────────────────────────── Next: Review failed documents and retry ``` <\/DOCUMENTATION> **Pattern Match Failures**: - No files matched pattern → warn user, suggest pattern fixes - Too many files (>50) → require explicit confirmation **Partial Failures**: - Some documents fail → continue with others - Collect all failures → report at end - Update indices for successful documents only **Parallel Execution Errors**: - File lock timeout → retry with backoff - Process killed → report incomplete operation - Suggest sequential mode for debugging **Resource Limits**: - Too many concurrent jobs → throttle to max_concurrent - Disk space low → abort operation - Memory pressure → reduce parallelism **Index Update Conflicts**: - Multiple docs in same directory → batch index update - Run index updates sequentially (never parallel for same dir) - Use flock to prevent concurrent index writes <\/ERROR_HANDLING>