docs/operator_self_improve_loop.md

Operator Self-Improve Loop

Clean product one-liner: this is the smallest safe loop for improving the product shell without opening free-form repo drift.

Why: an operator should know how to ask for one useful change, review it, benchmark it, and keep the proof trail.

Pareto Frontier

Option	Speed	Safety	Learning value	Real-world analog
edit files ad hoc	high	low	low	hallway fix with no ticket
propose one bounded manifest	high	high	high	editor assigns one scoped revision
broad autonomous rewrite	low	low	unclear	newsroom redesign during print deadline

Layman read: the middle path is the product path. It is fast enough to use and constrained enough to trust.

The Loop

Step	Operator move	Surface	Why it matters	Real-world analog
1. Frame one gap	name one missing doc, config, or thin glue improvement	goal sentence	small asks are reviewable	assign one article revision
2. Propose	rtk ./bin/bvtctl self-improve "<goal>"	conversational front door	the system must suggest structured change before touching files	ask for a marked-up draft
3. Review	inspect the proposed JSON, touched files, and benchmark	manifest + decision brief	you verify scope before execution opens	copy desk review
4. Apply	rtk ./bin/bvtctl self-improve-apply "<goal>"	bounded execution lane	the runtime writes only the approved files	publish the approved edit
5. Verify	rtk ./bin/bvtctl benchmark	benchmark surface	the shell should prove it still works after the edit	run press checks
6. Promote or stop	keep the change only if the artifact is usable and the proof is honest	receipt + graph	improvement should compound from evidence, not vibes	archive only verified copy

Guardrails

Guardrail	Current rule	Why in plain English
touched files	maximum 3	small changes are easier to review and safer to benchmark
allowed actions	write_file only	the runtime should change content directly, not improvise shell side effects
preferred roots	docs/, configs/, thin runtime/ or policy/ glue	the product shell improves fastest at the boundary surfaces
benchmark	rtk ./bin/bvtctl benchmark	every approved change should pay rent in product proof
proof	receipt required	if there is no durable trail, the loop did not really learn

What Good Looks Like

Acceptance bar	Plain-language test
recommendation is clear	the next operator can tell what changed and why
route is grounded	the change stays inside the allowed roots and manifest contract
proof is honest	the receipt and benchmark say what really happened
artifact is usable	the new doc, config, or thin glue helps the shipped shell immediately

Good First Requests

• rtk ./bin/bvtctl self-improve "add one missing operator doc for the self-improve loop"
• rtk ./bin/bvtctl self-improve "tighten one confusing runtime command explanation"
• rtk ./bin/bvtctl self-improve "add one benchmark note for operators"

Why: these are product-shell improvements. They sharpen the front door instead of dragging the runtime into a large rewrite.