view release on metacpan or  search on metacpan

lib/CPAN/Maker/Bootstrapper.pm  view on Meta::CPAN

iterative code review workflow built around JSON review files and
developer-applied disposition annotations. The workflow converges over
several rounds, with each round potentially costing less as noise is
suppressed and findings are resolved.

=head2 Overview

Each review round consists of three steps:

=over 4

=item 1. Run a review

 cpan-maker-bootstrapper code-review \
   --prompt-profile cli-tool \
   lib/My/Module.pm

The review is written to a timestamped C<.code> file containing a JSON
object with C<findings>, C<confirmations>, and C<deferred> arrays.

=item 2. Annotate the findings

 cpan-maker-bootstrapper annotate lib/My/Module.pm

This displays the current annotation state. Apply dispositions with
C<-a> options:

 cpan-maker-bootstrapper annotate \
   -a 1:accept -a 2:wrong -a 3:reject -a 4:defer \
   lib/My/Module.pm

You can annotate incrementally across multiple invocations. Each call
shows the updated state so you always know what remains.

=item 3. Submit the next review

Once all findings are annotated and code updated if necessary, run the
next review. The bootstrapper automatically finds and submits the
latest annotated review file with your updated code:

 cpan-maker-bootstrapper code-review lib/My/Module.pm

Alternatively, use C<--auto-annotate|-A> with the C<annotate> command
to annotate and immediately resubmit in one step:

 cpan-maker-bootstrapper annotate -a 1:wrong -a 2:reject --auto-annotate \
   lib/My/Module.pm

The LLM will honor all dispositions from the prior round, confirm
fixes marked C<ACCEPT>, carry forward C<DEFER> items, and suppress
C<REJECT> and C<WRONG> findings. New findings appear without noise
from settled questions.

=back

=head2 Dry Run Mode

Before your prompt and code are submitted for review, the script will
output a table of showing you the estimated cosst based on token
counts. The input token count is derived by calling the "COUNT TOKEN"
endpoint API with the message to be submitted for review. The input
token count is therefore accurate, while the output token count is an
estimate.

To stop the script for actually submitting the message for review, use
the C<--dry-run> option. This will abort the process immediately prior
to submission.

=head2 Dispositions

Each finding in the annotations file must be given one of the following
dispositions before the next review can be submitted:

=over 4

=item ACCEPT

The finding is valid and has been fixed. On the next review the LLM
will confirm the fix is present. If the fix is not found the finding
will be re-raised.

=item REJECT

The finding has been reviewed and dismissed as inapplicable to this
codebase or context. It will not be raised again in subsequent reviews.

=item WRONG

The finding was based on faulty reasoning. The code is correct. The
finding will not be re-raised. Use this when the LLM has misread the
control flow, misunderstood the design intent, or applied an
inappropriate threat model.

=item WRONG-RECONSIDER

Applied automatically at finalization to all findings marked WRONG.
On the first review of the next version the LLM will re-examine the
specific function and code excerpt carefully. If the prior analysis
was still incorrect the finding reverts to WRONG. If the code has
changed and the finding is now valid it is raised as a new finding.
If the model understands specifically why its prior reasoning was
wrong it may mark the finding CONFIRMED.

=item DEFER

The finding is known and acknowledged but not yet addressed. It is
carried forward in the C<deferred> array of each subsequent review
without being treated as a new finding.

=item CONFIRMED

Used for logic confirmations rather than defects. Marks that both the
LLM and the developer agree the code is correct.

=back

=head2 Diminishing Returns and When to Stop

Run the C<annotate> command after each review submission to view the
findings. Each round tends to surface smaller and more obscure issues
as obvious findings are resolved. Stop when you see these signals: