Napierce

Napierce is a small CLI for planning human-review-bounded candidate generation.

It helps you decide how many AI-generated candidates to create, how many should be used for broad exploration, and how many a human can realistically review under a fixed time budget.

Napierce is CLI-first and CLI-complete for the v0.1.0 workflow:

plan -> review -> summarize

It is useful for writing, documentation, prompt improvement, specification cleanup, UI copy refinement, code-repair review, and other workflows where AI can generate more candidates than humans can read.

Napierce is not a web search tool. It is not a direct implementation of the classical secretary problem. It is not mainly an AI-agent runner. It does not call LLM APIs or generate candidates by itself.

Napierce treats the 1/e idea as a practical budgeting heuristic for deciding where broad exploration should end and review-gated refinement should begin.

Core idea

AI can generate candidates faster than humans can read, compare, and judge them.

That means the main limit is often not generation speed. The main limit is human review capacity.

Napierce turns generation time, review time, and latency estimates into a bounded candidate plan:

1. Define the improvement goal.
2. Define the human review criteria.
3. Estimate generation latency per candidate.
4. Measure or estimate human review time per candidate.
5. Compute how many candidates can be generated.
6. Compute how many candidates can actually be reviewed.
7. Use about N / e generated candidates for broad exploration.
8. Use the remaining generated candidates for focused refinement.
9. Save all candidates.
10. Reduce them to a small reviewable candidate set.
11. Let the human choose from that finite set.

The goal is not to let an LLM optimize text or code indefinitely. The goal is to produce a bounded, diverse, reviewable candidate set for human judgment.

Quick start

From a local checkout, run the CLI directly with Node:

node bin/napierce.js --help

Create a candidate plan:

node bin/napierce.js plan \
  --generate-budget 20m \
  --generation-p95 30s \
  --review-budget 15m \
  --review-p95 90s \
  --oversample 3 \
  --json

Create a small candidate file:

cat > candidates.jsonl <<'EOF'
{"candidate_id":"cand_001","content":"First candidate text."}
{"candidate_id":"cand_002","text":"Second candidate text."}
{"candidate_id":"cand_003","body":"Third candidate text."}
EOF

Review candidates interactively:

node bin/napierce.js review \
  --candidates candidates.jsonl \
  --out review-events.jsonl

Then summarize the saved review events:

node bin/napierce.js summarize --events review-events.jsonl --json

If Napierce is installed as a package, use napierce instead of node bin/napierce.js.

Documentation

• User guide: practical step-by-step guide for using Napierce.
• Design: product design, CLI modes, data model, stopping conditions, and MVP scope.
• Research notes: research basis for human review, evaluation limits, workload, and testability.
• Rationale: classical 1/e proof, review-bounded planning model, and claim boundaries.
• Changelog: release history and known limitations.

Human review timing

For subjective artifacts such as prose, documentation, specifications, and prompts, final quality is judged by a human reader.

Napierce therefore treats review time as first-class data.

A workflow can record events such as:

• candidate opened,
• candidate read,
• candidate skipped,
• candidate accepted,
• candidate rejected,
• next candidate clicked.

From those events, Napierce can estimate:

• mean review time,
• standard deviation,
• p50 / p90 / p95 review time,
• reviewable candidate count under a fixed review budget.

Different candidate types take different amounts of time to read. A short UI label, a paragraph rewrite, a README section, and a code patch should not be treated as the same review unit.

The first version can use simple timing logs. Later versions can group timings by task type, artifact type, length bucket, or review mode.

Why 1/e?

The 1/e split is inspired by optimal stopping theory. In the classical setting, about the first N / e observations are used to learn a baseline, and later observations are compared against that baseline.

Napierce does not assume that AI workflows exactly satisfy that model. AI-generated candidates can usually be saved, compared later, revised, and filtered by human review or tests.

Therefore, Napierce uses N / e as an exploration-budget rule:

• the first phase explores the task and collects diverse candidates,
• the second phase refines promising directions,
• the final review set is selected from all saved candidates,
• the goal is practical bounded improvement, not a universal optimality claim.

The point is to avoid endless generation when the real limits are time, review attention, and decision quality.

For the classical proof and the agent-side improvement conditions, see docs/rationale.md.

Commands

napierce plan

napierce plan \
  --generate-budget 20m \
  --generation-p95 30s \
  --review-budget 15m \
  --review-p95 90s \
  --oversample 3 \
  --json

Example JSON output:

{
  "generation_budget_seconds": 1200,
  "review_budget_seconds": 900,
  "generation_latency_seconds": 30,
  "review_latency_seconds": 90,
  "max_generated_candidates": 40,
  "reviewable_candidates": 10,
  "oversample": 3,
  "planned_candidates": 30,
  "explore_candidates": 12,
  "refine_candidates": 18,
  "final_review_candidates": 10,
  "strategy": "review_bounded_generation_p95_review_p95"
}

napierce review

napierce review \
  --candidates candidates.jsonl \
  --out review-events.jsonl \
  --criteria criteria.md

This shows candidates one at a time in the CLI and records elapsed review seconds, action, optional score, and optional note as JSONL.

review is interactive. It does not support --json; use napierce summarize --events review-events.jsonl --json after the review session when JSON summary output is needed.

napierce summarize

napierce summarize --events review-events.jsonl --json

This reports review counts, mean review time, standard deviation, p50/p90/p95 review time, top candidates, and stopping reasons.

Candidate input

MVP candidate records must embed reviewable text directly in the JSONL record.

Valid text fields:

{"candidate_id":"cand_001","content":"First candidate text."}
{"candidate_id":"cand_002","text":"Second candidate text."}
{"candidate_id":"cand_003","body":"Third candidate text."}

File-backed candidate loading through content_path is not part of v0.1.0.

Use cases

• Produce multiple writing candidates without making the human read everything.
• Bound document or specification editing passes.
• Limit repeated prompt improvement loops.
• Decide how many code-repair candidates to generate before review.
• Split a fixed generation budget into exploration and refinement phases.
• Convert human review time into a finite reviewable candidate count.
• Keep AI output reviewable instead of letting revisions grow without a stopping rule.

Non-goals

Napierce will not initially:

• run agents directly,
• call LLM APIs,
• judge final output quality by itself,
• automatically merge code,
• replace human review,
• claim a universal optimal stopping theorem for all AI workflows.

The first version should stay small: calculate bounded candidate plans, record review events, and summarize review evidence.

MVP

The current CLI provides:

• napierce plan for calculating bounded candidate plans,
• napierce review for recording human review events,
• napierce summarize for aggregating review timings and scores,
• support for generation budget and generation latency,
• support for review budget and review latency,
• support for --p95, --mean, --sd, and safety factors,
• support for an oversampling ratio,
• JSON output for scripts and agent tools on plan and summarize,
• human-readable output for CLI use,
• tests for duration parsing, budget calculation, summarization, and CLI smoke behavior.

Formula

Let:

T_g = generation time budget
L_g = safe generation latency per candidate
T_r = human review time budget
L_r = safe human review time per candidate
rho = oversampling ratio

Then:

max_generated = floor(T_g / L_g)
reviewable = floor(T_r / L_r)
planned = min(max_generated, ceil(rho * reviewable))
explore = ceil(planned / e)
refine = planned - explore
final_review = reviewable

Review latency can come from direct measurement:

L_r = p95(review_time_samples)

or from a conservative estimate:

L_r = mean(review_time_samples) + lambda * standard_deviation(review_time_samples)

This is mathematically testable as a workflow rule. A baseline workflow can be compared against Napierce by measuring final human-rated quality, review time, generated candidate count, and reviewable candidate count.

This is still a heuristic for practical planning. It reuses the 1/e split as a bounded exploration rule for saved, reviewable AI-generated candidates.

Status

Experimental CLI MVP.

The current goal is to make candidate generation and human review limits explicit, reproducible, and easy to inspect.

License

Apache-2.0. See LICENSE.