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.
```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.
Coverage: 814 of 814 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.
Coverage: 12 of 12 discovered file(s) analysed (0 failed, 0 skipped by analysis_options or context).
20 findings collapse to 16 root cause(s) across 8 file(s).
1. [warning/high] emitted-not-rendered — CommentsState (CommentsBloc)
why: 75 = warning 50 x high (x1.0), user-visible failure (+25)
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.
where: lib/blocs/comment/comment_bloc.dart:143
clears 1 finding(s) (CommentSubmitError, CommentSubmitSuccess, CommentSubmitting, CommentsError, CommentsLoaded, CommentsLoading); verify with `pipe check /path/to/app --rule emitted-not-rendered`
1. [error/high] event-without-handler — HandlerGapEvent (GapBloc)
why: 115 = error 100 x high (x1.0), no product judgement needed (+15)
fix: Add `on<UnhandledTap>(...)` to GapBloc, or stop dispatching UnhandledTap.
where: lib/gaps.dart:74
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
shapes, the wording and the score arithmetic are what `suggest --format agent`
prints; a dormant union is one finding, so it scores no breadth bonus.)
(Real output of `pipe suggest test/fixtures/stuck_loading --format agent
--budget 1500`, run from the repository root. The budget cut the plan to its top
two causes; the omission line says so.)
The score is deliberately simple and always printed, so the order can be argued
with rather than trusted blindly:

View file

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