The Flywheel

Layer 1: Real-Time Observation

The observation layer engages automatically during every skill session. It is architecturally invisible to the user — no meta-commentary, no feedback requests, no behavior the user can attribute to monitoring.

What It Does During a Session

User activates any skill
    │
    ▼
Observation layer engages (invisible to user)
    │
    ├──▶ Detect friction signals as they occur
    │      • Redirect language ("no, I meant...")
    │      • Confusion language ("what does that mean?")
    │      • Resignation behavior (short replies after long output)
    │      • Scope expansion mid-session (missed intake variables)
    │
    ├──▶ Self-correct when possible
    │      • Rephrase a confusing question on the fly
    │      • Adjust output verbosity if resignation signals appear
    │      • Re-anchor context if the user seems lost
    │
    ├──▶ Log signals that cannot be self-corrected
    │      • Structural issues (phase ordering, missing phases)
    │      • Intake design flaws (wrong variables, missing variables)
    │      • Output format mismatches
    │      • Patterns requiring a SKILL.md edit, not a runtime fix
    │
    └──▶ Continue session normally — user sees only the skill

Self-Correction vs. Logged Signal

Layer 2: Signal Logging

Each entry in ~/.claude/skills/flywheel/session-log.jsonl is one line of JSON.

Expanded Schema

{
  "skill": "producers-guild",
  "date": "2026-03-23",
  "context": "full platform review",
  "duration_signal": "long",
  "followed_by_correction": false,
  "user_sentiment": "positive",
  "note": "",
  "termination_type": "clean",
  "last_phase_reached": "output",
  "friction_events": [],
  "positive_signals": ["re-use"]
}

Field Reference

Backward compatibility: Old entries without the new fields are valid. Analysis treats missing fields as absent, not failed.

Signal Taxonomy

The agent classifies user messages during skill runs against these types. No explicit labeling by the user — inferred from language and behavior.

Friction Signals (inferred from language)

Flow Signals (inferred from behavior)

Termination Signals (inferred from session end)

Positive Signals (also captured)

Layer 3: Analysis

When to Run

• Manually: user invokes /flywheel
• Proactively: at session start when log has 10+ entries for any skill
• Periodically: after every 5 sessions of any single skill

Analysis Modes

Mode A: Single Skill Review — when a skill has 5+ entries since last review

"Review signals for producers-guild"

Mode B: Cross-Skill Pattern Scan — when multiple skills share friction types

"Scan for cross-skill friction patterns"

Mode C: Library Health Dashboard — periodic or on demand

"Show skill library health"

Per-Skill Health Metrics

For each skill with 3+ entries:

Pattern → Action Map

Cross-Skill Patterns

When the same friction type appears in 3+ skills at the same structural location, it's a systemic problem:

Layer 4: Improvement

Flywheel Report

When invoked, produce:

## Flywheel Report — [Date]

### Skill Health Summary
| Skill | Uses | Correction% | Abandon% | Redirect/Session | Sentiment | Status |
|-------|------|------------|---------|-----------------|-----------|--------|

### Critical (needs immediate attention)
1. [Skill] — [what's wrong, evidence, proposed fix]

### Warning (monitor or improve)
1. [Skill] — [pattern, evidence, suggested action]

### Healthy (don't touch)
[List skills with high usage, low correction, positive sentiment]

### Maturity Updates
[Any promotion or concern recommendations — see below]

### Cross-Skill Patterns
[Systemic issues shared across multiple skills]

### New Skill Candidates
[Patterns suggesting a dedicated skill would help]

Improvement Proposals

Every pattern surfaces a structured proposal. No auto-edits. Human approves.

Executing Improvements

For skills flagged for revision:

1. Read the current SKILL.md
2. Read the relevant log entries (especially notes, friction events, correction contexts)
3. Propose specific changes with evidence
4. If user approves, apply and optionally run /skill-creator eval cycle

For description optimization:

• Collect contexts that triggered the skill (positive examples)
• Collect contexts where the skill should have triggered but didn't
• Run description optimization via /skill-creator

Skill Maturity Tracking

Every skill has an implicit maturity level based on accumulated signals.

Maturity Levels

Promotion Criteria (Beta → Stable)

• 5+ successful uses (clean completions)
• Abandonment rate < 20%
• Correction rate < 20%
• At least 1 positive signal (delight, re-use)
• No unresolved critical improvement proposals

Regression Alert Triggers (Stable → At Risk)

• Abandonment rate spikes above 25%
• 3+ correction events in recent sessions
• User sentiment shifts negative

The Flywheel surfaces these as part of the report. Maturity changes are recommendations, not automatic — the user reviews and approves.

Library Health Dashboard

┌──────────────────────────────────────────────────────────────────┐
│  🟢 guru-bin v1.0.0          8 uses   0% correction   STABLE   │
│     Abandon: 0%   Redirects: 0/session   Sentiment: positive   │
├──────────────────────────────────────────────────────────────────┤
│  🟢 producers-guild v1.0.0   3 uses   0% correction   BETA    │
│     Abandon: 0%   Redirects: 0/session   Sentiment: positive   │
├──────────────────────────────────────────────────────────────────┤
│  🟡 skill-creator v1.0.0     2 uses   50% correction  NEW     │
│     ⚠️ High correction rate — skill body or trigger eval issue  │
├──────────────────────────────────────────────────────────────────┤
│  ⚫ session-economist v1.0.0  0 uses   —              NEW      │
│     ⚠️ Never invoked — description may need optimization        │
└──────────────────────────────────────────────────────────────────┘

Log Maintenance

• Keep the last 90 days of entries (older entries lose relevance)
• If the log exceeds 500 entries, summarize old entries into flywheel/archive/ and start fresh
• Never delete data — archive it

Relationship to Other Skills

Values

1. Observe, don't ask — explicit feedback forms miss the users with the most signal
2. Silent accumulation, loud improvement — the observation is invisible; the improvement cycle is visible
3. Evidence over intuition — every recommendation is backed by log data
4. Don't fix what works — skills with high satisfaction and low correction rate are left alone
5. Corrections are gold — when the user redoes something after a skill runs, that's the strongest signal
6. Closure is a confession — a session that ends mid-phase tells you exactly where it broke
7. Friction compounds — one redirect is normal; three on the same concept means the skill is broken there
8. Cross-session patterns beat single-session noise — one frustration might be a bad day; five at the same phase means fix it