Twinned from https://github.com/cfsh/ninefold/issues/766 by tools/beads/import_github.py's reconcile pass.
Perhaps we should help devs navigate the tooling better by printing Print links to notes from messages in dev tooling, and generally when using the tooling. e.g. "if this was unexpected, read foo.md"
I got this back from nf-dev-design-005 at the end of a long context which shipped 4 PRs:
""" meta question:
can u reflect for a min, is it clear enough how to use our developer tooling? e.g. presubmit, review_now and so on? Did you find any commands or APIs confusing? Did you end up reading the source code to use the tools
I noticed u used a lot of context and tokens to make 4 PRs, so I'm wondering if theres any learnings to take from that
Genuinely useful question. Let me check a couple of things before answering, rather than going from impression.
Ran 2 commands That check answered it, and not in my favour. Let me file the one systemic finding, then answer straight.
File the just-in-time-docs finding Honest answer: the tooling was clearer than my use of it. I checked before replying, and the three most expensive mistakes I made were each already documented, in the notes file the step pointed at.
Did I read source to use the tools? Yes, but mostly legitimately — I was modifying presubmit.py, probe_all.py, nflib/, so reading them was the work. The one time I read source because docs failed me, docs hadn't failed me: I grepped nflib/sessions.py to find out why wrap_up.py refused, and the answer was in notes/chunks.md:70 in capitals — "a comment whose FIRST line is…". I'd written ## RELEASE as a heading.
The costly ones:
what I did what was already written full review_now after nearly every fix — ~12× CLAUDE.md:212: "once per batch, not once per push" full review_now to refresh a check stale after a rebase — 4× notes/merging.md:179: "⚠️ Do NOT use a full review_now for this … minutes and tokens, to move something whose actual work is three seconds" That second one is the sharpest. The note exists specifically to stop the expensive route, states the cost, and I took it four times — in the session you're now asking why cost so much. Each full review_now is a synchronous xhigh model run plus a long verdict I then read and replied to at length.
So on your token question, ranked by avoidability:
~12 full review pulls instead of batching + --reconcile-only. Entirely self-inflicted, entirely documented. Fix-induced defects — ~10 of ~20 findings were introduced by the fix for the previous one. Each cost a full round. That's not a docs problem; it's #482's missing mutation scaffolding, and it's why I added the "re-run the mutations the test already caught" property there. ~10 full poll digests. Correct per the decision line, but #726 already measures the digest at 256 KB with 93% being 188 open issues printed in full. Four full 34-probe sweeps where a subset would have established the dose–response; only the confirming run needed to be full. Over-long PR replies. The verdict asks for an itemization, not an essay per item. Where I'd defend the spend: the measurements themselves. They overturned three of the design doc's premises and stopped two pieces being built wrong — and #758 exists so nobody pays for them twice.
The one genuine system observation, filed as #765: the notes tier is opt-in by design, so a session doesn't know it needs the file until after it has paid. All three of my misses were first-time-in-session actions — first merge, first stale check, first RELEASE. The reviewer charter already fixed this for itself with an explicit "read the relevant notes file before…" instruction; there's no equivalent for a coding session at the step. Cheapest fix is a just-in-time pointer at loop step 7 rather than more in CLAUDE.md — which is the tax notes/README.md exists to avoid.
"""
None.
No comments.