Building with mini, Part 8/9: Health commands — changelog and doctor

In Part 7 we had the instrument panel: where am I, one step back, which model. Two commands remain, the ones that watch the project's health — not the phase state, but whether the whole thing holds together. changelog (what changed, and when, for users) and doctor (whether the mini setup is in order). Both read-only, both Claude-free.

changelog — what has piled up

Remember Part 4? Every done proposes an entry for CHANGELOG.md. After four phases, a fair amount has piled up there — and changelog shows it to you without opening the file:

mini changelog

[Unreleased]

### Added

- Tokenizer for arithmetic expressions: numbers (integer and decimal),
  operators `+ - * /`, and parentheses, each token carrying its position…
- `evaluate(text)` function that parses and computes an arithmetic
  expression, returning a `Decimal`. Supports `+ - * /`, parentheses,
  left-associative operators (`2-3-4 = -5`), and unary minus…
- Command-line interface: `python3 pycalc.py "2+3*4"` evaluates the
  expression and prints the result, with exit codes 0/1/2…
- `-h` / `--help` flag: prints usage, the supported operators…
  No released version yet — showing the Unreleased section.

A bare mini changelog shows the latest released version. But pycalc hasn't released anything yet (we never bumped the version — Part 6 mentioned --bump/--push are opt-in), so the command notices there's no dated version and honestly falls back to the [Unreleased] section with that note. When you want something specific:

mini changelog --unreleased      # the pending changes
mini changelog --version 1.0.0   # a specific release
mini changelog --all             # the whole file

An important detail: changelog is independent of .mini/ — it just reads CHANGELOG.md from the current directory. It works even in a project that has nothing to do with mini. It's a reader, not part of the state.

doctor — is the setup in order?

doctor walks the project and prints a checklist — what's OK, what's a warning, what's broken, and for each problem how to fix it:

mini doctor

mini doctor
  ✓ Project: state schema v2
  ✓ Phases: no orphaned "doing" phases
  ✓ Run reports: no stale reports
  ✓ Decisions: no stale decisions
  ✓ project.md: present
  ✓ CHANGELOG.md: present
  ! Slash commands: none installed in this project
    Run `mini install-commands` (or rely on the user-scope ones)
  ! Version: v1.18.0 → v1.20.0 available
    Run `mini upgrade` to update

[!] All essentials present, 2 warnings.

What it checks, and why it makes sense:

• Project / schema — does the state.json version match what this mini can read? If not, it suggests mini migrate. (This is the one fail that actually stops you.)
• Phases — is some phase stuck in doing with no open work? That's the "stuck" state we saw in Parts 4-5; doctor finds it and suggests done or undo.
• Run reports / Decisions — are there orphaned files left in .mini/run/ or .mini/decisions/ from a phase that no longer exists (e.g. after undo)? Safe to delete.
• project.md / CHANGELOG.md — are they in place?
• Slash commands — is the full /mini:* set installed in the project? For pycalc it's missing — and that's a legitimate state, not an error: pycalc runs off the user-scope commands (Part 0), so it has no project-scope ones. That's why it's a ! (warning), not a ✗.
• Version — is this mini current? doctor just told me that v1.20.0 is out while I'm running v1.18.0.

The summary tallies the counts: for pycalc, "All essentials present, 2 warnings" — nothing critical, two things to consider. doctor is purely read-only diagnostics; it fixes nothing itself, it just shows and advises.

When to run it: after undo/migrate (to check nothing was left behind), after a mini update, or simply when something feels off and you want a quick check that the problem isn't in the setup.

What they have in common

The same pattern as the state commands from Part 7: read-only, local, zero tokens. changelog reads CHANGELOG.md, doctor reads the filesystem and the version cache. Neither starts Claude, neither changes anything. They're the warning lights on the dashboard — you glance when you want to, and move on.

Trade-offs

• doctor checks the setup, not the code. Seven green ticks don't mean the program works — they mean mini is in order. "Do the tests pass?" is still on you and on verify.
• changelog is only as good as done wrote it. It shows what got written into CHANGELOG.md — and that's produced in the done session. Leave a vague entry there and changelog hands it back to you just as vague. It's a reader, not a proofreader.
• A doctor warning is not an order. "Slash commands: none" is fine for pycalc (user-scope). Treat the hints as suggestions, not a TODO list to clear — you know the context, the checklist doesn't.

Next time — the finale

That completes the set: from init through the whole loop, autonomous mode, state and health. One scenario remains, the one we've skirted so far: what if a project is already running and you want to bring mini into it after the fact? That's Part 9 — import-gsd, audit, and map, three ways to set mini onto an existing codebase. And because it's the finale, we'll release pycalc on GitHub — not as "yet another calculator", but as an open showcase of .mini/: the vision, the backlog, the phase memories and run reports, exactly the files this whole series has described.

---

mini is open source: npm install -g mini-orchestrator, then mini install-commands in your project. Source and docs on GitHub.