AGENT SKILL

clarify-the-real-problem

Dig out the actual goal behind a request before building anything. Use when a request is ambiguous, when the literal ask smells like an X-Y problem (they asked for a solution, not a problem), or when a wrong interpretation would waste significant work. Also use when the user says "still thinking about it", "what's the best way to do this?", or hands over a vague one-liner that implies hours of work.

License 许可
MIT
最近更新
2026-11-07
Stars
★ 16
Forks
2

01 前言 Front Matter

name
clarify-the-real-problem
description
Dig out the actual goal behind a request before building anything. Use when a request is ambiguous, when the literal ask smells like an X-Y problem (they asked for a solution, not a problem), or when a wrong interpretation would waste significant work. Also use when the user says "still thinking about it", "what's the best way to do this?", or hands over a vague one-liner that implies hours of work.

03 SKILL.md 正文

Clarify the Real Problem

What's requested and what's needed often differ. If the real problem behind "build me a CSV parser" is "I need to get data out of Excel," you may not need to write a parser at all.

What to Ask

  • What's the actual goal behind this request?
  • Does building exactly what was asked achieve that goal, or is there a shorter path?
  • Is this request describing a problem, or a solution already decided on? If it's a solution, why was that solution chosen? — e.g. "make the per-brand calibration scripts share code" can mean two different real problems: centralize the brand-agnostic statistics (summarize(), run_per_brand_calibration()) that six brand files had actually copy-pasted byte-for-byte, which had already caused a real bug (a hardcoded datasets/leica/... path left in 5 of 6 files' error messages) — or couple the per-brand evaluate_*.py/calibrate_profile_<brand>.py loaders themselves, which are deliberately kept uncoupled (copy the loader, don't import a sibling) so experiments don't tangle as they accumulate. Building the wrong one either recreates a bug that already happened once, or "fixes" duplication that wasn't the actual ask.
  • Is a one-line request actually hours of work? Reading it narrow reads as ignoring it — scope it broad, then confirm, rather than interpreting it small.
  • Principal-level angle: if doing exactly what's asked sets a pattern other teams will copy (a new endpoint shape, a shared schema, a naming convention), the real problem includes "what precedent does this set," not just what satisfies the requester.
  • Distinguished/Fellow angle: if the pattern is likely to harden into doctrine everyone in the company is expected to follow rather than something a few teams happen to copy, the real problem includes whether it deserves the scrutiny of a public write-up before it calcifies, because undoing company-wide doctrine costs years, not a sprint.
  • Executive angle (CTO/VP-Eng): if the "real problem" actually requires new headcount, a different skill set, or exposes the company to regulatory or customer-trust risk, that's a staffing and risk decision that belongs in front of whoever owns budget — not something to solve quietly inside the original request's scope.

Handling Ambiguity

  • If interpretations diverge and the outcomes differ significantly, present the branches. Don't silently pick one and proceed.
  • When asking back, one question at a time. A barrage of questions blocks progress just as much as guessing wrong.
  • If it's reversible, don't ask — do it and show the result. Only confirm upfront when it's irreversible.
  • If confused, don't hide it — name exactly what's confusing and say so.

State Assumptions Explicitly

Any blank filled in by guessing must be stated explicitly. "Proceeded assuming X" — one line now saves hours later.

04 同仓库更多 Skills

songjiun10-collab
songjiun10-collab/Hncs

widen-the-solution-space

Deliberately widen the set of candidate approaches before committing to one. Use before irreversible decisions (architecture, DB schema, data format, public API), when the first solution feels complicated or awkward, when the user is deciding rather than instructing ("what's the best way to do this?"), or when a previous attempt at the same problem failed. Skip for routine work with one obvious answer.

★ 16
songjiun10-collab
songjiun10-collab/Hncs

weigh-tradeoffs

Compare real alternatives explicitly and record why one was chosen. Use when picking between libraries, data structures, architectures, or storage options; when a decision is hard to reverse (schema, public API, data format, dependency); or when the user asks "which is better, A or B". Also use to decide how much deliberation a decision even deserves.

★ 16
songjiun10-collab
songjiun10-collab/Hncs

verify-before-claiming

Run the verification and read its output before saying anything is done, fixed, working, or passing. Use before any completion claim, before committing or opening a PR, before moving to the next task, and after a subagent or tool reports success. Triggers on the words "should work", "fixed", "done", "passing", "looks good" — and on the urge to celebrate.

★ 16
songjiun10-collab
songjiun10-collab/Hncs

verifiability-first

Turn the task into something verifiable and declare the success criterion before seeing results. Use when the request is vague about "done" ("make it work", "improve this"), when writing tests, when fixing a bug (write the failing reproduction first), or when comparing two approaches. Critical before any measurement or benchmark, where deciding the bar after seeing the numbers guarantees a "success".

★ 16
songjiun10-collab
songjiun10-collab/Hncs

threat-and-scale-check

Check trust boundaries, scale behavior, and layered safety. Use when handling user input, external API responses, files, or auth; when designing permissions, validation, or any safety mechanism; when data volume could grow; or when writing loops that touch I/O. Also use when reviewing whether a single safeguard is the only thing standing between a mistake and a disaster.

★ 16
songjiun10-collab
songjiun10-collab/Hncs

surgical-change

Keep every changed line traceable to the request. Use when editing existing code, especially code you didn't write; when tempted to clean up something you noticed while reading; when a diff is growing beyond the ask; or when deciding whether to delete code that looks dead.

★ 16