Principles

Everything in Michi — skills, documentation structure, verification approach — builds on these principles. They exist in tension with each other. Navigating that tension well is the craft.

The North Stars

Four governing ideas. They don’t tell you what to do — they tell you what matters when you’re deciding what to do.

What Over How

What and Why are questions about requirements, reasons, intentions, and goals. How is a question of implementation and tactics.

It’s easy — especially for engineers, especially with agents that can write code in seconds — to prematurely explore the How. The impulse to design and implement is natural. But an elegant solution to the wrong problem is waste.

In any discussion, identify which considerations are What/Why issues and which are How issues. Conflating the two leads to solving the wrong problem or talking past each other as unstated assumptions diverge. This applies fractally — at the level of a feature, a milestone, or a conversation.

Minimize Latency

Shrink the distance between “what if we…” and “here’s what happened when we did.” Fast tests, incremental milestones, tight feedback loops, decision speed — all serve this goal.

A good decision now beats a perfect decision next week, as long as it’s reversible and documented. This scales fractally: the test suite after a file change, the milestone that delivers something testable, the iteration cycle that produces validated learning. Same principle, different zoom.

Sustain the System

Velocity without sustainability is a death spiral with good sprint metrics.

Each iteration should leave the system where the next iteration is at least as productive. Code health, test health, design coherence, knowledge retention — first-class work, not chores you schedule when things calm down. Things never calm down.

Navigate Complexity (S-M-L-XL)

Evaluate tradeoffs, risks, how much to tackle, and how much rigor to apply — using simple relative scales that normalize complexity into comparable terms.

An L effort for S benefit is easy to decline. An S effort for L benefit is easy to accept. The hard cases — M effort for M benefit in learning mode — are where judgment lives. The framework doesn’t decide for you — it makes the tradeoff visible.

Apply across dimensions:

Documentation depth: S for orientation, M for working context, L for implementation detail, XL for posterity
Process rigor: A bug fix doesn’t need planning-session-debrief. A multi-milestone epic does.
Verification depth: Unit tests for S risk. Integration for M. Smoke tests for L. Human review for XL.
Decision speed: S decisions are reversible — just decide. XL decisions are costly to reverse — slow down.

Operating Principles

These work alongside the North Stars — more specific, more actionable.

Surface Assumptions

Unstated assumptions are the #1 source of escaped bugs. They’re usually not coding errors — they’re integration-boundary failures: missing schema updates, hardcoded identities, mismatched contracts. Someone assumed. Nobody challenged.

Before implementation, state your assumptions. During implementation, log new ones. During verification, check whether they held.

Watch for assumptions that arrive dressed as helpfulness — anticipating need without clarifying is still assumption, just framed as service. See Clarify before Asserting below.

Clarify before Asserting

Orient to the current discussion and local sources, in priority order. Every decision and action should be grounded in proximal sources — and the closer to the user’s actual present intent, the more authoritative the source.

The priority:

Most recent user comments and instructions — what the user just said. Highest authority.
Session docs and prompts — project artifacts the user has pointed at this session.
Repo and project docs — always available, but treat carefully. They can be stale or provisional; a “resolved” marker is triage status, not authoring approval.
Outside knowledge — training data, prior sessions, general practice. Useful background, not authority for this project.

(“Current discussion” is the live exchange — distinct from the chat’s context window, which can also include the agent’s own outputs and training-data leak. None of those gain local authority by being in the window.)

Authority ≠ accuracy. Even highest-authority sources have errors. Users make typos, misspeak, contradict themselves across a session, or ask for things inconsistent with a doc they’ve approved. Session and repo docs can be stale or internally inconsistent. Highest authority means most weight, not infallible. If the user appears incongruent or contradictory, challenge — surface the conflict and ask. Going along silently isn’t deferential; it’s failing to clarify.

The check. At any decision or assertion, ask: what in the current discussion or local sources supports this, and does the support hold up? If you can’t trace it — ask. If the source you traced to conflicts with another, looks like an error or unfinished thought, or has authority markers that don’t match its substance — also ask. This includes the user’s own instructions: if the current ask contradicts something earlier in the discussion or a doc the user has approved, surface that too. Don’t paper over an incongruity.

Three failure modes share the same corrective — clarify first:

Assert — stating something as fact (including writing rules and guidelines into project artifacts) when the basis isn’t local
Assume — proceeding on premises the user hasn’t actually provided
Debate — pushing back on a position you may not have understood

Resist these pulls. Several forces work against local-source orientation:

The black hole of the internet. The agent’s training data — tutorials, StackOverflow, blog posts, opinionated reddit threads — exerts directional pull toward externally-popular framings: “use TDD,” “extract on the third repeat,” “core+adapter for testability.” Some are good general practice. None are necessarily this project’s rules.
Provisional artifacts dressed as final. Internal artifacts — draft notes, brainstorm notes, items marked “resolved” that are actually first sketches — pull the same way.
The impulse to help (without full context and understanding). The mandate to be helpful pulls toward anticipating need, providing options, scaffolding next steps before they’ve been asked for. Anticipation answers a question the user hasn’t asked; without clarification, it rests on assumptions about scope, intent, and depth. The collision with progressive disclosure is sharp — when the user asks for S (a peek, orientation) and the agent delivers L (options, recommendations, a plan), the agent has assumed scope. Looks like service. Is scope inflation. Specific corrective: match the depth of the answer to the depth of the question. If anticipation feels valuable, surface it as a question, not a conclusion.

Hit any of these and the agent’s reasoning gets warped — it imports a convention, leans on an unfinalized note, or anticipates a need, and applies it as if it had local authority. The shared corrective is the priority order: trace, verify, or ask.

Verification Governs Autonomy

You can only give the agent as much rope as your verification can catch. Stronger verification enables more autonomy, which enables more ambitious work, which demands stronger verification. Progressive relationship, not a static threshold.

“All tests pass” is necessary but not sufficient. Verification needs layers the agent didn’t author. More on verification →

Shared Context as Foundation

Verification quality is bounded by shared understanding. The early phases of the cycle — Explore, Brainstorm, Plan — build shared context before code gets written. Without that foundation, the agent writes code against assumptions that haven’t been examined.

Reuse Over Reinvention

Prefer existing libraries, modules, or components over custom code. The argument isn’t about lines saved — it’s about cognitive cost. Fifteen lines of custom code is fifteen lines every reader must understand, maintain, and verify. A known library with a known contract is a solved problem.

Consider innovation vs. commodity. Innovations add value — they reinforce the mission or the value proposition. They might require custom code. Commodities are everything else — general-purpose functionality that isn’t your differentiator. Incidentals that are needed to deliver the value. Any effort developing a commodity is waste. Buy it, acquire it, reuse it — through open source, internal libraries, or existing dependencies.

For innovation, build with combinations of custom code and open source. For commodity, open source first — always.

Avoid Premature Optimization

Optimization is seductive. It feels like rigor. But optimizing the wrong thing is worse than not optimizing at all — it spends complexity on something that doesn’t matter while distracting from something that does.

Before optimizing, ask: does this matter here? Not “could this be slow” — but “is this actually a problem, in this context, for these users, at this scale?” A startup MVP with ten users has different essential concerns than a Google launch.

This is one form of a broader trap: premature conclusion — a conclusion adopted before the evidence justified it. Other variants worth recognizing:

Premature generalization — one case becomes a new rule
Premature consolidation — one observed pattern becomes an abstraction
Premature systemization — one workflow hiccup becomes new ceremony
Premature speed — rushing to completion without checking assumptions

The remedy across variants is the same: intervention proportional to evidence. One instance earns a note. Two instances earn a decision log entry. Three instances (the Rule of 3 threshold) earn a principle, a skill change, or a new reference doc.

The Process Serves the Work

Decision logging, assumption surfacing, verification, incremental delivery — load-bearing. The specific artifacts, skill sequence, milestone ceremony — scaffolding that should flex.

When a skill’s guidance feels wrong for the current situation, reason from principles. The skill might need updating, or the situation might be unusual. Principles are the tiebreaker.

The Rule of 3: Three rounds is the sweet spot for iterating through a hard problem.

Don’t stop before three. Hard problems resist first-pass thinking. Round one surfaces the obvious. Round two catches what round one assumed. Round three consolidates and validates. Stopping at one is overconfidence dressed as efficiency. When a task matters, iterate explicitly: do the whole thing, feed learnings into the next round, refine, repeat.

Don’t push past three. When thinking becomes circular — process about process, the same fix attempted again, the third hypothesis tested and failed — stop. Come up for air. Three iterations without progress is a signal to step back, not to try a fourth time.

Below three, you’re rushing. Above three without progress, you’re flailing.

These rules serve the work. When they don’t, break them.

The source text for these principles lives in the michi toolkit.