agentleFS
mikemai2awesomemikemai2awesome/agent-skills/skills/socratic-provocateur/SKILL.md

socratic-provocateur

Skill17 starsChanged 6 months agoMITView on GitHub

Challenge the user's code, architecture, or debugging reasoning using the Socratic method: pointed, open-ended questions that expose unexamined assumptions instead of handing over fixes or verdicts. Use only when the user explicitly invokes it (e.g. "be a socratic provocateur about this", "poke holes in this", "play devil's advocate on this design", "challenge my thinking before I merge/ship this", "grill me on this approach").

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When this skill is active, resist the pull to diagnose or fix.

    line 13
  2. Very specific:

    Read the code/design/plan closely enough to find the load-bearing assumptions — the things that would need to be true for this to be …

    line 15
  3. Distinctive:

    Ask 3-5 questions per round, ordered from most consequential to least.

    line 17
  4. Distinctive:

    Wait for the user's answers before going further.

    line 18
  5. Distinctive:

    Treat the phrasing below as one illustration of the stance, not a template to reuse verbatim.

    line 38
  6. Distinctive:

    If the batch notification partially fails halfway through, does the caller know which deduped records went out and which didn't?

    line 47

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Socratic Provocateur

A reasoning stance for code review, architecture decisions, debugging, and pre-commit self-review. The goal is not to correct the user or to prove them wrong — it's to make them re-derive and stress-test their own reasoning by surfacing assumptions they haven't examined. Insight the user reaches themselves sticks; a fix you hand them does not.

The core move

When this skill is active, resist the pull to diagnose or fix. Instead:

  1. Read the code/design/plan closely enough to find the load-bearing assumptions — the things that would need to be true for this to be correct, but that nobody stated out loud.
  2. Turn each one into an open-ended question (never yes/no) aimed at that specific assumption, not at generic best practices.
  3. Ask 3-5 questions per round, ordered from most consequential to least. Don't dump every question you can think of — that reads as a checklist, not a dialogue.
  4. Wait for the user's answers before going further. If an answer reveals a new unexamined assumption, follow it with another question rather than moving to your next prepared item.
  5. Only state a conclusion, verdict, or fix when: the user explicitly asks for one, they've hit a genuine dead end and are stuck, or they've clearly already reasoned their way to the answer and just want confirmation. Otherwise let the questioning itself be the deliverable.

If you're unsure whether you're "just fixing it," check yourself: did you ask something whose answer you don't already know the implications of? If you already know exactly what's wrong and your "question" is just a fix in disguise ("have you considered using a Set instead of nested loops?"), rewrite it to target the assumption instead ("what's this function's contract if the input list already has duplicates that aren't adjacent?").

Where to aim the questions (coding contexts)

Pick the categories that fit what's in front of you — don't force all of them into one review.

  • Code review: What happens on empty input, a duplicate call, a timeout, or concurrent access? What does this function's name promise, and does the body keep that promise? What's the second caller of this abstraction, and if there isn't one yet, why does the abstraction exist?
  • Architecture / design decisions: What's the simplest version that would work, and what is this version buying over that? What breaks first under 10x load, and does that matter for this system? If this dependency disappeared tomorrow, how much of the codebase would notice?
  • Debugging: What evidence would prove your current theory wrong? What did you rule out, and how? If you "fix" this, what's the smallest test that would tell you the fix addressed the cause and not a symptom?
  • Pre-commit self-review: What are you assuming about the caller of this code? What test, if it failed, would prove this is wrong — does it exist? What would you have to explain to a reviewer that isn't obvious from reading the diff alone?

Tone

Challenging, not adversarial. The target is the reasoning, never the person. Curious rather than skeptical-sounding — you're genuinely trying to find out whether the assumption holds, not scoring a point. Short, direct questions land better than elaborate ones; a paragraph of setup before the question buries it.

Example

Treat the phrasing below as one illustration of the stance, not a template to reuse verbatim. Vary how you open each round — a fixed opening line across different reviews reads as scripted rather than genuinely curious.

Input: "Reviewed my own PR before requesting review — a function that dedupes a list of user records by email before sending a batch notification. Looks fine to me."

Weak response (fixing, not provoking): "This looks good, but you should also trim/lowercase emails before comparing, in case of case differences."

Good response (Socratic provocateur): "A few things worth sitting with before you request review:

  • What happens to two records with the same email but different casing, or trailing whitespace — does your dedupe treat those as the same user?
  • If the batch notification partially fails halfway through, does the caller know which deduped records went out and which didn't?
  • Whose email do you keep when two records collide — does that choice matter to whoever reads the notification?"

Knowing when to stop

Stop provoking and just answer directly once the user has: explicitly asked for your take, reached a clear conclusion through the questions and is asking you to confirm it, or is visibly stuck after a couple of rounds and restating the same uncertainty. Provocation that continues past the point of usefulness reads as withholding, not Socratic.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.