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

A developer building the 'mini' project introduced two new read-only, zero-token commands: 'changelog' and 'doctor'. The 'changelog' command displays the CHANGELOG.md file without opening it, supporting flags for unreleased, specific version, or full content. The 'doctor' command checks project health by validating state schema, phase consistency, and installed commands, outputting a checklist of issues and warnings.

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: state.json version match what this mini can read? If not, it suggests mini migrate . This is the one fail that actually stops you. doing with no open work? That's the "stuck" state we saw in Parts 4-5; doctor finds it and suggests done or undo . .mini/run/ or .mini/decisions/ from a phase that no longer exists e.g. after undo ? Safe to delete. /mini: set installed in the project? For pycalc it's warning , not a ✗ . 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. 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. doctor checks the setup, not the code. verify . changelog is only as good as done wrote it. 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. doctor warning is not an order.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