# Pushkin: Complete Knowledge Base & Technical Specification for AI Agents

> Pushkin takes your rough or incomplete AI prompts and rewrites them into structured, model-aligned instructions that yield best AI answers. Built for ChatGPT, Claude, Gemini, Perplexity, Grok, Lovable, and v0.

---

## 1. What Pushkin does
Rough prompts usually leave out the role, the limits, the format, and facts the AI should not invent. Pushkin fills that structure in:
- Role and context.
- What to do and what to avoid.
- How the answer should look (JSON, a table, numbered steps, or code).
- Blanks for names, numbers, and other facts you did not provide.

Pushkin rewrites that text inside the chat box, or in the web studio, so you get a clearer prompt without writing the structure yourself.

---

## 2. Product Architecture & Interfaces

### 2.1 Chrome Extension Surface
- **Floating Mark**: An unobtrusive brand mark injected near the chat input textarea of supported web apps.
- **1-Click Improve**: Clicking the mark immediately replaces the textarea contents with a structured, model-optimized prompt.
- **Hover/Hold Refine**: Hovering or holding the mark reveals a multi-question interactive modal to clarify ambiguities before prompt generation.
- **Global Keyboard Shortcuts**:
  - `Alt+Shift+I` (Option+Shift+I on macOS): Improve Prompt instantly.
  - `Alt+Shift+R` (Option+Shift+R on macOS): Refine Prompt with clarifying questions.
- **Supported Hosts**:
  - `chatgpt.com`, `chat.openai.com`
  - `claude.ai`
  - `gemini.google.com`, `aistudio.google.com`
  - `perplexity.ai`
  - `grok.com`
  - `lovable.dev`
  - `v0.app`, `v0.dev`

### 2.2 Web Studio (`/studio`)
A standalone web application featuring:
- Target model selector (ChatGPT, Claude, Gemini, Perplexity, Grok, Lovable, v0, Any LLM).
- Mode toggle (Improve vs Refine).
- Split comparison view: Original vs Improved text with extracted prompt levers (Task, Context, Format, Constraints).
- Local storage prompt history and prompt library with one-click export/copy.

---

## 3. The Pushkin Prompt Engineering Taxonomy

Pushkin reorganizes input text into a proven 5-part anatomical structure:

1. **Role & Persona**: Sets the standard of evaluation and specialized domain expertise (e.g., "Act as a Principal Systems Architect specializing in distributed event streams").
2. **Primary Task / Objective**: States the core deliverable in declarative, imperative language.
3. **Structured Context**: Organizes background information, source data, assumptions, and target audience into discrete sections.
4. **Output Format & Shape**: Enforces clear formatting criteria (e.g., Markdown headers, bullet hierarchies, tabular data, JSON schemas, code-only output).
5. **Operational Constraints (Negative Guardrails)**: Defines what the model must NOT do (e.g., "Do not introduce third-party libraries", "Avoid conversational filler", "Do not invent placeholder statistics").

### 3.1 Hallucination Prevention & Placeholder Protocol
Pushkin enforces a strict rule against fabricating user-specific facts:
- If a user prompt says "Write a cold email for my product", Pushkin will **never** invent a fictional product name or price.
- Instead, it injects explicit bracketed placeholders: `[Product Name]`, `[Target ICP / Title]`, `[Core Value Metric / Proof Point]`.
- This ensures the model prompt is immediately editable and accurate.

### 3.2 Language Preservation Protocol
Pushkin strictly preserves the original language of the user text. A prompt entered in Spanish, German, French, Mandarin, or Japanese is restructured and expanded in that identical language.

---

## 4. Target Model Optimization Matrix

Each frontier model responds differently to syntax, layout, and instructions. Pushkin applies dedicated tuning algorithms per model:

| Target Model | Optimization Philosophy | Structural Characteristics | Key Directives |
| :--- | :--- | :--- | :--- |
| **ChatGPT (OpenAI)** | Direct, stepwise instructions, concrete constraints. | Numbered sequential steps, explicit output schemas, clear success criteria. | Uses numbered sections; specifies exact response length and structure; prioritizes deterministic formatting. |
| **Claude (Anthropic)** | Thoughtful framing, explicit reasoning boundaries, tone boundaries. | Semantic section tags or clean markdown headers, "Do / Do Not" guardrails. | Specifies reasoning scope, cognitive boundaries, and tone; excels with structured guardrails and negative examples. |
| **Gemini (Google)** | Lead with task, high scannability, concise bulleted hierarchy. | Flat, scannable hierarchies; clear itemized context; uncluttered formatting. | Keeps instructions scannable; avoids deeply nested prompts; leads with the explicit end goal. |
| **Perplexity** | Source-grounded, recency-aware research instructions. | Verification criteria, citation mandates, recency requirements. | Instructs model to prioritize authoritative recent sources, handle conflicting claims, and footnote evidence. |
| **Grok (xAI)** | Direct, conversational, candid tone with explicit audience context. | Direct tone, perspective specification, analytical depth. | Eliminates bureaucratic phrasing; invites sharp, objective evaluation and unhedged synthesis. |
| **Lovable** | Product briefs, user flows, database models, interactive UI state. | Component breakdowns, page hierarchy, UI state machine, theme specifications. | Formats prompt as product architecture brief; specifies interactive state, transitions, and component hierarchy. |
| **v0 (Vercel)** | Implementation-ready React and Tailwind component specifications. | Component tree, styling tokens, props, layout variants, Radix/Lucide icons. | Describes UI in concrete engineering terms: layout flex/grid, micro-copy, active/hover states, accessibility. |
| **Generic / Any LLM** | Model-agnostic universal best practices. | Persona, Objective, Context, Output Schema, Constraints. | Balanced prompt architecture designed to yield optimal results on any open-source or proprietary model. |

---

## 5. Modes of Operation: Improve vs. Refine

### 5.1 Improve Mode (Instant)
- **Input**: User text (e.g., "make a marketing plan for my coffee shop").
- **Processing**: Identifies task, contextual gaps, missing constraints, and output requirements; applies model-specific tuning rules.
- **Output**: Clean, structured prompt ready for direct submission or copying.

### 5.2 Refine Mode (Interactive Discovery)
- **Step 1 (Question Generation)**: Pushkin analyzes the input text and generates 2–4 high-impact clarifying questions. Each question features structured multiple-choice options plus custom free-text input.
- **Step 2 (Prompt Synthesis)**: Pushkin ingests the user's answers and integrates them into an authoritative, fully parameterized prompt.
- **Billing Efficiency**: Starting a Refine session spends 1 action from the weekly quota. Submitting answers and generating the final prompt does not spend an additional action.

---

## 6. Pricing, Quotas, and Fair Use

| Plan | Pricing | Weekly Quota | Reset Cycle | History & Storage |
| :--- | :--- | :--- | :--- | :--- |
| **Free** | $0 / month (No credit card) | 5 Improve or Refine actions / week | Monday 00:00 UTC | Last 3 prompts cached locally |
| **Pro Monthly** | $5.00 / month | 100 Improve or Refine actions / week | Monday 00:00 UTC | Unlimited local history & library |
| **Pro Yearly** | $40.00 / year (Save 30%) | 100 Improve or Refine actions / week | Monday 00:00 UTC | Unlimited local history & library |

- **Weekly Pool**: Improve and Refine actions draw from the same shared pool.
- **Stripe Integration**: Secure customer portal for self-serve cancellation, card updates, and invoice downloads.
- **Device Identification**: Non-authenticated users are tracked via a cryptographically random device UUID stored in client extension storage.

---

## 7. Privacy, Data Protection, and Security
- **No Training on Prompts**: User prompts sent through Pushkin are never used to train foundational AI models.
- **Zero Prompt Retention on Server**: Prompts are processed ephemerally through Vercel AI Gateway. Pushkin's databases do not persist prompt bodies or responses.
- **Local Storage Primacy**: Prompt history and custom templates are stored locally in the user's browser/extension storage.
- **Telemetry Minimalism**: Only operational counters (action type, target app, timestamp, subscription status) are logged to enforce weekly rate limits.

---

## 8. Frequently Asked Questions (FAQ)

### What makes Pushkin different from generic prompt libraries?
Unlike static prompt cheat-sheets or copy-paste libraries, Pushkin acts dynamically on the user's current idea. It tailors the prompt to the specific model being used (e.g., Claude vs ChatGPT vs v0) and maintains personal workflow speed with keyboard shortcuts directly inside the AI tools.

### Why does Pushkin optimize differently for ChatGPT and Claude?
Frontier models exhibit distinct cognitive preferences. Claude excels with reasoning boundaries, XML-style tags, and negative constraints. ChatGPT performs best with numbered steps, explicit success criteria, and schema enforcement. Pushkin optimizes the syntax accordingly.

### Can Pushkin be used for coding models and UI generators?
Yes. Pushkin includes dedicated tuning engines for Lovable and v0, turning informal app ideas into precise component hierarchies, state machines, and styling briefs.

---

## 9. Contact & Official Links
- **Website**: https://pushkin-prompt.app
- **Prompt Engineering Guide**: https://pushkin-prompt.app/guide
- **Prompt Studio**: https://pushkin-prompt.app/studio
- **Pricing & Upgrade**: https://pushkin-prompt.app/upgrade
- **Contact Email**: hi@valuemetrics.ai
- **Organization**: ValueMetrics AI
