Talk like a Pro

Vague coding request in, precise task prompt out.

模糊需求进，精确 prompt 出。不打扰，不阻塞，必要时才追问。

Talk like a Pro is a Pi extension that turns vague coding requests into precise, verifiable task prompts. It detects ambiguous input, gathers lightweight repository context, and asks focused clarifying questions only when they would change the outcome—so clear requests pass through untouched and your workflow is never blocked.

Quick start

Install the extension:

pi install git:github.com/TimYuann/Talk-like-a-pro

Restart Pi, or run /reload, then enable automatic translation:

/talk-like-a-pro on

Now type a vague request normally:

帮我优化一下登录体验，让它更专业一点

The extension shows its progress, asks only questions that materially affect implementation, and replaces the vague input with the refined task. Automatic translation is off by default; /!! can force a one-off translation without enabling it globally.

How it works

1. Heuristic filter — catches short requests and vague Chinese or English verbs; conversation-control messages such as 好的，开始吧 pass through.
2. Context probe — collects the working directory, git status, a bounded tracked-file sample, AGENTS.md / CLAUDE.md, and recent conversation text.
3. Intent analysis — calls the selected analyzer model through Pi's model registry with a 60-second total budget, including retries.
4. Clarification — validates and shows 1–3 focused questions when critical choices are missing.
5. Re-synthesis — combines the answers into a final prompt and refuses to inject it if critical ambiguity remains.
6. Transform — replaces the original input while preserving attached images.

LLM failures, invalid analyzer output, timeouts, and user cancellation all fall back to the original input. Mid-stream steering skips translation so corrections reach the active agent immediately.

Controls

Input	Behavior
/!! <request>	Force translation, bypassing both the heuristic and master switch
/! <request>	Force pass-through and always strip the prefix
Plain input	Use the heuristic when automatic translation is enabled

Examples:

/!! improve auth
/! keep this exact wording
/talk-like-a-pro status

Settings

Run /talk-like-a-pro in TUI mode for the settings screen, or use commands in any mode:

/talk-like-a-pro on|off|status
/talk-like-a-pro level 1|2
/talk-like-a-pro model follow-current|<provider/id>
/talk-like-a-pro effort <off|minimal|low|medium|high|xhigh|max>

Setting	Values	Default	Effect
Enable	on / off	off	Master switch; /!! still works while off
Level	1 Beginner / 2 Standard	2	Controls the shape and detail of the refined prompt
Analyzer model	follow-current / authenticated model	follow-current	Model used for intent analysis
Effort	model-supported levels	minimal	Reasoning effort for analyzer calls

Configuration persists to ~/.pi/agent/extensions/talk-like-a-pro.json. Invalid saved values are replaced with safe defaults. When enabled, the footer shows ● TLAP Lx.

Output levels

• 1 Beginner — a complete task specification: intent, implied needs, at least four requirements including boundaries, evidence-backed context, and at least three acceptance criteria. Maximum target length: 1,400 Chinese characters.
• 2 Standard — a compact fill-in prompt: intent, two or three requirements, evidence-backed context, and two acceptance criteria. Maximum target length: 800 Chinese characters.

Analyzer model and privacy

The picker shows session-scoped models, or authenticated registry models when no scope is configured. Provider-qualified model IDs are matched exactly; if a saved model is unavailable in a later session, the current session model is used.

The context probe and recent conversation excerpts are sent to the selected analyzer provider. Choose a provider you trust. The analyzer receives fixed policy as a system prompt and repository/user content as serialized untrusted data; it is also instructed not to copy credentials or unrelated conversation details into the refined prompt.

Development

During development, symlink the source into Pi's extension directory:

ls -la ~/.pi/agent/extensions/translator.ts
# -> <this-repo>/extensions/translator.ts

Edit extensions/translator.ts, run the syntax smoke test, then /reload in Pi:

bun build --target=node --external '@earendil-works/*' \
  extensions/translator.ts --outfile=/tmp/check.js

Known limits

• ctx.ui.select does not render option descriptions, so option labels must be self-contained.
• Clarification is limited to one question batch and one re-synthesis call; unresolved ambiguity falls back to the original request.
• Large analyzer models can still feel slow, although each analysis cycle—including retries—has a 60-second total timeout.
• The graphical settings screen requires TUI mode; command arguments work in non-TUI modes.
• Context exploration is intentionally bounded and does not read arbitrary source-file contents.

Tuning

All behavior lives in extensions/translator.ts:

• shouldConsiderFuzzy() — Chinese/English heuristic and control-message bypass
• exploreContext() — bounded, parallel context probes
• buildAnalyzerPrompt() — system policy plus JSON-serialized request data; level behavior lives in LEVEL_PROMPT_BLOCKS
• parseAnalysis() / parseQuestions() — strict analyzer-output validation
• callAnalyzer() / safeAnalyze() — model-registry call, timeout, empty-output retry, JSON-repair retry, and pass-through fallback
• resolveAnalyzerModel() / supportedEfforts() — exact model resolution and per-model effort filtering

Changes to the analyzer prompt or parser should be reflected in both Known limits and Tuning.

License

Released under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and sell copies, provided the copyright and license notice are retained. The software is provided without warranty.

Copyright © 2026 TimYuann.