English | 简体中文
Sharpen the axe before cutting wood — fool-proof requirement clarification for AI agents.
Ever told an AI "make me one of those… you know, the thing" and gotten back a confident wall of output that's nothing like what you meant?
The problem usually isn't that the model is dumb — it's that the requirement is mush. sharpen-first is a "requirement clarification" capability you install on an AI agent: when your goal is ambiguous, a big task has no success criteria, or you yourself say "I haven't really thought this through," the agent stops guessing and instead uses a fool-proof questioning method to sharpen the requirement with you — before it starts working.
You: make me one of those intro pages, something nice-looking
AI: (sharpen-first triggers) Question 1: what's this intro page for?
A. Product homepage (recommended — fits your recent project)
B. Personal résumé / portfolio
C. Event flyer landing page
You: whatever, your call
AI: (doesn't push back, adopts the recommendation and flags it as an assumption)
Got it — going with the product homepage, flagged as [Assumption].
Question 2: … (up to 5 questions, then wraps up)
📋 Consensus sheet
[Goal] … [Out of scope] … [Success criteria] …
[Key assumptions] Product homepage (you didn't confirm this — check here first if it's wrong)
[Open items] …
I'll start once you confirm.
| Mechanism | What it fixes |
|---|---|
| Max 5 questions, multiple-choice first, every question carries a recommendation | People who struggle to articulate can't answer open questions well, but they can pick from options |
| Answer "whatever / don't know" → adopt the recommendation + flag [Assumption], never press twice | Never grinds a user down |
| Small tasks take a "guess-and-confirm" shortcut, one line and move on | No five-question interrogation for trivial asks (over-sharpening is an explicit anti-pattern) |
| Idea not yet formed → upgrade from "asking" to "helping you think" (restate as 2-3 directions for the user to pick from) | When there's genuinely no answer in the user's head yet, pure questioning just draws blanks |
| Two wrap-up modes: a consensus sheet (start working directly) / a seven-section prompt (take it elsewhere to feed another AI, assumptions never evaporate) | Covers both downstream needs |
| Course-correction after work starts: any drift from the consensus sheet forces a stop-and-realign, with the cost of switching spelled out | Fixes "the big project drifts further off course the longer it runs" |
| Blind-spot probing (added in 1.2): before picking a question, ask yourself "what is he least sure about / what's the biggest omission / what hasn't he noticed" | The four core elements only ask "what do you want" — blind-spot probing asks "what haven't you seen" — otherwise the consensus sheet just inherits your blind spots as-is |
| Deep-grill mode (added in 1.2, opt-in): say "grill me / interrogate me" → the 5-question cap lifts, and it interrogates branch by branch down a decision tree until real consensus is reached | Fool-proofing protects people who struggle to articulate; deep-grill serves people who actively want to be interrogated — it only kicks in when you say so |
Option 1 · git clone (recommended, updatable)
git clone https://gitlab.com/LucioLiu/sharpen-first ~/.claude/skills/sharpen-first
Option 2 · Manual: copy this repo's SKILL.md to ~/.claude/skills/sharpen-first/SKILL.md. (Note: manual copies have no update channel — re-copy by hand when a new version ships.) Chinese-speaking users should copy SKILL.zh-CN.md instead and rename it to SKILL.md locally.
Other tools (Cursor / Codex / any LLM): SKILL.md is itself a complete, portable markdown guide — feed it to your tool as a rules document.
No commands to remember once installed — the agent judges three signals on its own (a goal with multiple readings / a big task with no standard / you saying you haven't thought it through) and triggers automatically. You can also just say "sharpen first" to force it, or say "grill me / interrogate me" to enter deep-grill mode (uncapped interrogation until real consensus).
Combines obra/superpowers's brainstorming (one question at a time / multiple-choice first / options carry trade-offs) with github/spec-kit's /speckit.clarify (coverage scanning / impact-ranked ordering / a 5-question cap) — both were built for writing code; sharpen-first is built for "any task that's unclear." Five extreme-scenario walkthroughs were run at design time, but the raw transcripts weren't published with the repo, so that alone can't be cited as proof current behavior has been tested; the stable evaluation cases are not published in this repo, and they stay not-run until an independent agent has actually run them. Version 1.2 absorbed the deep-grill interrogation playbook from the mattpocock/skills grilling family (branch-by-branch decision-tree questioning / facts-vs-decisions boundary / dependency-ordered question batching), and introduced the blind-spot probing engine.
Part of the capability-block architecture behind the Nuwa digital-employee framework, usable standalone — more blocks live in that repo (not in this folder).
- dont-reinvent — found out mid-clarification that the agent lacks a capability? Look for an existing wheel before building one.
- handoff-protocol — in a multi-agent team, the handoff discipline for delegating work once a consensus sheet is settled.
Current version 1.2.0 (see .claude-plugin/plugin.json). Updates are always published to this repo; git clone users run git pull in the installed directory to upgrade, manual-copy users should revisit this page and compare version numbers.
The unified structural test entry point and the standalone behavioral case bundle are not published in this repository yet — don't expect a tests or evals directory in what you installed. Passing structural tests would not be the same as the agent's behavior passing anyway: the two stable behavioral cases stay not-run until an independent subject + judge leave a receipt.
PolyForm Noncommercial 1.0.0 — free for personal and non-commercial use.
Both language editions are maintained in sync. If they ever diverge, the Chinese edition is authoritative — please open an issue if you spot one.