Docs Director Skill

docs-director-skill

Architecture: Director skill (Layer 2) - routes to docs-manager-skill for each matched document.

Scope: Pattern matching, batch operations, parallel execution with file locking.

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

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")

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

   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

   {
     "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

   # 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

Batch Write Partial:

{
  "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:

{
  "status": "success",
  "operation": "audit",
  "summary": {
    "total_documents": 156,
    "doc_types": 8,
    "missing_indices": 2,
    "validation_issues": 5
  },
  "by_type": { ... },
  "issues": [ ... ]
}

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

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