Building with mini, Part 5/9: When you need to think — discuss and verify

In Part 4 the loop next → plan → do → done ran and pycalc got its tokenizer. But the loop is optimistic: it assumes you already understand the phase, and that "the tests passed" means "done". Sometimes neither is true. For those two situations mini has two human checkpoints, symmetric around the loop:

• discuss — before the plan, when you don't have the phase thought through yet.
• verify — after do, when "green tests" aren't enough and it calls for a human eye.

Neither writes code, and neither moves the phase state. But each leaves behind a file that the later steps read — that's the whole point.

discuss — talk through the intent

We built the parser as Phase 2. Recursive descent looks like "just write it", but it hides decisions that are hard to change after the fact. Rather than discover them mid-implementation, I open a discussion:

mini discuss

The session gets the phase and the project, and is forbidden from implementing anything. The agent summarizes what the phase means, then asks — in small batches. The two most valuable questions were ones I wouldn't have asked myself:

2. Error positions at end of input — this is the main trap. For 2+ or (2+3 the token is missing exactly where the caret should point. But the parser only gets a list of tokens — the last position is at the last token, not past it. Either we pass the text length to the parser and report the error at pos = len(text), or the tokenizer starts adding an EOF token — but that changes Phase 1's output and breaks its tests.

That's not cosmetics. The second option would silently break a finished, tested Phase 1 — and it would only surface when the tests ran. We agreed on the first path (pass the length, don't touch the tokenizer). Decisions also landed on evaluation vs. AST (compute inline, no tree — an AST is overkill for a learning parser) and on the single public entry point (evaluate(text) -> Decimal).

Before the session ends, it writes a summary to .mini/discuss/phase-002.md — a fixed structure of Intent / Key decisions / Watch out for:

## Key decisions
- **Evaluate inline, no AST.** Compute the result during the recursive descent.
- **Single public entry point: `evaluate(text: str) -> Decimal`.**
- **End-of-input error positions: pass the text length to the parser.** Do NOT
  modify the tokenizer (no EOF token — that would break Phase 1 tests).
- **Division by zero points at the `/` operator token's position.**
- **Unary minus:** allow chaining (`--2` = 2) and post-operator use (`2*-3` = -6).
  **Reject unary plus** (`+5` is a syntax error).

That file is the payoff. mini plan and mini do pull it into their context — they see the decisions, not the whole rambling debate. The discussion is disposable, the conclusions permanent. (After discuss you also get offered an edit of the phase name/goal, in case the debate shifted the scope.)

verify — when "the tests passed" isn't enough

Two phases later pycalc actually computes: Phase 3 added the CLI layer. python3 pycalc.py "2+3*4" prints 14, errors go to stderr with a caret line. The tests are green, 14/14. Done?

No. The tests verify that 2++3 fails at position 2 — they don't verify whether that error looks good. And the readability of the messages is pycalc's entire selling point. So, before closing the phase:

mini verify

This is the one checkpoint that deliberately targets what a machine can't judge: appearance, clarity, smoothness. The agent leads the review interactively — one thing at a time, waiting for a reaction. It started from the verify items in the run report and then broadened the review. It signed off the happy path (the numbers read well, 1/3 truncates without a …, which I confirmed as intentional), but the wider pass turned up three real findings:

1. The error message has no prefix. The line prints unexpected token '+' with no error:/pycalc:. When you redirect stderr to a log or the caret line scrolls off, you can't tell an error from output. git/python prefix their errors.

2. The caret misaligns on tabs. The caret line is " " * err.pos + "^" over the raw index, but a tab renders as several columns — the caret lands elsewhere. Confirmed live. This is a genuine bug in the one feature you called the selling point, not cosmetics.

3. Usage names the wrong program. It prints usage: pycalc EXPRESSION, but it's invoked as python3 pycalc.py. The first line a confused user sees points at a command that doesn't exist.

I confirmed the tab caret myself (python3 pycalc.py "2⇥+⇥*3" — the caret really lands off) and --help too (it parses as an expression, "invalid character 'h'"). The agent wrote the findings into .mini/run/phase-003.md under a ## Verify findings section — below the YAML header, so mini done isn't disturbed. And the key moment:

Verdict: do not close the phase.
Recommended next step: go back to /mini:do to implement the three fixes.

This is the whole point of verify: it sent me back to do, not forward to done. Verify never closes phases — it either confirms there's something to close (and recommends done), or it finds work (and recommends do). It leaves the phase state in state.json untouched, because that's done's job, not its.

What to take away

Both commands are the same pattern: an interactive session, no code, no state change, output to a file. They differ only in where they stand in the loop and what they write — discuss notes for plan/do, verify findings into the report (and, for an already closed phase, into the memory too). Both are purely opt-in: the loop works without them. You reach for them only when thinking pays off.

The trade-offs, to put them on the table:

• They cost tokens and time. They're full interactive sessions. For a trivial phase discuss is just ceremony — next straight into plan is faster. They earn their keep only when there's something to decide or something to judge.
• verify is only as good as the reviewer. The agent suggests what to try, but you're the judge. If you answer "yeah, fine" without running the commands, you get a false "OK" in the report. The value is in actually clicking through it.
• verify findings aren't phases. Those three fixes now live only in the report. The next do has them in context, but if I don't finish the phase and /clear, I have to come back to the report by hand — the checkpoint doesn't auto-generate tasks into todo.

Next time

Three human stops per phase (proposal, plan, verification) are priceless for one phase a day — for five phases in an evening they're a chore. Next time we run mini auto: the loop driving phases back to back on its own, stopping for you only where it must. And with it stop — a clean way to halt it.

---

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