document-audit-extraction

Files (1)

• SKILL.md

SKILL.md (first lines)

# Document Audit & Feature Extraction

Systematically inventory, evaluate, and extract structured data from document collections.

## Audit Framework

### Four-Phase Audit

```
Phase 1: Inventory    → What exists?
Phase 2: Classify     → What type is each document?
Phase 3: Evaluate     → What's the quality?
Phase 4: Extract      → What structured data can we pull?
```

## Phase 1: Inventory

### Automated Inventory

```python
from pathlib import Path
from dataclasses import dataclass

@dataclass
class DocumentEntry:
    path: str
    name: str
    extension: str
    size_bytes: int
    modified: str
    word_count: int
    has_frontmatter: bool

def inventory_documents(root: str, patterns: list[str] = ["*.md", "*.txt", "*.yaml"]) -> list[DocumentEntry]:
    entries = []
    for pattern in patterns:
        for path in Path(root).rglob(pattern):
            content = path.read_text(errors="ignore")
            entries.append(DocumentEntry(
                path=str(path.relative_to(root)),
                name=path.stem,
                extension=path.suffix,
                size_bytes=path.stat().st_size,
                modified=path.stat().st_mtime,
                word_count=len(content.split()),
                has_frontmatter=content.startswith("---"),
            ))
    return entries
```

### Inventory Report

```markdown
## Document Inventory

| Path | Type | Words | Frontmatter | Modified |
|------|------|-------|-------------|----------|
| skills/dev/testing/SKILL.md | skill | 1,245 | Yes | 2026-03-20 |
| docs/CHANGELOG.md | changelog | 890 | No | 2026-03-19 |
| README.md | readme | 450 | No | 2026-03-18 |

**Total:** 142 documents | **With frontmatter:** 105 | **Total words:** 185,000
```

## Phase 2: Classification

### Document Type Taxonomy

| Type | Signal | Example |
|------|--------|---------|
| **Skill** | YAML frontmatter with `name:`, in skills/ | SKILL.md |
| **Configuration** | YAML/JSON schema | seed.yaml, registry.json |
| **Guide** | Tutorial structure, step-by-step | getting-started.md |
| **Reference** | API docs, schema docs | api-spec.md |
| **Decision** | ADR format, options + decision | adr-001.md |
| **Changelog** | Date-ordered entries | CHANGELOG.md |
| **Policy** | Rules, constraints | CONTRIBUTING.md |

### Automated Classification

```python
def classify_document(path: str, content: str) -> str:
    if "skills/" in path and content.startswith("---"):
        return "skill"
    if path.endswith("seed.yaml") or path.endswith("registry.json"):
        return "configuration"
    if "## Step" in content or "### Step" in content:
        return "guide"
    if "## Decision" in content or "## Alternatives" in content:
        return "decision"
    if "## [" in content and any(d in content for d in ["Added", "Fixed", "Changed"]):
        return "changelog"
    return "general"
```

## Phase 3: Quality Evaluation

### Quality Scorecard

| Criterion | Weight | Score (0-3) | Notes |
|-----------|--------|-------------|-------|
| **Completeness** | 30% | | All required sections present? |
| **Accuracy** | 25% | | Information correct and current? |
| **Clarity** | 20% | | Understandable without prior context? |
| **Structure** | 15% | | Logical organization, headings, formatting? |
| **Maintenance** | 10% | | Updated date, versioned, no stale links? |

### Automated Quality Checks

```python
def quality_check(path: str, content: str) -> dict:
    checks = {
        "has_title": content.startswith("#") or content.startswith("---"),
        "has_sections": content.count("\n##") >= 2,
        "reasonable_length": 100 < len(content.split()) < 10000,
        "no_todo_left": "TODO" not in content and "FIXME" not in content,
        "no_broken_links": not re.search(r'\[.*?\]\(\s*\)', content),
        "has_code_examples": "```" in content,
        "frontmatter_complete": check_frontmatter_fields(content),

From 4444J99/a-i--skills, MIT.

More from 4444J99/a-i--skills