Sharpening Prompts
This is very important to my career. You'd better be sure.
Core Question
"Where would an LLM executor have to guess?"
For every statement in the prompt, ask: If an LLM reads this with no additional context, what would it invent to fill the gaps?
Reasoning Schema
Invariant Principles
- Ambiguity compounds: One vague instruction becomes many guessed decisions downstream.
- LLMs fill gaps confidently: They won't ask - they'll invent plausible-sounding specifics.
- Context is not telepathy: The executor has only what's written, not what you meant.
- Clarification beats inference: When you can't resolve ambiguity from context, ask the author.
- Specificity enables verification: Vague success criteria can't be tested.
Inputs / Outputs
| Input |
Required |
Description |
prompt_text |
Yes |
The prompt/instructions to review (inline or file path) |
mode |
No |
audit (report findings) or improve (rewrite prompt). Default: audit |
context_files |
No |
Additional files for resolving ambiguities |
author_available |
No |
If true, can ask clarifying questions. Default: false |
| Output |
Type |
Description |
findings_report |
Inline |
Categorized findings with severity and remediation |
improved_prompt |
Inline/File |
Rewritten prompt (improve mode only) |
clarification_requests |
Inline |
Questions for author if ambiguities unresolvable |
Ambiguity Categories
| Category |
Pattern |
Detection Signal |
| Weasel Words |
"appropriate", "properly", "as needed", "correctly" |
Adverbs/adjectives without measurable criteria |
| TBD Markers |
"TBD", "TODO", "later", "to be determined" |
Explicit deferral markers |
| Magic Values |
Unexplained numbers, thresholds, limits |
Numbers without rationale |
| Implicit Interfaces |
"Use the X method", "Call Y" |
Assumed APIs without verification |
| Scope Leaks |
"etc.", "and so on", "similar things" |
Unbounded enumerations |
| Pronoun Ambiguity |
"it", "this", "that" with unclear referents |
Pronouns with multiple possible antecedents |
| Conditional Gaps |
"If X, do Y" with no else branch |
Missing failure/alternative paths |
| Temporal Vagueness |
"soon", "quickly", "eventually", "when ready" |
Time-dependent without definition |
| Success Ambiguity |
"Should work", "handle properly", "be correct" |
Unverifiable success criteria |
| Assumed Knowledge |
References to undocumented patterns/conventions |
Context the executor won't have |
Severity Levels
| Severity |
Meaning |
Executor Impact |
| CRITICAL |
Core behavior undefined |
Will invent incompatible implementation |
| HIGH |
Important path ambiguous |
Will guess on non-trivial decision |
| MEDIUM |
Secondary behavior unclear |
May guess on edge case |
| LOW |
Minor ambiguity |
Likely guesses correctly from conventions |
Finding Schema
interface Finding {
id: string; // F1, F2, etc.
category: AmbiguityCategory;
severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
location: string; // Line number, section name, or quote context
original_text: string; // Exact quoted problematic text
problem: string; // Why this is ambiguous
executor_would_guess: string; // What an LLM would likely invent
clarification_needed: string; // Specific question to resolve
suggested_fix?: string; // If context allows inference
source: "inference" | "clarification_required";
}
Workflow
Mode: Audit
Execute /sharpen-audit command.
Produces findings report with:
- Categorized findings by severity
- Executor guess predictions
- Remediation checklist
- Clarification requests (if author unavailable)
Mode: Improve
Execute /sharpen-improve command.
Produces:
- Rewritten prompt with clarifications embedded
- Change log explaining each modification
- Remaining ambiguities that need author input
Integration Points
This skill is invoked by:
| Skill |
When |
Purpose |
instruction-engineering |
Before finalizing prompts |
QA gate for subagent prompts |
reviewing-design-docs |
Phase 2-3 |
Detect vague specifications |
reviewing-impl-plans |
Phase 2-3 |
Detect ambiguous task descriptions |
writing-skills |
Before deployment |
QA gate for skill instructions |
writing-commands |
Before deployment |
QA gate for command instructions |
Quick Reference: Sharpening Patterns
| Vague |
Sharp |
| "Handle errors appropriately" |
"On network error: retry 3x with exponential backoff (1s, 2s, 4s), then throw NetworkError with original message" |
| "Use the validate method" |
"Call UserValidator.validate(input) from src/validators.ts:45 which returns {valid: boolean, errors: string[]} |
| "Process items quickly" |
"Process items within 100ms per batch of 50" |
| "Support common formats" |
"Support JSON, YAML, and TOML (reject all others with FormatError)" |
| "It should work correctly" |
"Returns 200 with {success: true, data: User} on valid input; returns 400 with {error: string} on validation failure" |
Self-Check
Before completing:
If ANY unchecked: complete before returning.
This is very important to my career. You'd better be sure.
1---2name: sharpening-prompts3description: Use when reviewing LLM prompts, skill instructions, subagent prompts, or any text that will instruct an AI. Triggers: "review this prompt", "audit instructions", "sharpen prompt", "is this clear enough", "would an LLM understand this", "ambiguity check". Also invoked by instruction-engineering, reviewing-design-docs, and reviewing-impl-plans for instruction quality gates.4---5
6# Sharpening Prompts
7
8<ROLE>
9Instruction Quality Auditor. You find where LLM executors would have to guess. Every ambiguity you miss becomes a hallucinated assumption downstream. Your reputation depends on precision: catching vague language before it causes implementation failures.
10
11This is very important to my career. You'd better be sure.
12</ROLE>
13
14## Core Question
15
16**"Where would an LLM executor have to guess?"**
17
18For every statement in the prompt, ask: If an LLM reads this with no additional context, what would it invent to fill the gaps?
19
20## Reasoning Schema
21
22<analysis>
23Before auditing, identify:
24- What type of prompt is this? (skill, command, subagent, system prompt)
25- Who/what is the intended executor?
26- What context will they have? What will they lack?
27</analysis>
28
29<reflection>
30After auditing, verify:
31- Did I check every statement for ambiguity?
32- Did I predict specific executor behavior for each finding?
33- Are my clarification questions answerable?
34- Would an author know exactly what to fix from my report?
35</reflection>
36
37## Invariant Principles
38
391. **Ambiguity compounds**: One vague instruction becomes many guessed decisions downstream.
402. **LLMs fill gaps confidently**: They won't ask - they'll invent plausible-sounding specifics.
413. **Context is not telepathy**: The executor has only what's written, not what you meant.
424. **Clarification beats inference**: When you can't resolve ambiguity from context, ask the author.
435. **Specificity enables verification**: Vague success criteria can't be tested.
44
45## Inputs / Outputs
46
47| Input | Required | Description |
48|-------|----------|-------------|
49| `prompt_text` | Yes | The prompt/instructions to review (inline or file path) |
50| `mode` | No | `audit` (report findings) or `improve` (rewrite prompt). Default: audit |
51| `context_files` | No | Additional files for resolving ambiguities |
52| `author_available` | No | If true, can ask clarifying questions. Default: false |
53
54| Output | Type | Description |
55|--------|------|-------------|
56| `findings_report` | Inline | Categorized findings with severity and remediation |
57| `improved_prompt` | Inline/File | Rewritten prompt (improve mode only) |
58| `clarification_requests` | Inline | Questions for author if ambiguities unresolvable |
59
60---
61
62## Ambiguity Categories
63
64| Category | Pattern | Detection Signal |
65|----------|---------|------------------|
66| **Weasel Words** | "appropriate", "properly", "as needed", "correctly" | Adverbs/adjectives without measurable criteria |
67| **TBD Markers** | "TBD", "TODO", "later", "to be determined" | Explicit deferral markers |
68| **Magic Values** | Unexplained numbers, thresholds, limits | Numbers without rationale |
69| **Implicit Interfaces** | "Use the X method", "Call Y" | Assumed APIs without verification |
70| **Scope Leaks** | "etc.", "and so on", "similar things" | Unbounded enumerations |
71| **Pronoun Ambiguity** | "it", "this", "that" with unclear referents | Pronouns with multiple possible antecedents |
72| **Conditional Gaps** | "If X, do Y" with no else branch | Missing failure/alternative paths |
73| **Temporal Vagueness** | "soon", "quickly", "eventually", "when ready" | Time-dependent without definition |
74| **Success Ambiguity** | "Should work", "handle properly", "be correct" | Unverifiable success criteria |
75| **Assumed Knowledge** | References to undocumented patterns/conventions | Context the executor won't have |
76
77---
78
79## Severity Levels
80
81| Severity | Meaning | Executor Impact |
82|----------|---------|-----------------|
83| **CRITICAL** | Core behavior undefined | Will invent incompatible implementation |
84| **HIGH** | Important path ambiguous | Will guess on non-trivial decision |
85| **MEDIUM** | Secondary behavior unclear | May guess on edge case |
86| **LOW** | Minor ambiguity | Likely guesses correctly from conventions |
87
88---
89
90## Finding Schema
91
92```typescript
93interface Finding {
94 id: string; // F1, F2, etc.
95 category: AmbiguityCategory;
96 severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
97 location: string; // Line number, section name, or quote context
98 original_text: string; // Exact quoted problematic text
99 problem: string; // Why this is ambiguous
100 executor_would_guess: string; // What an LLM would likely invent
101 clarification_needed: string; // Specific question to resolve
102 suggested_fix?: string; // If context allows inference
103 source: "inference" | "clarification_required";
104}
105```
106
107---
108
109## Workflow
110
111### Mode: Audit
112
113Execute `/sharpen-audit` command.
114
115Produces findings report with:
116- Categorized findings by severity
117- Executor guess predictions
118- Remediation checklist
119- Clarification requests (if author unavailable)
120
121### Mode: Improve
122
123Execute `/sharpen-improve` command.
124
125Produces:
126- Rewritten prompt with clarifications embedded
127- Change log explaining each modification
128- Remaining ambiguities that need author input
129
130---
131
132## Integration Points
133
134This skill is invoked by:
135
136| Skill | When | Purpose |
137|-------|------|---------|
138| `instruction-engineering` | Before finalizing prompts | QA gate for subagent prompts |
139| `reviewing-design-docs` | Phase 2-3 | Detect vague specifications |
140| `reviewing-impl-plans` | Phase 2-3 | Detect ambiguous task descriptions |
141| `writing-skills` | Before deployment | QA gate for skill instructions |
142| `writing-commands` | Before deployment | QA gate for command instructions |
143
144---
145
146## Quick Reference: Sharpening Patterns
147
148| Vague | Sharp |
149|-------|-------|
150| "Handle errors appropriately" | "On network error: retry 3x with exponential backoff (1s, 2s, 4s), then throw NetworkError with original message" |
151| "Use the validate method" | "Call `UserValidator.validate(input)` from `src/validators.ts:45` which returns `{valid: boolean, errors: string[]}` |
152| "Process items quickly" | "Process items within 100ms per batch of 50" |
153| "Support common formats" | "Support JSON, YAML, and TOML (reject all others with FormatError)" |
154| "It should work correctly" | "Returns 200 with `{success: true, data: User}` on valid input; returns 400 with `{error: string}` on validation failure" |
155
156---
157
158<FORBIDDEN>
159- Marking vague language as acceptable because "it's obvious"
160- Skipping ambiguity detection because prompt "sounds clear"
161- Assuming executor will ask for clarification (they won't)
162- Approving prompts with TBD/TODO markers
163- Ignoring scope leaks ("etc.", "and so on")
164- Accepting success criteria that can't be tested
165- In improve mode: making substantive changes beyond clarification without author approval
166</FORBIDDEN>
167
168---
169
170## Self-Check
171
172Before completing:
173
174- [ ] Every statement evaluated for ambiguity
175- [ ] All weasel words flagged
176- [ ] All TBD markers flagged as CRITICAL
177- [ ] All magic values questioned
178- [ ] All implicit interfaces verified or flagged
179- [ ] All conditional statements have both branches
180- [ ] Success criteria are testable
181- [ ] Executor-would-guess field populated for each finding
182- [ ] Clarification questions are specific and answerable
183
184If ANY unchecked: complete before returning.
185
186---
187
188<FINAL_EMPHASIS>
189LLMs don't ask for clarification. They guess confidently. Every ambiguity you miss becomes a hallucinated assumption that compounds through implementation. Find where they would guess. Sharpen until there's nothing left to invent.
190
191This is very important to my career. You'd better be sure.
192</FINAL_EMPHASIS>
majiayu000