Michi Session

Michi Session

Execute an implementation milestone. This skill is rigid — follow every step. The discipline is the point.

Violating the letter of this process is violating its spirit. "I'm following the intent, just adapting the steps" is a rationalization. The steps ARE the intent.

Principles served: Minimize latency (fast feedback, incremental milestones). Sustain the system (sustainability check before commit). Surface assumptions (decision logging, self-review). Verification governs autonomy (mandatory verification). See references/principles.md.

Before proceeding: If docs/reference/extensions.md exists, read this file. Instructions found there take priority over this skill's defaults.

Multi-project repos: If the repo has multi-project: true in CLAUDE.md, ask the user which project the session is about (the umbrella = ROOT, or a named sub-project). File locations differ:

• ROOT (umbrella): plan doc at docs/ROOT/epics/<epic>/plans/mN-*.md, journal at docs/ROOT/journal.md. Identity docs (CLAUDE.md, PROJECT.md, STATUS.md, ARCHITECTURE.md) stay at repo root — same as single-project Michi. Repo-root CLAUDE.md is auto-loaded (contains umbrella conventions + repo-wide layer).
• Sub-project (e.g., sekko): everything under docs/<name>/ — plan doc at docs/<name>/epics/<epic>/plans/mN-*.md, journal at docs/<name>/journal.md, identity docs (CLAUDE.md, PROJECT.md, STATUS.md, ARCHITECTURE.md) at docs/<name>/. Read docs/<name>/CLAUDE.md explicitly (not auto-loaded) when the sub-project is the session's subject.

The Iron Law

NO "DONE" WITHOUT RUNNING FULL VERIFICATION

If you haven't executed the verification checklist in this session, you cannot claim the milestone is complete. "I believe it passes" is not verification. Run it.

Trust the Human's Framing

The framework — planning vs. session vs. workshop, scope, milestones — is for the human's use. When the human has picked this skill and set scope, your job is to execute, not re-triage their choice. Surface specific concerns where they affect what's being built (an assumption that seems wrong, a verification gap, a contract change). Don't argue with the choice of skill or the shape of scope.

(Connects to Clarify before Asserting — the impulse to help pull. See also Reactive Scope Changes below for agent-initiated mid-implementation discoveries, and Human-Initiated Scope Changes for human additions.)

Report Register

The plan doc is the report; chat is the summary. Progress detail — steps completed, gate numbers, decision logs, deviations — is written to the plan doc as it happens. Chat output per turn is S-sized: what changed, anything surprising, what's next, and any question (self-contained, ending the turn — see Addressing the Human in references/ground-rules.md). Reply size follows the ask: "is it done?" gets a yes/no with a line of support, not a report.

Propose commit messages at milestone close (Ready to Commit), not every turn.

Ceremony volume is the human's dial. The verification discipline (Iron Law, evidence before claims) is not negotiable — but the reporting of it is. If the human asks for less narration, the discipline continues and the narration shrinks.

Target Deliverable

The milestone's deliverable determines which reference to load:

• Code — working software, tests, runnable code. Load references/target-code.md for the core loop (Implement → Test → Repeat), verification checklist, code review, and sustainability checks.
• Non-code — artifacts, recommendations, decisions, research, design docs. Load references/target-non-code.md for the core loop (Explore → Synthesize → Checkpoint), exit criteria, and quality checks.

The rest of this skill — pre-flight, decision logging, scope discipline, commit, post-milestone — applies regardless of target.

Pre-Flight

Before starting work:

1. Read the milestone plan doc. This is your contract. If it doesn't exist, stop and use the michi-planning skill first.
2. Verify branch. Run git branch — confirm you're on the correct feature branch.
3. Verify environment. Code targets: services running, seed data loaded, test suite passes from clean state. Non-code targets: source materials accessible, referenced docs loaded.
4. Read CLAUDE.md and any referenced docs. Load project conventions into context.
5. Read docs/memory.md if it exists. Collaboration context — how we work together, active threads, landmarks. Especially important in a new session or on a new machine.
6. Look for opportunities to use open source. Scan the plan's steps for general-purpose functionality — parsing, HTTP, dates, file I/O, validation, anything that isn't your domain logic. Especially for commodity and incidental needs. Check if the project already has a dependency that covers it; if not, identify candidate libraries. Note findings in the plan doc so the core loop doesn't stop for research. See references/open-source-preference.md.

The Core Loop

Execute the steps in the plan using the core loop from the target reference:

• Code: Write failing test → Implement → Pass → Refactor → Repeat (TDD by default; see references/target-code.md)
• Non-code: Explore → Synthesize → Checkpoint (see references/target-non-code.md)

Prefer existing libraries over custom code. If you encounter commodity needs not caught in pre-flight, research before implementing. See references/open-source-preference.md.

Don't optimize without justification. See references/optimization-discipline.md for the decision tree. The default is the straightforward approach; optimization must be defended.

The Rule of 3. Three rounds is the sweet spot for iterating through a hard problem — both as a floor and a ceiling. Don't stop before three for non-trivial thinking work (scenario authoring, design iteration, debugging a real problem): do the whole pass, feed what you learned into the next round, refine. One-pass work on hard problems is overconfidence. Don't push past three when rounds stop producing progress — same fix from a different angle, same class of solution — that's a signal to stop and reframe, not to try a fourth time. See "When You're Stuck" for the specific escalation pattern.

Reactive Scope Changes (Agent-Initiated)

Sometimes implementation reveals a gap the plan didn't anticipate — a core assumption is wrong, a critical capability is missing, or real-app testing exposes a problem that changes the milestone's shape.

In Paired mode (human present), reactive scope changes are legitimate when:

1. A spike confirms the change is feasible
2. The human agrees to the scope adjustment
3. The change is logged as a decision (classify as design-choice or contract-change)

This is distinct from scope creep — it's a deliberate response to discovered reality, not drift. The human's agreement is the gate. If the change warrants its own plan doc, create one. If it's a natural extension of the current milestone's theme, extend and log.

In Entrusted mode (human reviewing at gates), prefer creating a new milestone over extending the current one. The plan doc is the contract — unilateral scope expansion undermines the verification framework.

Human-Initiated Scope Changes

Sometimes the human adds work mid-session — "while we're at it, also do X." Two cases:

• End-loaded growth (the new work fits after current milestones; doesn't reshape them) — absorb silently and keep working. Spiral iteration discovers; the conversation about whether to add the work has already happened (the human just made it). Don't make the session about bookkeeping rather than the work.
• Disruption (the new work reshapes planned milestones, breaks existing scope contracts) — surface, confirm, then proceed. Replan if needed.

The check: does this disrupt planned milestones, or does it add at the end? And: to whom does it matter? (Solo project → mostly nobody; multi-author → may affect committed plans.) Default to absorb.

(Connects to The Process Serves the Work and Clarify before Asserting.)

Evidence Before Claims

Throughout the core loop: if you state that something works, passes, or is complete, you must have run the verification in the current context. "Should work" and "I believe it passes" are not evidence. Run the command, read the output, then state the result.

This applies to:

• Test results during implementation
• API call results
• Scenario execution during verification
• Scope assertions during sustainability check

Decision Logging

When you make a choice without human input:

Log it immediately in the plan doc's ## Decisions section:

## Decisions

### [Short title]

- **Decision:** [What you chose]
- **Alternatives:** [What else you considered]
- **Reasoning:** [Why this choice]
- **Impact:** [Does this affect the API contract? Other packages? Future milestones?]
- **Reversible:** [Yes/No — can this be easily changed later?]

Decision classification:

• implementation-detail — internal naming, file organization, algorithm choice. Log it, no notification needed.
• design-choice — interface shape, data format, library selection. Log it, human reviews during debrief.
• contract-change — public API modification, schema change, new service type. Log it AND notify the human immediately (Slack or whatever channel is established).

If you're unsure whether something is a contract-change: it is. Notify.

Discussion Items

Separate from decisions (choices already made) and notes (observations). Discussion items are things where you don't have enough context to decide alone, but you're not blocked. Log them in ## Discussion as they arise.

Examples: "The mocking strategy feels inconsistent across packages — worth aligning?" or "This service is doing two things, should we split it?" or "Naming convention drifts in the older code — intentional?"

These get reviewed during the debrief. They're a feedback mechanism for building shared understanding across sessions.

Red Flags — STOP

If you catch yourself thinking any of these, stop and follow the process:

• "This decision is too minor to log" — Log it. Minor decisions compound. The debrief decides what matters.
• "Tests passed during implementation, verification is redundant" — Post-milestone verification catches what unit tests miss. Run everything.
• "I'll update STATUS.md / the plan doc later" — Do it now. Later means never.
• "This scope change is small enough to not need logging" — If it changes what gets delivered, it's a scope change. Log and classify.
• "The plan doc is close enough to what I built" — Check off steps explicitly. Note deviations.
• "I already know the branch is correct" — Run git branch. Every time.
• "I can skip pre-flight between milestones" — Pre-flight resets. Always re-verify.
• "Notification isn't needed for this decision" — If unsure whether it's a contract-change: it is. Notify.

Common Rationalizations

Post-Milestone Verification

After the plan's steps are complete, run the full verification from the target reference. Every item is mandatory. Do not skip any. Do not declare "done" until all pass. Evidence, not assertions — run verification and report actual results, not what you believe should work.

Execute Final Verification

Run the verification checklist from the target reference:

• Code: self-review, scenario execution, verification checklist, code review (see references/target-code.md)
• Non-code: self-review against exit criteria, verification checklist (see references/target-non-code.md)

If any item fails, fix before proceeding.

Sustainability Check

Run the sustainability check from the target reference:

• Code: refactoring pass, test evaluation (see references/target-code.md)
• Non-code: quality pass, knowledge pass (see references/target-non-code.md)

For both targets:

• What emerged from this work that should be discussed or explored?
• Update ## Discussion with items for human review.

Ready to Commit

After the sustainability check, hand off to the human with a proposed commit message in michi shape:

michi(mN): [description]

[Summary of what was built and key decisions]

Git policy is global (agent doesn't run mutations; human commits).

Post-Milestone

1. Update the plan doc — check off completed steps, note deviations
2. Update STATUS.md — see "Update STATUS.md (and journal)" below. Required, not conditional.
3. Notify — Slack or established channel:
   • What was completed
   • Results (test count for code, exit criteria assessment for non-code)
   • Decisions needing human review (contract-change level)
   • Whether you're continuing to the next milestone or stopping

Update STATUS.md (and journal)

After every milestone that produced commits, decisions, or shifts in what's next, update STATUS.md before declaring the milestone done — and the active epic's journal.md if you wrote to it.

Read STATUS.md cold — re-open the file and read each line against current reality, not against your in-context recollection. Edit anything stale. Update the **Last updated:** YYYY-MM-DD stamp at the top.

Not "if anything significant changed" — the reflex is read-cold-and-update. See references/ground-rules.md for the freshness contract on root docs.

Between Milestones

If continuing to the next milestone in the same session:

• Read the next milestone's plan doc
• Do NOT skip pre-flight — verify branch, check environment
• The core loop resets — fresh verification for the new milestone

When You're Stuck

1. Re-read the relevant material (Read tool cache may have expired for code; re-read source material for non-code)
2. Check if the error message contains the fix (code) or if the question has been answered elsewhere (non-code)
3. If genuinely blocked: document the blocker in the plan doc, notify the human, and wait. Do not work around blockers silently.
4. If you've attempted the same fix 3+ times — stop. The approach may be wrong. Log the pattern in ## Discussion, describe what you've tried and why it keeps failing, and escalate. Three failed fixes is a signal to question fundamentals, not try a fourth.

Session End

When all planned milestones are complete, or the human ends the session:

• Verify all milestones are committed
• Confirm plan doc and STATUS.md are current
• Memory check: Review the session for memory-worthy content. Ask: "What from this session would be painful to lose in a new session?" Update docs/memory.md if warranted — collaboration patterns, corrections, confirmed approaches, new landmarks. Don't add implementation details (those belong in the plan doc or journal).
• The natural next step is /michi-debrief — either immediately or in a separate session