fix(guide,suggest): word agent guidance no stronger than the evidence #2

Merged
trevon merged 13 commits from docs/honest-agent-guidance into main 2026-09-22 21:19:58 +00:00
2 changed files with 19 additions and 13 deletions
Showing only changes of commit dd74828e1d - Show all commits

fix(suggest): drop "work them in this order" from the agent plan

7ee8020 added the caution that the order is a score, not a mandate, but the
summary line two lines below still told the agent to work them in order.

The README fix-order example was hand-written with invented counts; it is now
the real output of the plan for the stuck_loading fixture.
trvon 2026-09-22 12:13:39 -06:00
Signed by: trevon
GPG key ID: 38686EA797D7A8A7

View file

@ -341,22 +341,28 @@ the plan is presented both globally and **per file**. Only new findings are
planned, so a ratcheted baseline yields an empty plan. planned, so a ratcheted baseline yields an empty plan.
```text ```text
# pipe plan — /path/to/app # pipe plan — test/fixtures/stuck_loading
Static heuristics; confirm each against the cited file. Order is a score, not a mandate. Static heuristics; confirm each against the cited file. Order is a score, not a mandate.
Coverage: 814 of 814 discovered file(s) analysed (0 failed, 0 skipped by analysis_options or context). Coverage: 12 of 12 discovered file(s) analysed (0 failed, 0 skipped by analysis_options or context).
146 findings collapse to 58 root cause(s) across 41 file(s). Work them in this order. 20 findings collapse to 16 root cause(s) across 8 file(s).
1. [warning/high] emitted-not-rendered — CommentsState (CommentsBloc) 1. [error/high] event-without-handler — HandlerGapEvent (GapBloc)
why: 75 = warning 50 x high (x1.0), user-visible failure (+25) why: 115 = error 100 x high (x1.0), no product judgement needed (+15)
fix: Wire it up: decide whether the feature ships, and if it does, mount CommentsBloc in a screen and render its states. Removing the bloc and its DI registration is the exception and needs explicit approval. fix: Add `on<UnhandledTap>(...)` to GapBloc, or stop dispatching UnhandledTap.
where: lib/blocs/comment/comment_bloc.dart:143 where: lib/gaps.dart:74
clears 1 finding(s) (CommentSubmitError, CommentSubmitSuccess, CommentSubmitting, CommentsError, CommentsLoaded, CommentsLoading); verify with `pipe check /path/to/app --rule emitted-not-rendered` clears 1 finding(s) (UnhandledTap); verify with `pipe check test/fixtures/stuck_loading --rule event-without-handler`
2. [warning/high] loading-not-reset — ItemBloc.twoSwallowedAwaits
why: 85 = warning 50 x high (x1.0), one fix clears 3 findings (+20), no product judgement needed (+15)
fix: Emit a failure/timeout state in the catch (or rethrow) so every loading state is resolved. Applies to each of: <closure>, twoSwallowedAwaits.
where: lib/item_bloc.dart:35, lib/item_bloc.dart:40, lib/item_bloc.dart:53
clears 3 finding(s) (<closure>, twoSwallowedAwaits); verify with `pipe check test/fixtures/stuck_loading --rule loading-not-reset`
14 further cause(s) omitted to stay within 1500 characters. Run `pipe suggest` for the full plan.
``` ```
(Abbreviated and illustrative: the counts are not from a single run. The line (Real output of `pipe suggest test/fixtures/stuck_loading --format agent
shapes, the wording and the score arithmetic are what `suggest --format agent` --budget 1500`, run from the repository root. The budget cut the plan to its top
prints; a dormant union is one finding, so it scores no breadth bonus.) two causes; the omission line says so.)
The score is deliberately simple and always printed, so the order can be argued The score is deliberately simple and always printed, so the order can be argued
with rather than trusted blindly: with rather than trusted blindly:

View file

@ -167,7 +167,7 @@ class WorkPlan {
..write(coverage == null ? '' : '${coverage!.describe()}\n') ..write(coverage == null ? '' : '${coverage!.describe()}\n')
..writeln( ..writeln(
'$totalFindings findings collapse to $totalCauses root cause(s) across ' '$totalFindings findings collapse to $totalCauses root cause(s) across '
'${files.length} file(s). Work them in this order.', '${files.length} file(s).',
) )
..writeln(); ..writeln();
final actions = ordered; final actions = ordered;