📅 let's chat! explore the endless possibilities creating industries that don't exist. click here
← Back to Learning Hub
Guide 7 of 8 10 min read

Reference Implementation

Goal: Explore the complete built system and understand what's included

What Was Built

Learning Guides (4 Files)

  1. GUIDE-00-START-HERE.md (5 min) — Mental model, why this pattern works, quick terminology
  2. GUIDE-01-PATTERN-EXPLAINED.md (15 min) — Deep dive on each component, orchestrator mechanics, phase agent contracts
  3. GUIDE-02-BUILDING-YOUR-OWN.md (30 min) — Decision tree, step-by-step adaptation guide, real-world examples
  4. GUIDE-03-DEBUGGING-TIPS.md (15 min) — 10 common issues and solutions, debugging tools, prevention checklist

Reference Implementation (16 Files)

schema-optimization/ — Complete 5-phase workflow:

  • SKILL.md — Orchestrator (300+ lines)
  • agents/ — 5 phase agent contracts (initial analysis, field utilization, impact assessment, verification, recommendations)
  • references/ — Step-by-step procedures for each phase
  • scripts/ — Deterministic verification script
  • reports/ — Session directories created at runtime

The Core Innovation: Phase 4 Verification

Traditional approach: The LLM says "I found 23 unused fields" and you have no way to verify.

Test harness approach: Phase 2 (LLM) writes a report. Phase 4 runs an actual verification script, confirms 21 fields, revises 2 that were wrong, and discovers 3 more. The agent compares results and updates recommendations with a full audit trail.

Result: Empirically validated conclusions with evidence.

Key Features Delivered

  • Complete orchestrator — session creation, phase chaining, validation gates
  • 5 phase agents with strict JSON contracts
  • Working verification script — deterministic, fast, produces JSON
  • 60+ pages of learning material
  • Hands-on exercise with step-by-step walkthrough
  • Visual documentation — maps, diagrams, flow charts

Design Principles

  1. Evidence-Based: Every phase writes a file
  2. Machine-Checkable: JSON outputs validated programmatically
  3. Fail-Fast: Orchestrator stops on first validation failure
  4. Composable: Phases are independent, reusable
  5. Debuggable: Clear failure points, structured outputs
  6. Repeatable: Deterministic scripts, same inputs = same outputs
  7. Auditable: Session directories preserve complete audit trail

Production Deployment Path

When you're ready to move a workflow out of the lab:

  1. Complete all phases — all reference docs written
  2. Test with real data — run on actual datasets
  3. Add error handling — graceful failures, meaningful errors
  4. Add logging — trace execution for debugging
  5. Move to production — copy from workspace/lab/ to .claude/skills/
  6. Document for ops — how to run, monitor, debug
  7. Monitor and iterate — track success rate, refine

Full Summary on GitHub

The complete system summary with file counts, testing procedures, and FAQ:

View Full Summary on GitHub →