jmagly/source-unifier

Source Unifier Skill

Purpose

Single responsibility: Intelligently merge documentation from multiple sources (websites, GitHub repos, PDFs) while detecting and transparently reporting conflicts between documented and implemented behavior. (BP-4)

Grounding Checkpoint (Archetype 1 Mitigation)

Before executing, VERIFY:

• [ ] All source URLs/paths are accessible
• [ ] Each source type is correctly identified (docs, github, pdf)
• [ ] Output directory is writable
• [ ] Merge mode is specified (rule-based or AI-enhanced)
• [ ] Conflict resolution strategy is defined

DO NOT merge without inspecting each source first.

Uncertainty Escalation (Archetype 2 Mitigation)

ASK USER instead of guessing when:

• Conflict severity unclear (is doc or code authoritative?)
• Multiple valid interpretations of API signature
• Source versions don't match (v2 docs vs v3 code)
• Merge strategy produces ambiguous results

NEVER silently resolve conflicts. Always report discrepancies.

Context Scope (Archetype 3 Mitigation)

| Context Type | Included | Excluded | |--------------|----------|----------| | RELEVANT | All specified sources, merge config | Unrelated documentation | | PERIPHERAL | Version history for context | Other projects | | DISTRACTOR | Previous merge attempts | Unrelated codebases |

Conflict Types

| Type | Severity | Description | Example | |------|----------|-------------|---------| | Missing in code | HIGH | Documented but not implemented | API endpoint in docs, not in code | | Missing in docs | MEDIUM | Implemented but not documented | Hidden feature in code | | Signature mismatch | MEDIUM | Different parameters/types | func(a, b) vs func(a, b, c=None) | | Description mismatch | LOW | Different explanations | Wording differences |

Workflow Steps

Step 1: Verify Sources (Grounding)

# Test documentation URL
curl -I https://docs.example.com/

# Test GitHub repo
gh repo view owner/repo --json name,description

# Test PDF file
file manual.pdf && pdfinfo manual.pdf

Step 2: Create Unified Configuration

{
  "name": "myframework",
  "description": "Complete framework knowledge from docs + code",
  "merge_mode": "rule-based",
  "conflict_resolution": {
    "missing_in_code": "warn",
    "missing_in_docs": "include",
    "signature_mismatch": "show_both",
    "description_mismatch": "prefer_docs"
  },
  "sources": [
    {
      "type": "documentation",
      "base_url": "https://docs.example.com/",
      "extract_api": true,
      "max_pages": 200
    },
    {
      "type": "github",
      "repo": "owner/myframework",
      "include_code": true,
      "code_analysis_depth": "surface",
      "max_issues": 100
    },
    {
      "type": "pdf",
      "path": "docs/manual.pdf",
      "extract_tables": true
    }
  ]
}

Step 3: Execute Unified Scraping

Option A: With skill-seekers

skill-seekers unified --config unified-config.json

Option B: Manual merge workflow

1. Scrape each source independently
2. Extract API signatures from each
3. Compare and detect conflicts
4. Generate merged output with conflict annotations

Step 4: Review Conflict Report

The unifier generates a conflict report:

# Conflict Report: myframework

## Summary
- Total APIs analyzed: 245
- Conflicts detected: 18
- Missing in code: 3 (HIGH)
- Missing in docs: 8 (MEDIUM)
- Signature mismatches: 5 (MEDIUM)
- Description mismatches: 2 (LOW)

## HIGH Severity Conflicts

### `deprecated_function()`
- **Status**: Documented but not found in code
- **Documentation**: "Use this function to..."
- **Code**: NOT FOUND
- **Recommendation**: Remove from docs or implement

## MEDIUM Severity Conflicts

### `process_data(input: str)`
- **Status**: Signature mismatch
- **Documentation**: `process_data(input: str)`
- **Code**: `process_data(input: str, validate: bool = True)`
- **Recommendation**: Update documentation to include `validate` parameter

Step 5: Validate Merged Output

# Check merged skill structure
ls -la output/myframework/

# Verify conflict annotations
grep -r "⚠️\|Conflict\|WARNING" output/myframework/references/

# Count conflict markers
grep -c "Conflict" output/myframework/references/*.md

Recovery Protocol (Archetype 4 Mitigation)

On error:

1. PAUSE - Preserve partial merge state
2. DIAGNOSE - Check error type:
   • Source unavailable → Skip source, note in report
   • Parse error → Check source format, retry with different parser
   • Memory error → Process sources sequentially
   • Conflict overflow → Increase conflict threshold or filter by severity
3. ADAPT - Adjust merge strategy
4. RETRY - Resume merge (max 3 attempts)
5. ESCALATE - Present partial results, ask user for conflict resolution

Checkpoint Support

State saved to: .aiwg/working/checkpoints/source-unifier/

checkpoints/source-unifier/
├── source_1_docs.json      # Processed docs
├── source_2_github.json    # Processed GitHub
├── source_3_pdf.json       # Processed PDF
├── conflicts.json          # Detected conflicts
└── merge_progress.json     # Current merge state

Resume: skill-seekers unified --config config.json --resume

Output Structure

output/myframework/
├── SKILL.md                    # Main skill with conflict summary
├── references/
│   ├── index.md                # Unified index
│   ├── api_reference.md        # Merged API docs (with conflict markers)
│   ├── guides.md               # Merged guides
│   └── conflicts.md            # Detailed conflict report
├── sources/
│   ├── documentation.md        # Original docs content
│   ├── github.md               # GitHub-extracted content
│   └── pdf.md                  # PDF-extracted content
└── metadata/
    ├── sources.json            # Source metadata
    └── conflict_summary.json   # Machine-readable conflicts

Conflict Markers in Output

Merged content includes inline conflict markers:

#### `process_data(input: str, validate: bool = True)`

⚠️ **Conflict**: Documentation signature differs from implementation

**Documentation says:**
```python
def process_data(input: str) -> dict:
    """Process input data and return results."""

Code implementation:

def process_data(input: str, validate: bool = True) -> dict:
    """Process input data with optional validation."""

Resolution: Documentation should be updated to include the validate parameter added in v2.3.

## Merge Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| `rule-based` | Apply predefined rules for conflict resolution | Fast, deterministic |
| `ai-enhanced` | Use AI to intelligently merge conflicting content | Better quality, slower |
| `manual` | Generate conflicts only, user resolves | Full control |

## Troubleshooting

| Issue | Diagnosis | Solution |
|-------|-----------|----------|
| Too many conflicts | Sources very different | Filter by severity, merge incrementally |
| False positives | Parser differences | Normalize API extraction |
| Missing content | Source incomplete | Add supplementary source |
| Merge too slow | Large sources | Use parallel processing |

## References

- Skill Seekers Unified Scraping: https://github.com/jmagly/Skill_Seekers/blob/main/docs/UNIFIED_SCRAPING.md
- REF-001: Production-Grade Agentic Workflows (BP-4, BP-6 model consortium parallel)
- REF-002: LLM Failure Modes (Archetype 1-4 mitigations)