Prompt Engineering Guide (Arlis Edition)

Core Philosophy: The Forensic Advocate

In Arlis, prompt engineering is not just about getting the right answer; it's about embodying the advocacy mission.

Every prompt must find the balance between:

1. •Rigorous Precision (Forensic Audit, Government Compliance)
2. •Warm Empathy (Social Worker, Bureaucracy Buddy)

Key Principles

1. •Role & Identity: Every prompt must define Arlis's specific role for that task (e.g., "The Jargon Shield" vs. "The Audit Brain").
2. •Actionable Instructions: Break tasks down into atomic steps. Arlis doesn't "help"; Arlis "analyzes, plans, and executes".
3. •Few-Shot Examples: Always provide input/output examples. This is critical for reliable JSON extraction from messy government forms.
4. •Empathy Constraints: While being precise, errors must be handled gently. (e.g., Rule: "Never say 'User is wrong', say 'Let's verify this value'").
5. •Thinking Process: Use <think> tags (Gemini 3 Pro) for complex reasoning tasks like policy interpretation or form logic cross-referencing.

The Standard Protocol

All prompts in lib/ai/prompts.ts MUST follow this structure:

1. •ROLE: Identity (e.g., ROLE_FORENSIC_ADVOCATE).
2. •SKILLS: Specific capabilities (e.g., SKILLS_PLAIN_LANGUAGE).
3. •WORKFLOW: Step-by-step execution plan.
4. •RULES: Hard constraints and formatting requirements.
5. •EXAMPLES: Concrete input -> output pairs.

Anti-Patterns to Avoid

Implementation Patterns

1. Using the buildPrompt Utility

We have a TypeScript utility in lib/ai/prompts.ts to enforce this structure.

Example Usage:

import { buildPrompt, AI_SYSTEM_PROTOCOL } from '@/lib/ai/prompts';

export const MY_PROMPT = buildPrompt({
  role: AI_SYSTEM_PROTOCOL.ROLE_FORENSIC_ADVOCATE,
  skills: [
    "Optical Character Recognition",
    "Data Verification"
  ],
  rules: [
    "Output must be valid JSON",
    "Flag any mismatches found"
  ],
  workflow: [
    "Scan document",
    "Compare with database",
    "Report findings"
  ],
  examples: [
    {
      input: "Income: 5000",
      output: '{"verified": true}',
      explanation: "Income matches paystub."
    }
  ],
  thinkingRequired: true
});

Checklist for New Prompts

Before committing a new prompt, verify:

• • Identity Check: Does it sound like Arlis (Advocate + Auditor)?
• • Workflow Steps? Are the steps atomic and actionable?
• • Examples Included? Are there at least 1-2 examples? (Crucial for messy OCR)
• • Constraints Specific? Are limits quantitative?
• • Thinking Enabled? Is <think> used for complex reasoning?
• • JSON/Format Valid? If outputting JSON, are the rules strict?

Resources

This approach leverages the "Winning Strategy" of combining Forensic Accuracy with Human Empathy, powered by Gemini 3 Pro's thinking capabilities.