ViryaZheng/promptly-prompt

README preview

# promptly-prompt

A Claude Code skill that forces AI to **understand before executing**.

> A good prompt solves the problem fast — not through decoration, but by aligning with the AI from the very first message and on every one after. One plugin, two sentences, and ~90% of prompt problems disappear. The two that matter: **clear** and **concise**.

## What It Does

A `UserPromptSubmit` hook that acts as a **clarity gate**: it intercepts unclear prompts — vague verbs with no success criterion ("make it better"), hedging, dangling references — and injects two disciplines, both at once:

1. **Restate to align** — Echo the request back in its own words and state its understanding, so you can catch a misread before any work happens. If the restatement surfaces a mismatch, AI raises it before acting.
2. **Diagnose, then reuse prior art** — Don't solve from memory. Diagnose the root cause of the problem, search for the domain's mature, established practices — frameworks, libraries, methodologies, prior art — and only then proceed. If nothing fits, say so and explain why.

Clear prompts pass through untouched — no matter how long. A detailed spec with file paths, error messages, and acceptance criteria is the *clearest* prompt there is; only unclear ones pay the alignment tax. Simple commands (`git status`, `read file.py`, `/commit`) also pass silently.

The injection follows the prompt's language: Chinese prompts get the Chinese protocol, English prompts the English one.

## Why

Most AI failures start with an unclear input — and nobody writes perfectly clear prompts when their brain is foggy. Instead of teaching you to prompt better, this hook catches the unclear prompt at submission and repairs it in place: the restatement forces one round of alignment, after which it is as if you had submitted a clear prompt all along. You don't have to get better; the collaboration does.

View full repository on GitHub →