Clarify and Prompt: Turn Rough Ideas Into Self-Contained Agent Task Briefs
When assigning tasks to a coding agent, giving a single vague sentence and expecting the agent to guess the rest usually backfires. The agent invents unspoken assumptions, touches unrelated files, or generates hundreds of lines of useless code before getting stuck. On the other hand, an agent that asks a dozen open-ended questions causes decision fatigue.
I built clarify-and-prompt (MIT, v1.1.0) in the the-skills repository to solve this problem. It acts as an upstream clarification gate before any code is written: it routes the request through structured reasoning frameworks, bounds inquiry to 3 to 5 questions with recommended defaults, and outputs a self-contained task brief.
The generated prompt serves as the first and only instruction for the downstream agent. The receiving agent does not need conversation history, encounters no vague pronouns, and sees hard technical boundaries right away.
1. The 5 Thinking Frameworks & Method Router
When a request arrives, the skill inspects local workspace files first (package.json, target modules, system configs) so it never asks for facts already on disk. It then routes the request based on where the prompt needs clarity:
| Symptom in User Request | Applied Framework | Target Resolution |
|---|---|---|
| Prescribes an implementation before defining the problem ("Build a cron script") | First Principles & 5 Whys | Find the root cause and drop unneeded assumptions |
| Product feature with unclear value or trigger ("Add an export button") | Jobs-to-be-Done (JTBD) | Lock down: When [situation] -> I want [action] -> So I can [outcome] |
| Tangled, multi-layer technical requirements | SCQA + MECE | Frame Situation, Complication, Question, and split into non-overlapping branches |
| Uses subjective adjectives ("fast, clean, scalable, lightweight") | Socratic Quantification | Translate vague words into testable latencies, throughput SLAs, or byte budgets |
| Risk of hallucination or breaking existing code | Pre-mortem Inversion | Ask "What makes this run a failure?" to set strict Non-Goals |
Each inquiry combines these frameworks across 4 slots:
- Slot 1: Root objective and trigger event (First Principles / JTBD / SCQA).
- Slot 2: Technical architecture and functional boundaries (MECE Bucket A).
- Slot 3: Edge cases and quantified SLAs (Socratic / MECE Bucket B).
- Slot 4: Guardrails and out-of-scope boundaries (Pre-mortem Inversion).
Every question includes a concrete default option: *(Recommended: Option A - reason)*. You can answer in seconds by typing 1A, 2A, 3B.
2. The 4-Phase Pipeline Architecture
The process from rough idea to self-contained task brief takes 4 steps:
- Phase 1: Context scan & method routing. Classify the task domain (Coding, Architecture, Research, or Writing). Read workspace files to extract existing stack conventions, then pick 1 to 2 frameworks alongside mandatory Socratic and Pre-mortem checks.
- Phase 2: Bounded clarification. Ask 3 to 5 targeted questions in a single turn. Only run a second round if critical blockers remain. Skipped questions default to the recommended option as explicit assumptions.
- Phase 3: Synthesis summary. Display a brief summary of Situation and Complication (SCQA), Core Objective (JTBD), Quantified Constraints, and Non-Goals for quick review.
- Phase 4: Prompt generation. Pick the domain template and generate the prompt in a fenced code block. The prompt starts directly with the Objective, skips chat references like "as discussed earlier", omits persona tags ("You are a senior engineer"), and formats requirements for immediate execution.
3. Design Guardrails & Real-World Walkthrough
Two key design rules in clarify-and-prompt:
- No hand-off tone: The receiving agent runs in a fresh session. Phrasing like "continuing from our earlier discussion" causes the agent to search for non-existent session logs or skip basic setup.
- Objective over persona: Telling an LLM "You are a world-class engineer" adds no useful technical signal. A concrete objective with strict acceptance criteria produces far better code.
Here is a verified turn-by-turn trace of the skill clarifying an outbound webhook feature for an order processing service.
Turn 1: Initial User Prompt
User: I want to add an outbound webhook to notify our partner whenever an order status changes. Help me clarify the requirements and write a detailed prompt for a coding agent.
Turn 2: Agent Routes Frameworks and Inquires
The agent reads local files, detects a FastAPI backend, and presents 4 bounded questions:
Agent: To generate an unambiguous prompt for your coding agent, please confirm these 4 technical decisions (you can answer briefly with
1A, 2A, 3B...):
- [JTBD & Socratic SLA] Delivery Mechanism & Retry Policy:
- A (Recommended - avoids blocking order writes): Dispatch asynchronously via a background queue with exponential backoff retries (up to 5 attempts) on network errors, HTTP 5xx, or 429.
- B: Send synchronously inside the order status update request.
- [MECE - Security] Payload Signing:
- A (Recommended standard): Sign payloads with HMAC-SHA256 in
X-Webhook-SignaturealongsideX-Webhook-Timestampto prevent replay attacks.- B: Send a static Bearer token in the request header.
- [First Principles - Scope] Target Configuration & Audit Ledger:
- A (For multi-partner scale): Store endpoints in a
webhook_endpointstable and record delivery attempts inwebhook_deliveries.- B (For single partner today): Configure partner URL and Secret via environment variables (.env), and only create
webhook_deliveriesfor audit records.- [Pre-mortem - Stack & Guardrails] Background Worker & Non-Goals:
- What is your current worker stack (e.g., FastAPI + arq/Redis), and are there modules the agent must NOT touch?
Turn 3: User Replies in Seconds
User: 1A, 2A, and 3B because we only integrate with one partner right now, but keep the
webhook_deliveriestable for auditing. Our stack is FastAPI + async SQLAlchemy 2.0 + PostgreSQL witharq(Redis). Do not touch the existing payment service.
Turn 4: Agent Synthesizes and Emits the Task Brief
The agent compiles the constraints and emits an actionable specification:
# Objective (JTBD)
In this FastAPI + Async SQLAlchemy 2.0 + PostgreSQL + arq codebase, when an Order status changes, asynchronously dispatch a cryptographically signed outbound webhook via arq and persist delivery records in PostgreSQL so the partner receives reliable updates without degrading order mutation latency.
# Context & Problem Framing (SCQA)
- Situation: The application runs on FastAPI, SQLAlchemy 2.0 Async, PostgreSQL, and an arq background worker over Redis.
- Complication: The partner requires real-time order updates with cryptographic verification and retry resilience during downtimes, while we require an audit trail of every attempt.
- Architecture Scope: Because we integrate with a single partner, load WEBHOOK_TARGET_URL and WEBHOOK_SECRET from environment settings (Pydantic BaseSettings). Do not build an endpoint management table.
# Requirements & Quantified Constraints (MECE + Socratic)
## 1. Database Schema (webhook_deliveries)
Create an Async SQLAlchemy model and Alembic migration for webhook_deliveries:
- id: UUID (Primary Key)
- event_id: UUID (Unique idempotency key for the event)
- order_id: Foreign key referencing orders
- event_type: String (e.g., order.status_changed)
- payload: JSONB (Serialized JSON payload)
- status: Enum (PENDING, SUCCESS, FAILED)
- attempt_count: Integer (default 0)
- last_response_code: Integer, nullable
- last_error: Text, nullable
- next_retry_at: Timestamp with timezone, nullable
- created_at, updated_at: Timestamp with timezone
## 2. Payload Security (HMAC-SHA256)
- Required HTTP Headers:
- Content-Type: application/json
- X-Webhook-Id: <event_id>
- X-Webhook-Timestamp: <unix_epoch_seconds>
- X-Webhook-Signature: sha256=<hex_digest> computed via HMAC-SHA256(secret, f"{timestamp}.{raw_json_body}")
## 3. Worker SLA & Retry Flow (arq)
- Once the order mutation commits to PostgreSQL:
1. Insert a webhook_deliveries record with status = PENDING.
2. Enqueue the task deliver_order_webhook(delivery_id) in arq.
- Inside the worker task:
- Dispatch HTTP POST via httpx.AsyncClient(timeout=10.0) to WEBHOOK_TARGET_URL.
- On HTTP 2xx: Mark status = SUCCESS, increment attempt_count, clear next_retry_at.
- On network timeout, HTTP 5xx, or 429:
- If attempt_count < 5: Schedule retry with exponential backoff (15s, 60s, 300s, 900s) and update next_retry_at.
- If attempt_count >= 5: Mark status = FAILED and halt retries.
- On HTTP 4xx (excluding 429): Mark status = FAILED immediately without retrying.
# Pre-mortem Guardrails & Non-Goals
- Do NOT build a multi-tenant webhook_endpoints table or management CRUD endpoints.
- Do NOT modify or refactor code in the services/payment directory.
- Do NOT make synchronous HTTP calls inside the order update request lifecycle.
- Never log WEBHOOK_SECRET in plaintext logs or database columns.
- Compute the HMAC signature using raw serialized UTF-8 bytes sent over the wire to prevent key-ordering mismatches.
# Acceptance Criteria
- [ ] X-Webhook-Signature matches HMAC-SHA256(secret, "{timestamp}.{raw_body}").
- [ ] HTTP 200 moves record status to SUCCESS with attempt_count = 1.
- [ ] HTTP 500 or timeout triggers up to 5 retries before moving to FAILED.
- [ ] HTTP 400 fails immediately with zero retries.
- [ ] All new and existing pytest test suites pass with zero regressions.
4. Installation & Quickstart
Method 1: Local Skill Directory
Clone the repository and copy the skill into your local agent environment:
# Clone the repository
git clone https://github.com/pxuanbach/the-skills.git
# Copy clarify-and-prompt into your agent skills directory
cp -r the-skills/skills/clarify-and-prompt ~/.gemini/skills/
# or for Claude Code:
# cp -r the-skills/skills/clarify-and-prompt ~/.claude/skills/
Method 2: Direct Execution in Agent Environments
With the skill installed in your agent runtime (such as Antigravity CLI, Claude Code, or Cursor), activate it with:
/clarify-and-prompt I want to implement Time-based One-Time Password (TOTP) two-factor authentication for our existing auth service.
Or trigger it in conversational sessions:
Please apply the clarify-and-prompt skill to clarify this requirement and create a coding prompt: "Integrate Stripe webhooks into our Next.js backend".
When the inquiry finishes, the agent outputs the self-contained prompt block ready for copy-pasting, or saves it directly to .temp/task-prompt.md.
I have been using this skill for my daily engineering workflows. Frankly speaking, I think it still has plenty of rough edges. There is plenty of room for improvement, so I will likely update this kit again in the future, haha.