view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

# THE REVIEW WORKFLOW

`CPAN::Maker::Bootstrapper` allow you implement a structured
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.

## Overview

Each review round consists of three steps:

- 1. Run a review

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

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

- 2. Annotate the findings

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

    This displays the current annotation state. Apply dispositions with
    `-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.

- 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 `--auto-annotate|-A` with the `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 `ACCEPT`, carry forward `DEFER` items, and suppress
    `REJECT` and `WRONG` findings. New findings appear without noise
    from settled questions.

## 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 `--dry-run` option. This will abort the process immediately prior
to submission.

## Dispositions

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

- 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.

- REJECT

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

- 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.

- 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.

- DEFER

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

- CONFIRMED

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

## Diminishing Returns and When to Stop

Run the `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:

- All new findings are LOW severity.
- The LLM is re-raising findings already marked WRONG or REJECT,
possibly rephrased.