view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

    Defaults to `user.name` from your global git config.

# 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

        cmb 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

    An annotation is how you mark a finding with a disposition. The
    dispositions are used by the LLM during thenext review. See ["Dispositions"](#dispositions).

        cmb annotate lib/My/Module.pm

    This displays the current annotation state. Apply dispositions with
    `-a` options:

        cmb 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:

        cmb code-review lib/My/Module.pm

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

        cmb 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
dispositions describe below before the next review can be
submitted. The prompt sent to the LLM is designed around these
dispositions. This helps the LLM produce findings that hopefully will
converge on a clean review.

- 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. Despite some fairly aggressive
attempts to create prompts that prevent trivial or obscure findings