Flywheel

What this is

Your data — conversations, emails, calendar, health, location — is a record of your friction. Every repeated question, every correction, every manual step, every meeting that could have been an email. These are observable facts. The flywheel turns observations into improvements.

This is the Fix Your Papercuts chapter turned into an executable guide, and Don't Ask Me to Track It turned into a system. The data already exists. You build engines to read it, identify friction, and fix it. Then you do it again. That's the flywheel.

This is also Kai's mission: minimize friction. Step one is finding it. The flywheel is the architecture for doing that systematically — Steward streams health data, Oracle predicts what's coming, nightly consolidation connects dots across sources, and the event database gives you one timeline to mine. The flywheel is what ties those pieces together into something that actually spins.

This isn't hypothetical

The flywheel pattern shows up everywhere once you start looking. Here's what it looks like in practice:

• Screenshots. macOS screenshots land on the Desktop with names like Screenshot 2026-03-07 at 2.51.42 PM.png. Spaces in filenames break agent paths. Fix: fourteen lines of bash — grab latest screenshot, strip spaces, rename to screen.png, move to working directory. Five-minute fix, used dozens of times a day, rewritten three times as the need evolved. Over five years: eighty hours saved.
• Sleep. Six months of observations — breathing machine compliance, supplements, sleep aids. Discovered homeostatic adaptation: every sleep aid works for exactly four days, then stops. Required six months of data to see the pattern. Built an iOS app (Steward) that streams health data from Apple Watch to an event database without touching anything. The observation layer was manual for months before the fix was automated.
• Home sensors. Noticed bathroom light on at 8:30am = getting ready. YouTube playing = not leaving anytime soon. TV off = departure sequence. Formalized as Bayesian likelihood ratios: YouTube on = 0.5x probability of leaving, TV off = 1.5x. Built a prediction engine in one day. Now runs on a fifteen-minute loop pulling sensor data from the apartment.
• Steering files. AI kept dumping temporary files in /tmp. Added one line to CLAUDE.md: "Don't use /tmp." Permanent behavior change across every future session. One correction, written down once, never repeated.
• Data collection. Discovered Google Takeout doesn't include files from the last few hours. Documented it in wall-learnings.md the same session. Updated the published guide on shapes.exe.xyz. Next person doesn't hit the same wall.
• Context portability. Migrated an AI project from ChatGPT to Claude. Lost months of conversation history. Spent two days rebuilding context by hand. Invented the steering file pattern — a conversation you have once that applies to every conversation after.
• Operations reports. A consultant spending 30-60 hours per month on manual report production. Identified 7 discrete skills (extract timeline, map SLA terms, identify discrepancies, correct dates, calculate compliance, generate narrative, compile report). Projected result: 5-10 hours per month. From busyness to business.

The pattern is always the same: observe the friction, measure it, find the cause, fix it, track whether the fix worked. The only variable is the data source.

The layers

The flywheel has five layers. Each one builds on the one below it.

1. Observe

Fact-based friction logging. "March 10, 3:14 PM: asked about SSH permissions (4th time across 3 sessions)." No judgement. No interpretation. Expert field notes. A dated observation from a specific source. This technique applies to any data source — conversations, email, calendar, health, location, git logs. You build collection engines that mine friction from wherever it lives, on a schedule.

2. Identify metrics

What's measurable in the observations? "Average time to first productive commit per new project." "Number of times I re-explain project structure per week." "Days between exercise sessions." The observations suggest the metrics, not the other way around. You don't decide what to measure — you let the friction tell you.

3. Identify causal links

Connect observations across sources. "SSH questions spike after new project creation" (conversations + git log). "Energy drops correlate with days without exercise" (health + daily scores). "Meeting-heavy days produce zero commits" (calendar + git). Causals are hypotheses — they need validation. But even weak signals are worth writing down.

4. Propose interventions

A fix matched to a cause. A steering file addition. A shell alias. A cron job. A calendar block. A habit change. Each intervention is a hypothesis: "If I add an SSH cheatsheet to CLAUDE.md, the SSH questions stop." Small, testable, reversible.

Interventions are proposal documents. The flywheel writes a fix proposal — a markdown file describing the problem, the cause, and the proposed change — and drops it in the right project folder. An agent running in that project picks up the proposal and implements it. The flywheel doesn't fix things directly; it creates work for the agents that do. The folder is the interface.

Not every intervention is ready to execute. Some need research. Some need a conversation. Some are half-formed ideas waiting for the right moment. These go to the slush pile — a deferred backlog of planned interventions, unfinished thoughts, and future possibilities. The slush pile is the flywheel's long-term memory for things it noticed but can't fix yet.

5. Manage subgoals

CRUD on improvable metrics. Track whether interventions are working. "SSH questions: 4/week → 0/week after steering file fix." Drop metrics that flatline. Add new ones when new friction appears. This is the feedback loop that makes the flywheel spin — you can see it working, so you keep doing it.

Collection engines

Each data source gets an adapter that mines observations on a schedule. You don't need all of them — start with one. The output is always the same: dated observations.

The output structure

Everything lives in one folder. The agent creates it and maintains it across runs.

The handoff

Scheduling

The flywheel is a periodic process. Without a schedule, it's a one-shot audit that you'll forget to repeat. The collection engines need to run on a cadence — weekly for high-frequency sources (conversations, git, email), monthly for slower ones (location, health trends).

Options, from simplest to most automated:

• Calendar block. A recurring event that says "run the flywheel." You open your terminal, paste the handoff prompt, and walk through it with an agent. Lowest friction to set up.
• Steering file reminder. Add a line to your CLAUDE.md: "If it's been more than a week since the last flywheel run, remind me." The agent checks flywheel/log.md on startup.
• Cron job. Schedule collection engines to run automatically and dump observations. You review them when you're ready. The observation layer runs unattended; the interpretation layers need you.
• Nightly consolidation. The full Kai architecture: engines run at 3am, observations land in the event database, causal analysis runs across all sources, and you wake up to a briefing. This is the endgame — not where you start.

But here's the thing: the flywheel manages its own schedule. If the cadence is wrong — too frequent and you're ignoring it, too rare and friction piles up — that's an observation. The flywheel proposes a schedule change the same way it proposes any other intervention. It writes a proposal to its own project folder. It updates its own skills. The schedule isn't a setting you configure once; it's a metric the flywheel tracks and adjusts.

Start with a calendar block. The flywheel will tell you when to change it.

The dashboard

The flywheel produces structured data. That data wants a dashboard.

• Metric trends. Are your papercut counts going down over time? Line charts, sparklines, before/after comparisons.
• Win velocity. How many fixes landed this week, this month? A fix rate that's climbing means the flywheel is accelerating.
• Active subgoals. What's being tracked, what's flatlined, what's improving? A flatlined metric is a signal — either the intervention isn't working or the problem was solved and the metric should be retired.
• Source coverage. Which collection engines ran recently? Which are stale? A stale engine is a blind spot.
• Causal map. What connects to what across data sources. A graph of observations, metrics, and interventions. This is where you see the shape of your friction.

The dashboard reads flywheel/ and renders it. Static HTML, same as this page. The flywheel generates the data; the dashboard makes it visible. If the dashboard is missing something, the flywheel observes that too.