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 +}); +``` diff --git a/src/prompts.ts b/src/prompts.ts index f5af3c7..593bd33 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. @@ -74,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": []. `; /** @@ -141,8 +147,13 @@ 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. +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()