092 — PromptLint

Problem

AI prompt engineers, product builders integrating LLMs, and everyday ChatGPT/Claude users waste significant time iterating on poorly structured prompts. Common anti-patterns creep in unnoticed: vague instructions ("make it better"), missing output format specs, contradictory constraints ("be concise but cover everything in detail"), no few-shot examples, overreliance on a single model assumption, and missing system-role separation. These issues lead to inconsistent, verbose, or off-topic outputs that require multiple re-prompts.

Existing tools focus on prompt templates (prompt libraries, prompt marketplaces) or versioning (prompt management platforms), but none provide a real-time linting/quality checker that analyzes prompt text for structural weaknesses and suggests concrete improvements before you hit submit. Users need a fast, client-side tool that catches prompt anti-patterns the way a linter catches code smells.

Target Users:

• AI prompt engineers iterating on production prompts
• Developers integrating LLMs into apps (want clean prompts before API calls)
• Product managers prototyping AI features
• Power users of ChatGPT, Claude, Gemini who want better results faster

Core Features

P0 — Must-Have

1. Paste & Lint — Large textarea to paste/type a prompt. A deterministic rule engine runs instantly on each keystroke (no API call for core linting). Results panel shows categorized warnings/suggestions with line anchors.

2. Deterministic Rule Engine (~15 rules covering):

   • Clarity: Detect vague phrases ("make it good", "do something", "improve it") — flag with suggestion to specify measurable criteria
   • Output Format: Check if prompt specifies desired output format (JSON, markdown, numbered list, prose, etc.) — warn if missing
   • Contradictions: Flag pairs of conflicting directives ("be concise" + "be thorough", "short" + "comprehensive")
   • Role Prompting: Check if a system/persona/role is defined — suggest adding one for better control
   • Length: Warn on extremely short prompts (<20 chars) and very long prompts (>4000 chars) with context-appropriate advice
   • Examples: Detect absence of few-shot examples when prompt includes classification or transformation tasks
   • Negative Instructions: Flag excessive use of "don't" without positive alternatives
   • Numbered Steps: Detect sequential task prompts without numbered/ordered steps — suggest numbering
   • Ambiguity Markers: Flag hedge words ("maybe", "sort of", "kind of", "perhaps") that reduce prompt precision
   • Repetition: Detect repeated phrases or near-duplicate instructions
   • Delimiter Usage: Check for missing delimiters (triple quotes, XML tags, markdown blocks) when prompt contains reference text or examples
   • Temperature Hints: Flag when prompt content implies need for deterministic output but lacks a temperature guidance note
   • Whitespace/Formatting: Flag excessive blank lines, mixed indentation in structured prompts

3. Issue Panel — Sidebar listing all warnings grouped by category (Clarity, Structure, Format, Style). Click any issue to highlight the relevant text region in the editor. Each issue shows severity (info/warning/error) and a one-line fix suggestion.

4. Live Score — A composite quality score (0–100) displayed prominently, updating in real-time. Based on weighted rule pass/fail counts. Gives users a quick "is this prompt ready?" signal.

P1 — Nice-to-Have

1. AI-Powered Suggestions — Optional Gemini API call (user provides key or uses app default) that analyzes the prompt holistically and suggests 2–3 rewrite improvements. Clearly marked as AI-generated; deterministic linting works without it.

2. Prompt Templates — 10–15 starter templates (code review, summarization, classification, extraction, brainstorming, etc.) that users can load and customize. Templates pass lint checks by construction.

3. Export — Copy linted prompt to clipboard, or download as .txt / .md.

4. History — Last 20 lint sessions saved in localStorage with timestamp, score, and issue count. Click to reload.

Technical Approach

• Frontend-only for core linting: The deterministic rule engine runs entirely in the browser using regex and simple NLP heuristics (no API needed for the main value proposition).
• Optional Gemini enhancement: For AI-powered rewrite suggestions, call Gemini API client-side with the user's key or a shared app key (rate-limited).
• No database required for MVP: All state (history, config, rule toggles) lives in localStorage. If multi-user profiles are added later, add a simple Postgres-backed accounts table.
• No auth required for MVP: Fully functional without login. Optional auth only if history sync is added.

Suggested Stack

Feasibility Gut-Check

Out of Scope (defer these)

• Multi-user accounts and prompt sharing
• Prompt versioning / A/B testing
• Model-specific optimization tips (e.g., GPT-4 vs Claude-specific patterns)
• Prompt cost estimation (token counting with pricing)
• API endpoint to lint prompts programmatically

Architecture Design Spec

Status: ✅ Design Complete — Ready for implementation. Architecture document: designs/092-PromptLint-architecture.md C4 Container diagram: diagrams/promptlint-architecture.html Designed by: System Architect | Date: 2026-08-14