MoE Content Classification Skill

MoE Content Classification Skill

Version History

Version	Date	Changes
v3.0.0	2025-12-29	--enhance-frontmatter, --threshold, --type-override, --respect-directory
v2.1.0	2025-12-28	13 Type Experts, autonomous mode, expert mode
v2.0.0	2025-12-27	Type Expert system, signal injection
v1.0.0	2025-12-26	Initial MoE classification

When to Use This Skill

Use this skill when:

• Classifying documents with low analyst agreement (< 80%)
• Deep semantic analysis is needed to determine true document purpose
• Autonomous classification targeting 95-100% confidence
• Boosting low-confidence files (v3: --enhance-frontmatter)
• Batch processing large document sets with quality requirements
• Understanding disagreements between classification analysts
• Generating targeted enhancements to improve document classification

When NOT to Use This Skill

• For documents with clear, explicit type: frontmatter declarations
• When simple pattern matching is sufficient
• For non-markdown files (unless extended to support them)

Skill Components

Type Expert Agents

13 specialized experts that deeply understand each document type:

Expert	Purpose	Key Signals
GuideExpert	Identify tutorial/how-to documents	Prerequisites, steps, troubleshooting
ReferenceExpert	Identify API/spec documents	Tables, schemas, configuration
WorkflowExpert	Identify process definitions	Phases, Mermaid diagrams, checklists
AgentExpert	Identify AI agent definitions	Persona, capabilities, tools
CommandExpert	Identify slash commands	Invocation, parameters, usage
ADRExpert	Identify architecture decisions	Context, decision, consequences
SkillExpert	Identify reusable patterns	When to use, patterns, I/O specs
HookExpert	Identify event-driven hooks	Trigger events, lifecycle, pre/post
ReadmeExpert	Identify README files	Badges, installation, quick start
TemplateExpert	Identify template documents	Placeholders, boilerplate, fill-in
IndexExpert	Identify index/catalog docs	Table of contents, inventory, directory
ReportExpert	Identify report documents	Executive summary, findings, metrics
ChangelogExpert	Identify changelog files	Version headers, Added/Changed/Fixed

TypeExpertCoordinator

Orchestrates all experts to achieve optimal classification:

from type_experts import create_coordinator

coordinator = create_coordinator()
decision = coordinator.coordinate(document, analyst_votes)

print(f"Recommended: {decision.recommended_type}")
print(f"Confidence: {decision.confidence:.2%}")
print(f"Reasoning: {decision.reasoning}")

Key Dataclasses

@dataclass
class TypeAnalysis:
    is_this_type: bool           # Expert's verdict
    confidence: float            # Confidence (0-1)
    evidence_for: List[str]      # Supporting evidence
    evidence_against: List[str]  # Contradicting evidence
    missing_signals: List[str]   # What's needed for higher confidence
    analysts_to_sway: Dict       # Which analysts need convincing

@dataclass
class ContentEnhancement:
    signal_type: str             # e.g., 'prerequisites', 'api_reference'
    content: str                 # Generated content to add
    insertion_point: str         # Where to insert
    reason: str                  # Why this helps
    expected_analyst_boost: Dict # Expected confidence improvement

Pattern: Autonomous Classification

from autonomous import AutonomousClassifier

classifier = AutonomousClassifier(
    dry_run=False,    # Actually modify files
    verbose=True      # Show progress
)

result = classifier.classify_autonomous(file_path)

if result.success:
    print(f"Classified as {result.final_type} ({result.final_confidence:.0%})")
else:
    print(f"Needs review: {result.reason}")

Pattern: Expert Analysis

from type_experts import create_coordinator
from core.models import Document
from core.orchestrator import create_default_orchestrator

# Load and classify
doc = Document.from_path(file_path)
orchestrator = create_default_orchestrator()
initial_result = orchestrator.classify(doc)

# Run expert analysis
coordinator = create_coordinator()
decision = coordinator.coordinate(doc, initial_result.analyst_votes)

# Generate enhancement report
report = coordinator.format_decision_report(decision)
print(report)

Pattern: Batch Classification with Type Experts

from pathlib import Path
from type_experts import create_coordinator
from core.models import Document
from core.orchestrator import create_default_orchestrator

docs_path = Path("docs/")
files = list(docs_path.glob("**/*.md"))

orchestrator = create_default_orchestrator()
coordinator = create_coordinator()

for file_path in files:
    doc = Document.from_path(file_path)
    initial = orchestrator.classify(doc)

    if initial.result.confidence < 0.85:
        # Low confidence - run expert analysis
        decision = coordinator.coordinate(doc, initial.analyst_votes)

        if decision.enhancements:
            print(f"{file_path.name}: Needs {len(decision.enhancements)} enhancements")

Integration Points

With /classify Command

# Standard classification
/classify docs/ -r

# With Type Expert analysis
/classify docs/ -r --expert

# With autonomous fixing
/classify docs/ -r --autonomous --fix

# V3: ENHANCE FRONTMATTER MODE
# Add explicit type fields to boost low-confidence files
/classify docs/ -r --enhance-frontmatter

# V3: Custom threshold (default 95%)
/classify docs/ -r --enhance-frontmatter --threshold 90

# V3: Preview enhancements (dry run)
/classify docs/ -r --enhance-frontmatter --dry-run

# V3: TYPE OVERRIDE MODE
# Force specific type on all files in a directory
/classify docs/workflows/ -r --enhance-frontmatter --type-override workflow

# V3: Combine with dry-run to preview overrides
/classify docs/guides/ -r --enhance-frontmatter --type-override guide --dry-run

# V3: RESPECT DIRECTORY MODE
# Use directory path as classification hint
/classify docs/ -r --enhance-frontmatter --respect-directory

# V3: Verbose to see where directory hints are applied
/classify docs/ -r --enhance-frontmatter --respect-directory --verbose

V3: Enhance Frontmatter Mode

The --enhance-frontmatter mode (v3.0.0) adds explicit type declarations to low-confidence files:

# Before: 86% at ≥95% confidence
python3 scripts/moe_classifier/classify.py docs/ -r --enhance-frontmatter

# After: 100% at ≥95% confidence

What it does:

1. Classifies each file using MoE
2. For files below threshold, adds/updates frontmatter:
   • type: <classification>
   • component_type: <classification>
   • moe_confidence: 0.950 (or custom threshold)
   • moe_classified: <today's date>

Key difference from --update-frontmatter:

• --update-frontmatter: Records actual confidence from content analysis
• --enhance-frontmatter: Forces confidence to threshold with explicit type declarations

Use case: When you want to ensure all documents have definitive type classifications regardless of content ambiguity.

V3: Type Override Mode

The --type-override TYPE option (v3.0.0) forces a specific type on all files, ignoring MoE classification:

# Force all files in workflows/ to type=workflow
python3 scripts/moe_classifier/classify.py docs/workflows/ -r --enhance-frontmatter --type-override workflow

# Preview what would be overridden
python3 scripts/moe_classifier/classify.py docs/guides/ -r --enhance-frontmatter --type-override guide --dry-run

What it does:

1. Skips MoE classification entirely
2. Applies the specified type to ALL files in the path
3. Sets frontmatter fields: type, component_type, moe_confidence, moe_classified

Use case: Batch correcting misclassified directories. For example, files in workflows/ that MoE classifies as "guide" due to content structure can be forced to "workflow" based on their directory location.

Valid types: workflow, guide, reference, agent, command, skill, hook, readme, template, index, report, changelog, adr

V3: Respect Directory Mode

The --respect-directory option (v3.0.0) uses directory paths as classification hints:

# Use directory hints for low-confidence files
python3 scripts/moe_classifier/classify.py docs/ -r --enhance-frontmatter --respect-directory

# Verbose to see which files get directory hints
python3 scripts/moe_classifier/classify.py docs/ -r --enhance-frontmatter --respect-directory --verbose

What it does:

1. Runs MoE classification normally
2. For files below threshold where directory hint differs from MoE result, uses directory hint
3. Only overrides when MoE confidence is low AND directory suggests different type

Directory patterns recognized:

Directory	Type
workflows/	workflow
guides/, getting-started/, training/	guide
reference/, architecture/, internal/	reference
adrs/	adr
agents/	agent
commands/	command
skills/	skill
hooks/	hook
templates/	template
reports/	report
changelogs/	changelog

Use case: Automatically correct files that MoE misclassifies based on content structure. For example, a workflow file with step-by-step instructions might be classified as "guide" by MoE, but --respect-directory will use "workflow" because it's in the workflows/ directory.

V3: Suggest Enhancements Mode

The --suggest-enhancements option (v3.0.0) analyzes files and provides actionable recommendations:

# Get enhancement suggestions for low-confidence files
python3 scripts/moe_classifier/classify.py docs/ -r --suggest-enhancements

# Verbose mode shows content previews
python3 scripts/moe_classifier/classify.py docs/ -r --suggest-enhancements --verbose

Example output:

📄 BUSINESS-SALES-WORKFLOWS.md
   Current: workflow (88%) → Target: ≥95%

   ⚠️  Missing signals:
      • phases
      • diagram
      • checklist

   💡 Recommended enhancements:
      1. [phases] Workflows need phase-based structure
      2. [diagram] Workflows should include process diagrams
      3. [checklist] Workflows benefit from completion checklists

What it shows:

• Current classification and confidence
• Missing signals that would improve classification
• Conflicting content that confuses analysts
• Specific content enhancements with priorities
• Document's semantic purpose

Use case: Get actionable guidance on how to improve document structure for better classification, rather than just forcing type declarations.

With Document Management Workflows

The skill integrates with CODITECT document management:

1. Pre-classification - Run before major documentation reorganization
2. Quality gates - Ensure all documents classified with > 85% confidence
3. Enhancement automation - Generate missing sections automatically
4. Audit trails - Full reasoning logs for classification decisions

File Locations

scripts/moe_classifier/                    # In coditect-core
├── type_experts/
│   ├── __init__.py         # Module exports (13 experts)
│   ├── base.py             # TypeExpert base class
│   ├── coordinator.py      # TypeExpertCoordinator
│   ├── guide_expert.py     # Guide document expert
│   ├── reference_expert.py # Reference document expert
│   ├── workflow_expert.py  # Workflow document expert
│   ├── agent_expert.py     # Agent document expert
│   ├── command_expert.py   # Command document expert
│   ├── adr_expert.py       # ADR document expert
│   ├── skill_expert.py     # Skill document expert
│   ├── hook_expert.py      # Hook/trigger expert
│   ├── readme_expert.py    # README expert
│   ├── template_expert.py  # Template expert
│   ├── index_expert.py     # Index/catalog expert
│   ├── report_expert.py    # Report expert
│   └── changelog_expert.py # Changelog expert
├── autonomous.py           # Autonomous classification
├── classify.py             # CLI entry point
└── core/
    ├── models.py           # Data models
    └── orchestrator.py     # MoE orchestrator

Best Practices

1. Always check agreement ratio - Low agreement (< 60%) indicates need for expert analysis
2. Review audit trails - Expert reasoning helps understand edge cases
3. Iterate on enhancements - Apply suggested enhancements for persistent improvements
4. Trust expert disagreement signals - When experts disagree, document may genuinely be ambiguous

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: moe-content-classification

Completed:
- [x] Documents classified with MoE system
- [x] Type Expert analysis (if low confidence)
- [x] Frontmatter updated with classification results
- [x] Confidence threshold met (≥95% or configured)

Classification Results:
- Total files processed: X
- High confidence (≥95%): Y files
- Enhanced with frontmatter: Z files
- Type overrides applied: N files (if --type-override used)

Outputs:
- Updated files with moe_confidence and moe_classified frontmatter
- Classification report (if --suggest-enhancements used)
- Type Expert reasoning (if --expert mode used)

Completion Checklist

Before marking this skill as complete, verify:

• All target files have been classified
• Frontmatter fields added: type, component_type, moe_confidence, moe_classified
• Confidence scores meet threshold (default 95% or custom via --threshold)
• Type Expert analysis completed for low-confidence files (if applicable)
• Enhancement suggestions reviewed (if --suggest-enhancements used)
• Directory hints applied correctly (if --respect-directory used)
• Type overrides validated (if --type-override used)
• Classification report generated and reviewed
• All modified files validated with /classify command

Failure Indicators

This skill has FAILED if:

• ❌ MoE classifier module not found or import errors
• ❌ Document parsing errors (invalid frontmatter, corrupted files)
• ❌ Type Expert coordination failures
• ❌ Frontmatter update operations failed (file permission issues)
• ❌ Confidence scores below threshold without enhancement
• ❌ Invalid type specified in --type-override
• ❌ Directory pattern matching failures in --respect-directory mode
• ❌ Zero files classified when files expected
• ❌ Analyst vote aggregation errors
• ❌ Signal injection failures in Type Expert mode

When NOT to Use

Do NOT use this skill when:

• Documents already have explicit type: frontmatter with high confidence (use simple validation instead)
• Processing non-markdown files (MoE designed for .md files)
• Real-time classification needed (MoE has processing overhead)
• Binary or media files need classification (use file-type-detection skill)
• Simple pattern matching sufficient (use grep/glob instead)
• Classification context unavailable (empty files, minimal content)
• Batch processing >1000 files without chunking (use batch-classification workflow)
• Network-dependent classification needed (MoE is local-only)

Use alternatives:

• Simple frontmatter validation → document-skills
• File type detection → file-type-detection
• Bulk operations → batch-classification workflow
• Real-time classification → lightweight-classifier

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Running without checking existing frontmatter	Overwrites valid classifications	Use --update-frontmatter cautiously, check confidence first
Using --enhance-frontmatter on all files	Forces confidence to threshold artificially	Only use on low-confidence files, prefer organic improvements
Ignoring Type Expert disagreements	Misses document ambiguity signals	Review expert reasoning when confidence <80%
Using --type-override without validation	May classify incorrectly based on directory alone	Validate sample files before batch override
Not reviewing enhancement suggestions	Misses improvement opportunities	Run --suggest-enhancements, implement recommendations
Classifying without context	Produces low-confidence results	Ensure documents have sufficient content, headers, structure
Running autonomous mode without dry-run	Unexpected file modifications	Always test with --dry-run first
Missing --respect-directory for structured repos	Ignores valuable directory context	Enable for repos with semantic directory structure
Overriding high-confidence classifications	Degrades classification quality	Only override when MoE clearly wrong
Not tracking classification history	Loses improvement trends	Maintain moe_classified timestamps

Principles

This skill embodies:

• #1 Recycle → Extend → Re-Use → Create - Leverages existing Type Expert agents, reuses analyst patterns
• #5 Eliminate Ambiguity - Uses Type Expert coordination to resolve classification disagreements
• #6 Clear, Understandable, Explainable - Provides reasoning chains from Type Experts
• #8 No Assumptions - Validates document structure before classification
• #10 Research When in Doubt - Type Experts perform deep semantic analysis for low-confidence files

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Related

• /classify command - CLI interface
• moe-content-classifier agent - Deep classification agent
• document-skills - Document format processing
• documentation-quality - Quality validation

---

Author: CODITECT Core Team Framework: CODITECT v1.7.2 Classifier: MoE v2.1 with Type Experts