view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

## 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
you should 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 (LLMs can and do make mistakes!).
- New findings describe edge cases that cannot occur in normal usage.

When all findings have dispositions and no new substantive issues
appear, the code is ready to ship.

## The Release Artifact

When you are satisfied with the review state, finalize it with
`--finalize-annotations`:

    cmb annotate --finalize-annotations -a 1:wrong -a 2:reject lib/My/Module.pm

This applies any remaining dispositions, validates that all findings
are annotated, reads the version from the `VERSION` file, and writes
the versioned release artifact:

    CPAN-Maker-Bootstrapper-1.1.0-REVIEW.json

This file serves as a code review certification for the release - a
machine-readable record of every finding examined, every logic
confirmation made, and every disposition applied before the version
was published. Commit it to the repository alongside your ChangeLog.

All findings marked WRONG are automatically converted to
WRONG-RECONSIDER in the release artifact, prompting careful
re-examination on the first review of the next version rather
than permanent suppression.

## Cost Management

Typical review costs run $0.05-0.10 per run on a moderately sized
module with POD stripped depending on the model you choose. The
default model used for POD review is `claude-haiku-4-5-20251001` and
`claude-sonnet-4-6` for code review. Costs decrease over successive
rounds as the model spends fewer output tokens re-explaining
suppressed findings.

Use your own prompt profiles (`--prompt-profile`) to suppress entire
classes of noise before they reach the annotation file. A well-tuned
profile for your application type is the highest-leverage cost
reduction available.

## See Also

["LLM Commands"](#llm-commands), ["PROMPT PROFILES"](#prompt-profiles), [CPAN::Maker::ConfigReader](https://metacpan.org/pod/CPAN%3A%3AMaker%3A%3AConfigReader)

# PROMPT PROFILES

Prompt profiles are additive prompt fragments that customize the review
behavior for specific application types. They are appended to the base
review prompt before submission and are intended to focus the review on
relevant concerns while suppressing noise that does not apply to the
target context.

_NOTE: Prompts count toward your input token count. Be succinct and
accurate._

## Using Profiles

Pass one or more profiles using the `--prompt-profile` option:

    cmb code-review --prompt-profile cli-tool MyModule.pm

Multiple profiles may be combined:

    cmb code-review --prompt-profile cli-tool --prompt-profile security MyModule.pm

Profiles are resolved from the `.prompts/` directory in the current
project. A profile named `cli-tool` resolves to
`.prompts/cli-tool.prompt`. Add your own prompt profiles and commit
them to your project.

### Built-in Profiles

The following profile is installed with the distribution:

- cli-tool

    Appropriate for single-user developer CLI tools. Suppresses security
    findings that assume a multi-user or hostile environment, TOCTOU race
    condition findings that assume concurrent invocation, and concerns about
    `qx{}` or `system()` calls where input originates from the user's own
    configuration. Also assumes `perlcritic` and `perltidy` are enforced
    in the development environment.

### Creating Custom Profiles

A profile is a plain text file in `.prompts/` containing additional
prompt instructions, one per line. Lines beginning with `#` are treated
as comments and stripped before submission. Profile instructions use the
same format as the base review prompt.

Example `.prompts/security.prompt`:

    # security profile - add to any review where input handling matters
    - Treat all caller-supplied input as untrusted regardless of source.
    - Flag any use of eval, system, or exec that incorporates external data.
    - Flag missing taint checks on data used in file or system operations.

### Planned Profiles

The following profiles are planned for future releases:

- library

    Focuses on API contract correctness and caller assumptions. Appropriate
    for CPAN distributions intended for use by unknown callers.

- web-application