{"slug": "building-with-mini-part-8-9-health-commands-changelog-and-doctor", "title": "Building with mini, Part 8/9: Health commands — changelog and doctor", "summary": "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.", "body_md": "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`\n\n(what changed, and when, for users) and `doctor`\n\n(whether the mini setup is in order). Both read-only, both Claude-free.\n\n`changelog`\n\n— what has piled up\nRemember Part 4? Every `done`\n\nproposes an entry for `CHANGELOG.md`\n\n. After four phases, a fair amount has piled up there — and `changelog`\n\nshows it to you without opening the file:\n\n```\nmini changelog\n[Unreleased]\n\n### Added\n\n- Tokenizer for arithmetic expressions: numbers (integer and decimal),\n  operators `+ - * /`, and parentheses, each token carrying its position…\n- `evaluate(text)` function that parses and computes an arithmetic\n  expression, returning a `Decimal`. Supports `+ - * /`, parentheses,\n  left-associative operators (`2-3-4 = -5`), and unary minus…\n- Command-line interface: `python3 pycalc.py \"2+3*4\"` evaluates the\n  expression and prints the result, with exit codes 0/1/2…\n- `-h` / `--help` flag: prints usage, the supported operators…\n  No released version yet — showing the Unreleased section.\n```\n\nA bare `mini changelog`\n\nshows the latest **released** version. But pycalc hasn't released anything yet (we never bumped the version — Part 6 mentioned `--bump`\n\n/`--push`\n\nare opt-in), so the command notices there's no dated version and honestly falls back to the `[Unreleased]`\n\nsection with that note. When you want something specific:\n\n```\nmini changelog --unreleased      # the pending changes\nmini changelog --version 1.0.0   # a specific release\nmini changelog --all             # the whole file\n```\n\nAn important detail: `changelog`\n\nis **independent of .mini/** — it just reads\n\n`CHANGELOG.md`\n\nfrom 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`\n\n— is the setup in order?\n`doctor`\n\nwalks the project and prints a checklist — what's OK, what's a warning, what's broken, and for each problem how to fix it:\n\n```\nmini doctor\nmini doctor\n  ✓ Project: state schema v2\n  ✓ Phases: no orphaned \"doing\" phases\n  ✓ Run reports: no stale reports\n  ✓ Decisions: no stale decisions\n  ✓ project.md: present\n  ✓ CHANGELOG.md: present\n  ! Slash commands: none installed in this project\n    Run `mini install-commands` (or rely on the user-scope ones)\n  ! Version: v1.18.0 → v1.20.0 available\n    Run `mini upgrade` to update\n\n[!] All essentials present, 2 warnings.\n```\n\nWhat it checks, and why it makes sense:\n\n`state.json`\n\nversion match what this mini can read? If not, it suggests `mini migrate`\n\n. (This is the one `fail`\n\nthat actually stops you.)`doing`\n\nwith no open work? That's the \"stuck\" state we saw in Parts 4-5; `doctor`\n\nfinds it and suggests `done`\n\nor `undo`\n\n.`.mini/run/`\n\nor `.mini/decisions/`\n\nfrom a phase that no longer exists (e.g. after `undo`\n\n)? Safe to delete.`/mini:*`\n\nset installed in the project? For pycalc it's `!`\n\n(warning), not a `✗`\n\n.`doctor`\n\njust told me that `v1.20.0`\n\nis out while I'm running `v1.18.0`\n\n.The summary tallies the counts: for pycalc, \"All essentials present, 2 warnings\" — nothing critical, two things to consider. `doctor`\n\nis purely read-only diagnostics; it fixes nothing itself, it just shows and advises.\n\nWhen to run it: after\n\n`undo`\n\n/`migrate`\n\n(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.\n\nThe same pattern as the state commands from Part 7: **read-only, local, zero tokens.** `changelog`\n\nreads `CHANGELOG.md`\n\n, `doctor`\n\nreads 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.\n\n`doctor`\n\nchecks the setup, not the code.`verify`\n\n.`changelog`\n\nis only as good as `done`\n\nwrote it.`CHANGELOG.md`\n\n— and that's produced in the `done`\n\nsession. Leave a vague entry there and `changelog`\n\nhands it back to you just as vague. It's a reader, not a proofreader.`doctor`\n\nwarning is not an order.That completes the set: from `init`\n\nthrough 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`\n\n, `audit`\n\n, and `map`\n\n, 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/`\n\n: the vision, the backlog, the phase memories and run reports, exactly the files this whole series has described.\n\n*mini is open source: npm install -g mini-orchestrator, then mini install-commands in your project. Source and docs on *", "url": "https://wpnews.pro/news/building-with-mini-part-8-9-health-commands-changelog-and-doctor", "canonical_source": "https://dev.to/stkremen/building-with-mini-part-8-health-commands-changelog-and-doctor-5b5j", "published_at": "2026-07-29 11:00:00+00:00", "updated_at": "2026-07-29 11:03:29.646933+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["mini"], "alternates": {"html": "https://wpnews.pro/news/building-with-mini-part-8-9-health-commands-changelog-and-doctor", "markdown": "https://wpnews.pro/news/building-with-mini-part-8-9-health-commands-changelog-and-doctor.md", "text": "https://wpnews.pro/news/building-with-mini-part-8-9-health-commands-changelog-and-doctor.txt", "jsonld": "https://wpnews.pro/news/building-with-mini-part-8-9-health-commands-changelog-and-doctor.jsonld"}}