From c631d63eb48095a8aec496c891a04a49b055e0e1 Mon Sep 17 00:00:00 2001 From: JStaRFilms Date: Sun, 14 Dec 2025 11:10:17 +0100 Subject: [PATCH 1/3] refactor(prompts): add anti-hallucination and grounding rules - Enforce English-only output and strict context grounding - Prevent hallucination of unlisted files or resume-related terms --- src/prompts.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/prompts.ts b/src/prompts.ts index f5af3c7..dfc1463 100644 --- a/src/prompts.ts +++ b/src/prompts.ts @@ -51,6 +51,11 @@ Your goal is to find BUGS, SECURITY RISKS, LOGIC ERRORS, and **DOCUMENTATION GAP - If you see hardcoded usernames like "johndoe" or "demo" with a TODO comment, this is intentional dev scaffolding - Only flag these are security issues if there's NO indication it's a dev placeholder +8. **ANTI-HALLUCINATION (STRICT):** + - **LANGUAGE:** Output MUST be in ENGLISH. Do NOT use Korean (e.g., "직책"), Russian, or Chinese. + - **CONTEXT:** You are reviewing CODE, not a resume or job application. Do NOT mention "hiring", "job title", "professional journey". + - **GROUNDING:** Only report findings for files explicitly listed in the "FILES CHANGED" list. Do not invent filenames like "src/orchestrator.html". + ### THE J STAR TONE MATRIX: - **Authority:** High. Don't say "I think" or "maybe". Say "This causes X" or "This will fail when Y". - **Brevity:** High. Max 2 sentences per finding. No filler words. @@ -141,6 +146,10 @@ RULES: 4. Documentation is per-FEATURE not per-file. Check if feature doc exists before flagging. 5. **DELETED FILES:** If status is [removed], DO NOT report bugs in the code. ONLY report if the deletion is dangerous (e.g. missing auth replacement). 6. Hardcoded test usernames (johndoe, demo) with TODO comments are dev placeholders, not security issues. +7. **STRICT GROUNDING:** + - **ENGLISH ONLY.** + - Do NOT output "직책" or resume terms. + - You are reviewing a Git Diff, not a website about a person. Output strict JSON only. `; From 671b441119f74a3ee47819b9c19751ccabffbf45 Mon Sep 17 00:00:00 2001 From: JStaRFilms Date: Sun, 14 Dec 2025 11:13:26 +0100 Subject: [PATCH 2/3] docs(features): add prompts documentation --- docs/features/prompts.md | 52 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/features/prompts.md diff --git a/docs/features/prompts.md b/docs/features/prompts.md new file mode 100644 index 0000000..c5ae4bd --- /dev/null +++ b/docs/features/prompts.md @@ -0,0 +1,52 @@ +# Prompts & Persona (`src/prompts.ts`) + +## Purpose +The Central Brain of J Star. This module exports the System Prompts and User Prompt builders that define the bot's persona, rules, and output format. It serves as the single source of truth for how the AI "thinks" and "speaks". + +## Core Exports + +### 1. System Prompts +- **`TRIAGE_SYSTEM_PROMPT`**: The "Gatekeeper". Designed for speed and cost-efficiency. It classifies PRs to decide if a deep review is necessary. +- **`ANALYST_SYSTEM_PROMPT`**: The "Sentinel". The main logic for deep code review. It enforces the "Strict Senior Engineer" persona and demands strict JSON output. +- **`CHUNK_REVIEW_SYSTEM_PROMPT`**: The "Worker". A specialized prompt for reviewing single files in isolation, used during Map-Reduce operations for large PRs. + +### 2. Prompt Builders +- **`buildAnalystUserPrompt`**: Mechanisms to assemble the context window. It intelligently injects: + - The list of files to audit. + - The diff (truncated if necessary). + - **Existing Documentation Inventory** (to prevent false "missing docs" flags). +- **`buildChunkReviewPrompt`**: Creates a highly focused prompt for a single file, injecting project architecture and relevant feature docs context. + +## Guardrails & Anti-Hallucination +The prompts have been battle-hardened against specific failures: + +1. **Strict JSON Enforcement**: Explicit rules to prevent the model from translating JSON keys (e.g., `verdict` -> `овердикт`) or outputting Markdown code fences. +2. **Context Anchoring**: Constraints to stop the model from hallucinating that it is reviewing a Resume or Job Application (preventing "Job Title/직책" errors). +3. **Deleted Code Safety**: Strict instructions to ignore bugs in lines starting with `-`, as they no longer exist. +4. **Line Number Precision**: Requirements to output specific line numbers for every finding. + +## Usage Example + +```typescript +import { ANALYST_SYSTEM_PROMPT, buildAnalystUserPrompt } from './prompts'; + +// 1. Initialize with the System Prompt +const systemMessage = ANALYST_SYSTEM_PROMPT; + +// 2. Build the User Context +// Injects the diff and awareness of existing docs to avoid false positives +const userMessage = buildAnalystUserPrompt( + ['src/auth.ts', 'src/types.ts'], // Files to focus on + ['src/auth.ts', 'src/types.ts', 'README.md'], // All files + diffString, // The git diff + ['auth.md', 'architecture.md'] // List of existing doc files +); + +// 3. Generate Response (using Vercel AI SDK) +const response = await generateObject({ + model: groq('moonshotai/kimi-k2-instruct-0905'), + system: systemMessage, + prompt: userMessage, + schema: JStarReviewSchema +}); +``` From f5d6659438a6f8347d8a569ab30aff5c22e75a98 Mon Sep 17 00:00:00 2001 From: JStaRFilms Date: Sun, 14 Dec 2025 11:17:48 +0100 Subject: [PATCH 3/3] feat(types): add line number field and default empty findings to review schemas Add "line" property to findings for precise issue location and set default empty arrays to handle cases with no findings, improving schema robustness and prompt accuracy. --- src/prompts.ts | 4 +++- src/types.ts | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/prompts.ts b/src/prompts.ts index dfc1463..593bd33 100644 --- a/src/prompts.ts +++ b/src/prompts.ts @@ -79,8 +79,9 @@ You MUST include both "summary" and "findings" fields.Do not omit the summary. JSON Structure: { "summary": { "quality_score": 0 - 100, "verdict": "APPROVE" | "REQUEST_CHANGES" | "COMMENT", "tone": "encouraging" | "critical" | "neutral" }, - "findings": [{ "file": "...", "severity": "...", "category": "...", "title": "...", "message": "...", "fix_prompt": string | null }] + "findings": [{ "file": "...", "severity": "...", "category": "...", "title": "...", "message": "...", "fix_prompt": string | null, "line": number }] } +IMPORTANT: If there are no findings, return "findings": []. `; /** @@ -152,6 +153,7 @@ RULES: - You are reviewing a Git Diff, not a website about a person. Output strict JSON only. +IMPORTANT: If no issues found, return "findings": [] and a high quality score. `; /** diff --git a/src/types.ts b/src/types.ts index 0a2cefb..e77a106 100644 --- a/src/types.ts +++ b/src/types.ts @@ -113,6 +113,7 @@ export const JStarReviewSchema = z.object({ summary: SummarySchema.describe('High-level summary of the review.'), findings: z .array(FindingSchema) + .default([]) .describe('List of all issues found. Can be empty if code is clean.'), }); @@ -130,6 +131,7 @@ export const ChunkReviewSchema = z.object({ file: z.string().describe('The file being reviewed'), findings: z .array(FindingSchema) + .default([]) .describe('Issues found in this specific file. Can be empty if clean.'), quality_score: z .number()