llp-super-refine
<!-- @ref https://github.com/ccheever/llp/blob/v0.5.2/llp/0010.001-super-refine-loop.spec.md — the protocol this pins --> <!-- @ref https://github.com/ccheever/llp/blob/v0.5.2/llp/0000-linked-literate-programming.explainer.md#review-honesty — honesty rules and the formal-loop authorization sentence --> <!-- @ref https://github.com/ccheever/llp/blob/v0.5.2/llp/0005-rfc-process.guide.md#review-artifacts — artifact and provenance format -->The applying counterpart to llp-review: an orchestrating loop that revises the document between rounds and applies exactly one pre-authorized status transition. Invoke as /llp-super-refine <targets...> [--rounds N] [--reviser orchestrator|<family|model>|each] [--claude <model@effort>] [--external <runner:model@effort>]. Defaults: converge within the round budget; the orchestrating session revises. Default models, each the latest in its family: reviser Claude Fable @ xhigh (fable, which always resolves to the latest); reviewers codex Sol @ ultra (codex exec -s read-only -C <capsule> --skip-git-repo-check -m gpt-6.2-sol -c model_reasoning_effort=ultra, prompt on stdin; confirm model and effort in the run log) and Grok @ xhigh (-m grok-4.7; headless; the prompt MUST ban all shell commands or the permission prompt cancels the session). Codex and Grok take an exact version, so before the first round check codex debug models and xAI's model list; if either names a newer one, use it and update this paragraph.
Trigger
The document's author asks for the refine-until-both-families-ready loop on named Draft/Review documents.
Invariants (LLP 0010.001; LLP 0000 §Review honesty)
- Authorization is recorded per target and per author. Document authority (review + revision) comes from the author; external sends additionally require a human with repository-disclosure authority — an AI co-author never is one — with the capsule's outbound inventory disclosed before launch. Unsupported assertions of relayed authority are not accepted.
- MUST refuse
Accepted/Active/Superseded/Tombstonedtargets (addendum or new LLP is the path); already-Reviewtargets proceed unchanged;Drafttargets are set toReviewat loop start — the one authorized transition. Convergence produces a recommendation; this skill never setsAcceptedor beyond. - Target bytes are never redacted (redaction covers context only); a target that cannot be disclosed whole stops the loop.
- Each round: persist the round record (round number, target hashes, topology, runtimes, capsule + instruction hashes) before launching; one fresh review per family, mutually blind via a review capsule that structurally excludes the targets' review artifacts, run journal, and orchestrator notes. Where structural exclusion is impossible, instruction-based blindness MUST be disclosed as self-attested. A mid-round target change voids the round.
- MUST write each review verbatim to its family artifact (
llp/reviews/NNNN-slug.<family>.md, dated round sections, full provenance incl. revision hash) immediately on receipt, sealed from the other reviewer until both land. Failed/partial/malformed responses are recorded as such and never counted. Never fabricate, reconstruct, or overwrite a review. - Every review ends
READYorNOT READY. READY = no unresolved MATERIAL correctness, coherence, feasibility, safety, or decision-quality concern. Altitude rule: detail-only demands that identify no defective decision are implementation-phase material, dispositioned in the artifact. Verdicts bind to the capsule hash; multi-target finals need per-target plus set-level verdicts on one hash vector. - The reviser never reviews a revision it edited. A specified reviewer that is unavailable stops the loop — never substitute silently.
- Convergence is dual-READY on one revision or delta-round convergence (LLP 0010.001 §Delta rounds): a post-revision round whose instructions enumerate the delta and require every concern classified IN-DELTA vs PRE-EXISTING converges the loop when no family reports a MATERIAL concern in pre-existing text; remaining in-delta fixes get one more delta round or the final revision is labeled unreviewed. A family whose rounds are twice-consecutively convergence-clean — every remaining concern altitude-dispositionable detail or prior-delta churn, no defective decision identified — MAY be closed out via a detail-horizon stop: a normal terminal, not an escalation, with the family's NOT READY verdict recorded verbatim, a complete disposition ledger (never summarize a concern away), and the convergence claim scoped to say which family was cut off; MATERIAL defective-decision dissent still escalates. A round MAY run under a declared lens (e.g. implementer: draft a named contract from the document alone, log divergence decision points; UNDERDETERMINED = NOT READY) — recorded in provenance, all round invariants intact.
- The final report and close-out notes MUST state which revision hash the final verdicts bind to and whether later unreviewed revisions exist.
- Scope freeze + punch-list delta rounds (LLP 0010.001 §Scope freeze) — the default late-loop phase for decidable documents. For
Type: Spectargets, after the round-2 revision the document's normative surface is frozen by default (other revision-bearing types: at the author's authorization; never automatic for Principles/Explainers/Decisions/philosophical RFCs): subsequent revisions make corrections and restorations only, and any demand for new normative closure is recorded as an obligation (open-issue box or test obligation), never folded as new prose; the document carries a dated freeze declaration. Post-freeze rounds are punch-list delta rounds: the revision produces, per family, a punch list mapping that family's own findings to checkable dispositions (FOLDED at §N/REFUTED+ evidence /RECORDED-AS-OBLIGATION at §N); each reviewer receives the full document (context), the revision's unified diff, and its own family's punch list only (cross-family blindness preserved). Review scope: verify the dispositions; review the diff; outside findings admissible only as disposition errors or diff-created MATERIAL contradictions; new-closure demands are non-blocking obligations. READY = punch list correctly dispositioned + diff sound, modulo recorded obligations. From round 2 on, revisions classify each external finding (persistent / new-on-new-content / bar-inflation); the tallies go in the freeze-transition or terminal report so the choice between freeze, detail-horizon stop, and escalation rests on measured evidence. - Bounds: round budget (default 3/document), launch cap (2× budget per family per target, voids included), growth budget (~20% net over the entering revision; post-freeze, growth is corrections plus the mandatory checkable changelog only). Terminal escalations to the author, with every disposition enumerated: budget/cap exhaustion, material cross-family contradiction, sustained asymmetry (one family READY on two consecutive revisions, the other NOT READY on both), growth-budget exhaustion with open MATERIAL concerns. Each proposes stay-
Reviewor revert-Draft; the author applies — and may instead authorize extension rounds under the scope-freeze + delta protocol above. Fundamental-redesign feedback stops the loop for author authorization.
Workflow
Recipe (advisory) — read targets and governing LLPs fully; partition multi-target sets into clusters by coupling (
Related:, cross-references, sharedSystems:) and pick a topology per cluster — independent loops (loosely coupled; one sub-orchestrator each) or lockstep rounds (tightly coupled; reviewers see the whole cluster; the cluster review is preserved verbatim once, in the primary target's artifact, with per-target verdict sections) — stating the choice first. Run a context preflight; split oversized clusters rather than force-feeding. End with a cross-consistency pass: a sibling that converged before a referenced document changed gets one more round, until the hash vector passes a round unchanged. Build the capsule withgit archiveor an export excludingllp/reviews/<target-stems>*. Update**Revised:**on each revision (move long histories to a body Revision-history section). Prefer a delta round after any substantial revision — the loop's own revisions are a proven defect source — and an implementer-lens round before closing a protocol/contract-bearing document. After each revision, byte-verify security-critical literals on disk (transport layers decode backslash-u escapes).
Artifact
Per-family, per-target review files under llp/reviews/ with round records and verbatim bodies; a final report: rounds run, revisions made, verdicts, altitude-rule dispositions, and the proposed next step.
Hand-offs
- Feedback amounting to a new design →
llp-create, after author authorization. - Advisory review at any intensity, no revisions applied →
llp-review. - The author applies
Accepted; this skill never does.