Documentation
¶
Overview ¶
Package prompts holds the byte-verbatim Go ports of every LLM prompt builder in PR-AF's Python source of truth: the reasoner system/task prompts in reasoners/harnesses.py, the merge-gate classification prompt in merge_gate.py, the polish prompt in polish.py, and the coverage-gap review prompt in orchestrator.py.
Each builder renders output that is byte-identical to the Python f-string / str-concat builder for the same inputs, including:
- Python str()/repr() formatting of interpolated lists (e.g. the compound dedup `Tags: ['a', 'b']` single-quoted list repr),
- f-string float formatting (str(float) and `{x:.2f}`),
- json.dumps(..., default=str) context blocks (insertion-ordered keys, ", "/": " separators, ensure_ascii escaping) via the pyjson encoder, and
- Python truthiness for the optional prompt sections.
The reasoner packages (T3.1) and the gates package (T3.2) import these builders instead of embedding prompt strings, so there is exactly one copy of each prompt and the golden tests (testdata/*.txt, generated by scripts/gen_golden.py from the real Python builders) pin it byte-for-byte.
Index ¶
- Constants
- func AdversaryPrompt(findings []schemas.ReviewFinding, aiGeneratedConfidence float64, ...) string
- func AnatomyPrompt(intake schemas.IntakeResult, prTitle, prDescription string, prLabels []string, ...) string
- func CompoundDedupPrompt(findings []schemas.ReviewFinding, individualFindingsSummary string) string
- func CompoundFinderPrompt(findings []schemas.ReviewFinding, repoPath string, ...) string
- func CoverageGapPrompt(gap string) string
- func CoverageGatePrompt(anatomy schemas.AnatomyResult, ...) string
- func DeepenFindingsPrompt(diffPatches []StrPair, existingTitles []string, repoPath, prContext string) string
- func EvidenceVerifierPrompt(findings []schemas.ReviewFinding, evidenceMap map[string]*OMap, ...) string
- func ExtractObligationsPrompt(diffPatches []StrPair, repoPath, prContext string) string
- func IntakeFallbackPrompt(title, description, requestedDepth string, languages []string, ...) string
- func IntakeGatePrompt(title, description string, labels []string, author string, filesChanged int, ...) string
- func MergeGateUserPrompt(f schemas.ScoredFinding) string
- func MetaContext(intake schemas.IntakeResult, anatomy schemas.AnatomyResult, ...) string
- func MetaMechanicalPrompt(context, repoPath, depth string) string
- func MetaSemanticPrompt(context, repoPath, depth string) string
- func MetaSystemicPrompt(context, repoPath, depth string) string
- func PlanningPrompt(intake schemas.IntakeResult, anatomy schemas.AnatomyResult, depth string, ...) string
- func PolishUserPrompt(body string) string
- func PostWorthinessPrompt(findings []schemas.ScoredFinding) string
- func PyJSON(v any) string
- func ReviewDimensionPrompt(o ReviewDimensionOptions) string
- func VerifyObligationPrompt(where, reliesOn, property string) string
- type OMap
- type ReviewDimensionOptions
- type StrPair
Constants ¶
const CoverageGateSystem = "Analyze the coverage state and return the structured result."
CoverageGateSystem is the system prompt for the coverage_gate .ai() call.
const IntakeGateSystem = "Return pr_type, complexity, and confident only. Use the provided schema."
IntakeGateSystem is the system prompt for the intake .ai() gate.
const MergeGateSystem = "You are the release manager for an automated code reviewer. Your job is to " +
"decide whether a single review finding must be fixed BEFORE this PR is merged, " +
"or whether the team can safely merge now and address it later.\n" +
"\n" +
"Apply a TIGHT bar. Only call something `blocking` if at least one is true:\n" +
" - It breaks the build, tests, or type-checking.\n" +
" - It introduces a security vulnerability reachable from a real user-facing " +
"code path (auth bypass, injection, credential leak, RCE, exposed secret, " +
"missing access control on a route real clients hit).\n" +
" - It causes data loss, data corruption, or irreversible state damage in " +
"production-running code.\n" +
" - It breaks an existing public API/CLI/schema contract that real callers " +
"depend on, with no migration path.\n" +
" - It is a regression of behavior that was working before this PR.\n" +
"\n" +
"Treat the following as NON-blocking (return blocking=false):\n" +
" - Code quality, style, naming, refactor opportunities.\n" +
" - Missing tests for edge cases, low test coverage, mock signature drift in " +
"test helpers.\n" +
" - Defensive programming opportunities, missing input validation that has " +
"no demonstrated reachable exploit path.\n" +
" - Performance suggestions that don't change correctness.\n" +
" - Documentation, comments, README, type-hint completeness.\n" +
" - 'Should also handle X' suggestions when X isn't currently reachable.\n" +
" - Architectural critiques (DRY, single source of truth, layering) without a " +
"concrete production impact described in the finding.\n" +
" - Issues whose reachability or exploitability the finding itself cannot " +
"demonstrate concretely.\n" +
"\n" +
"If the finding's evidence does NOT concretely demonstrate one of the blocking " +
"criteria above — even when the severity is labeled 'critical' — return " +
"blocking=false. Reviewers are often alarmist; you are the calibrating layer.\n" +
"\n" +
"Output strict JSON with this exact shape and nothing else:\n" +
` {"blocking": true | false, "reason": "<one short sentence>"}` + "\n" +
"Do not add prose. Do not wrap in markdown fences. JSON only."
MergeGateSystem ports merge_gate._MERGE_GATE_SYSTEM.
const PolishSystem = "You rewrite GitHub PR review comments. A good PR comment tells the author " +
"exactly what to fix and why, so they can act in under 30 seconds. Open with a " +
"one-sentence directive. Then one short paragraph (2-3 sentences) on the concrete " +
"failure mode — no abstract security lectures, no 'attacker-controlled' filler. " +
"Preserve every file path, line number, identifier, code block, markdown " +
"header, GitHub alert callout (`> [!CAUTION]`, `> [!NOTE]`), `<details>` block, " +
"and `<sub>` line verbatim. Never invent facts. Never soften severity. Output " +
"the polished comment body only — no preamble, no commentary."
PolishSystem ports polish._POLISH_SYSTEM.
Variables ¶
This section is empty.
Functions ¶
func AdversaryPrompt ¶
func AdversaryPrompt(findings []schemas.ReviewFinding, aiGeneratedConfidence float64, prContext, repoPath string, evidenceMap map[string]*OMap) string
AdversaryPrompt ports adversary_phase. Skepticism escalates to "high" when the AI-generated confidence exceeds 0.5; the extra skepticism line appears on the same condition. has_evidence is bool(evidenceMap).
func AnatomyPrompt ¶
func AnatomyPrompt(intake schemas.IntakeResult, prTitle, prDescription string, prLabels []string, clusters []schemas.ChangeCluster, stats schemas.DiffStats, blastRadiusCount int, files []schemas.FileChange) string
AnatomyPrompt builds the anatomy_phase prompt. clusters/stats/blastRadiusCount/ files are the deterministic diff-engine outputs (T2.1) the reasoner computed; they are passed in typed so this builder never touches diff parsing.
func CompoundDedupPrompt ¶
func CompoundDedupPrompt(findings []schemas.ReviewFinding, individualFindingsSummary string) string
CompoundDedupPrompt ports compound_dedup_phase. Caller invokes only when len(findings) > 1. The Tags field interpolates as a Python list repr (single-quoted).
func CompoundFinderPrompt ¶
func CompoundFinderPrompt(findings []schemas.ReviewFinding, repoPath string, evidenceMap map[string]*OMap) string
CompoundFinderPrompt ports compound_finder_phase. Caller invokes only when len(findings) >= 2. evidenceMap is keyed by finding title; each value is the raw evidence package (rendered verbatim into cluster_evidence and mined for the per-finding evidence_package sub-object).
func CoverageGapPrompt ¶
CoverageGapPrompt ports orchestrator._build_gap_dimensions' review_prompt.
func CoverageGatePrompt ¶
func CoverageGatePrompt(anatomy schemas.AnatomyResult, reviewedClusters, dimensionNamesReviewed []string) string
CoverageGatePrompt builds the coverage_gate user prompt. The cluster payload here is keyed id, name, description, files (no primary_language — distinct from _cluster_descriptions).
func DeepenFindingsPrompt ¶
func DeepenFindingsPrompt(diffPatches []StrPair, existingTitles []string, repoPath, prContext string) string
DeepenFindingsPrompt ports deepen_findings. Caller invokes only when there is at least one non-empty patch. existingTitles is truncated to 40 and joined with "; " (empty -> "none").
func EvidenceVerifierPrompt ¶
func EvidenceVerifierPrompt(findings []schemas.ReviewFinding, evidenceMap map[string]*OMap, prContext, repoPath string) string
EvidenceVerifierPrompt ports evidence_verifier. evidenceMap is keyed by finding title.
func ExtractObligationsPrompt ¶
ExtractObligationsPrompt ports extract_obligations. Caller invokes only when there is at least one non-empty patch.
func IntakeFallbackPrompt ¶
func IntakeFallbackPrompt(title, description, requestedDepth string, languages []string, filesChanged int) string
IntakeFallbackPrompt builds the intake_phase .harness() fallback prompt. description is truncated to the first 4000 runes.
func IntakeGatePrompt ¶
func IntakeGatePrompt(title, description string, labels []string, author string, filesChanged int, languages, commitMessages []string) string
IntakeGatePrompt builds the intake .ai() gate user prompt. languages must be pre-sorted (the reasoner uses sorted(_extract_languages(pr))); commitMessages is truncated to the first 5 and description to the first 4000 runes, matching the Python json payload.
func MergeGateUserPrompt ¶
func MergeGateUserPrompt(f schemas.ScoredFinding) string
MergeGateUserPrompt ports merge_gate._build_user_prompt: the per-finding user prompt. Evidence and Suggested-fix sections are included only when truthy (Python `if finding.evidence` / `if finding.suggestion`).
func MetaContext ¶
func MetaContext(intake schemas.IntakeResult, anatomy schemas.AnatomyResult, diffPatches []StrPair, reviewerFeedback string) string
MetaContext ports _build_meta_context: the shared json context string all three meta selectors interpolate. diffPatches is added only when non-empty (Python `if diff_patches:`), truncated to the first 15 pairs in order; reviewerFeedback is added only when non-empty.
func MetaMechanicalPrompt ¶
MetaMechanicalPrompt builds the meta_mechanical selector prompt.
func MetaSemanticPrompt ¶
MetaSemanticPrompt builds the meta_semantic selector prompt.
func MetaSystemicPrompt ¶
MetaSystemicPrompt builds the meta_systemic selector prompt.
func PlanningPrompt ¶
func PlanningPrompt(intake schemas.IntakeResult, anatomy schemas.AnatomyResult, depth string, hints []string) string
PlanningPrompt builds the planning_phase prompt.
func PolishUserPrompt ¶
PolishUserPrompt ports polish._polish_one's user prompt.
func PostWorthinessPrompt ¶
func PostWorthinessPrompt(findings []schemas.ScoredFinding) string
Ports post_worthiness_gate's prompt from reasoners/harnesses.py. The caller only invokes this when len(findings) > 1 (Python early-returns otherwise).
func PyJSON ¶
PyJSON renders v exactly as Python's json.dumps(v, default=str): ", "/": " separators, insertion-ordered *OMap keys, ensure_ascii escaping, and Python float repr. Exported so the reasoners can write context files whose content is byte-identical to the JSON blocks the prompt builders embed or reference.
func ReviewDimensionPrompt ¶
func ReviewDimensionPrompt(o ReviewDimensionOptions) string
ReviewDimensionPrompt builds the review_dimension reviewer prompt.
func VerifyObligationPrompt ¶
VerifyObligationPrompt ports verify_obligation's single-obligation prompt.
Types ¶
type OMap ¶
type OMap struct {
// contains filtered or unexported fields
}
OMap is an insertion-ordered JSON object. The reasoners build their context payloads with a fixed key order, so callers construct these with omap(...) and the encoder preserves that order — matching Python dict repr / json.dumps.
func NewOMap ¶
func NewOMap() *OMap
NewOMap returns an empty insertion-ordered JSON object, ready for Set calls. It is the exported counterpart of the package-private omap() constructor.
func (*OMap) GetStr ¶
GetStr returns the string value at key, or def if absent/not a string — mirroring Python dict.get(key, default) followed by use as a string.
func (*OMap) GetStrSlice ¶
GetStrSlice returns the []string value at key, or an empty slice if absent.
type ReviewDimensionOptions ¶
type ReviewDimensionOptions struct {
ReviewPrompt string
TargetFiles []string
ContextFiles []string
RepoPath string
CurrentDepth int
MaxDepth int
PrNarrative string
RiskSurfaces []string
IntakeSummary string
PrDescription string
DiffPatches map[string]string
AllDimensionNames []string
ReviewerFeedback string
PrimedCode string
}
ReviewDimensionOptions mirrors the review_dimension reasoner signature.