Skill Topography

Activation-centric self-improving loop for Hermes skills.

Core idea: skills are not static docs; they are activation landscapes. We learn why each skill activates, classify failures causally, probe boundaries, then ship verified refinements through shadow rollout.

Why this is different

Standard loops do: failure -> rewrite skill.

Skill Topography does:

1. Telemetry capture (situation + activation + outcome)
2. Landscape modeling (attractors, repulsors, boundary conditions)
3. Failure taxonomy classification (8 modes)
4. Probe generation (negative/positive/edge)
5. Minimal refinement (append-only candidate diffs)
6. Shadow deployment (promote/rollback decisions)
7. Drift and pressure checks (staleness, novelty, complexity)

Architecture

sessions/cron output
   -> telemetry collector
   -> sqlite (situations, activations, outcomes)
   -> landscape engine
   -> failure classifier
   -> intervention planner (boundary refiner)
   -> probe generator / probe executor
   -> shadow deployer
   -> drift detector
   -> daily orchestrator

Project layout

skill_topography/
  config.py        # paths/constants
  db.py            # schema + persistence helpers
  telemetry.py     # session ingestion
  classifier.py    # 8-mode failure classifier
  landscape.py     # activation landscape engine
  probe.py         # synthetic probe generation/execution
  refiner.py       # intervention planning + candidate generation
  shadow.py        # shadow rollout manager
  drift.py         # drift/pressure detection
  orchestrator.py  # macro-loop coordinator

scripts/
  telemetry_collector.py
  landscape_engine.py
  failure_classifier.py
  probe_generator.py
  boundary_refiner.py
  shadow_deployer.py
  drift_detector.py
  skill_topography_daily.py

tests/
  test_db.py
  test_telemetry.py
  test_classifier.py
  test_landscape.py

Quickstart

cd /home/mars/projects/skill-evolution
python3 -m pip install -e .[dev]
pytest

# Run one full macro-loop:
python3 scripts/skill_topography_daily.py

Cron wiring (recommended)

# hourly telemetry batch
0 * * * * python3 /home/mars/projects/skill-evolution/scripts/telemetry_collector.py

# hourly shadow monitor
5 * * * * python3 /home/mars/projects/skill-evolution/scripts/shadow_deployer.py --monitor

# daily macro-loop
0 3 * * * python3 /home/mars/projects/skill-evolution/scripts/skill_topography_daily.py

# daily drift checks
0 4 * * * python3 /home/mars/projects/skill-evolution/scripts/drift_detector.py

Phase status

• ✅ Phase 1: schema + telemetry collector
• ✅ Phase 2: failure classifier + landscape engine
• ✅ Phase 3: probe generator + boundary refiner
• ✅ Phase 4: shadow deployer + drift detector
• ✅ Phase 5: daily orchestrator
• ✅ Phase 6: git-ready repo for GitHub push

Failure taxonomy

1. BOUNDARY_UNDERSPECIFIED
2. BOUNDARY_OVERSPECIFIED
3. CONTENT_MISALIGNED
4. TOOL_SELECTION_ERROR
5. CONTEXT_DECAY
6. SKILL_INTERFERENCE
7. PERCEPTION_MISMATCH
8. CASCADING_FAILURE

License

MIT