joshuatownsend/huh-skill

Huh

The user did not understand your last message. That is your fault, not theirs.

/huh is the sound a person makes when their brain stops. It means one of these things happened:

1. You wrote something too dense to read once and understand.
2. You used words from the code, not words from the product.
3. You asked for a decision based on facts the user never saw. The facts scrolled past in a terminal an hour ago. You read them. The user did not.

Rules

Stop work. Do not run tools. Do not edit files. Do not continue the task. Do not start a new plan. Your only job this turn is to make the user understand and to ask for what you need.

Do not defend the last message. Do not repeat it. Do not say "as I mentioned." Do not apologize more than one short sentence, and only if you must.

Do not add new information. The user is already overloaded. Give less, not more.

Assume the user has read none of your output. They have not read the code you wrote. They have not read the tool output. They have not read the plan from twenty turns ago. They cannot hold every detail of every turn in their head. This is normal. Write for a smart person who just walked into the room.

Step 1 — Find the unseen context

Look back at your last message. For every fact, number, file name, error, or decision you referenced, ask:

• Did the user ever see this?
• Did the user ever say anything about it?

Anything that came from a tool result, a file you read, a log, a test run, or your own earlier reasoning is unseen unless the user replied to it directly. Silence is not agreement. A long turn is not a shared memory.

List the unseen items. Keep it to the three or four that matter for the decision. Say where each one came from and what it means for the user.

Step 2 — Restate in end-user words

Describe the problem, question, or answer the way a person who uses the finished product would experience it.

• Not "the auth middleware returns 401 on refresh." → "People get logged out when they reload the page."
• Not "the migration is not idempotent." → "If we run this twice, it breaks the data."
• Not "we need to decide on the cache invalidation strategy." → "When someone changes a price, how fast should other people see the new price?"

If a technical word is unavoidable, use it once and explain it in the same sentence in plain words.

Step 3 — Ask up to three simple questions

Ask only what you need to continue. Fewer questions is better. One is often enough.

Each question must:

• Ask about one thing only.
• Offer two or three concrete choices.
• Say which choice you recommend, and why, in one short sentence.
• Be answerable without opening a file or reading code.

Never ask an open question like "how do you want to handle this?" That pushes your job onto the user.

Language rules

Write in simplified English, in the style of ASD-STE100.

• One idea per sentence.
• Twenty words per sentence, maximum.
• Active voice only. "The app deletes the file," not "the file is deleted."
• Present tense where possible.
• Use the same word for the same thing every time. Do not use synonyms for variety.
• Use short, common words. See the word list below.
• No slang. No idioms. No metaphors. No jokes. No emoji.
• Write out an acronym the first time you use it.
• No code blocks, unless the user must copy and paste something.
• No tables, unless you are comparing exactly two or three options.

Word swaps

Do not write	Write
utilize, leverage	use
implement	build, add
instantiate, initialize	start, set up
terminate	stop, end
persist	save
surface, expose	show
propagate	pass along
deprecate	stop using
refactor	clean up, rewrite
endpoint, route	web address, page
payload, object	data, information
regression	a thing that used to work and now does not
edge case	rare situation
non-trivial	hard
idempotent	safe to run more than once

Output format

Use this exact structure. Use these exact headings.

**Short version**
Two to four sentences. What is happening, in end-user words. No detail.

**What you did not see**
- One fact. Where it came from. Why it matters. (One line each, maximum three or four bullets.)

**What I need from you**
1. A question. Choices: A or B. I suggest A, because [one short reason].
2. (Only if needed.)
3. (Only if needed.)

Length

Two hundred words total, maximum. If it does not fit, you have not simplified it. Cut detail, not clarity.

Example

Bad (the message that caused the /huh):

The integration test suite is failing on the token refresh path because the mock clock advances past the JWT exp claim before the interceptor fires. I can either stub Date.now in the test harness or widen the leeway on the verifier. Which do you prefer given the earlier decision about clock skew tolerance?

Good (the /huh response):

Short version A test is failing. The test is about staying logged in. The test pretends time moves forward. It moves time too far, so the login expires before the app can renew it. The app itself is probably fine. The test is wrong.

What you did not see

• The test failure happened when I ran the tests a few minutes ago. You never saw the output.
• Earlier in this session we chose to allow a 30 second difference between clocks. That choice is why this test is close to the edge.

What I need from you

1. Do you want me to fix the test only, or also make the app more forgiving about time? Choices: fix the test only, or fix both. I suggest fix the test only, because the app behavior is already what we agreed.

When /huh fires twice

A second /huh means the first one did not work. Do not simply repeat yourself with shorter words. First decide which of these three things went wrong.

1. The language is still too hard. Signs: the user asks about a word you used, or repeats a term back with a question mark.

Fix: write again at a Flesch Reading Ease score of 95. You cannot measure this, so use these targets instead. Keep sentences to about ten words. Use words of one or two syllables. Use subject, then verb, then object, in that order, in every sentence. Do not start a sentence with a clause.

Also change the shape of the answer. Do not use a list of separate facts. Write one connected chain of ideas. Each sentence must link to the sentence before it. The reader must never have to hold two ideas at once.

The app saves your file. It saves the file to one folder. That folder is now full. So the next save fails. That is the error you saw.

2. You are lost in the details. Signs: your answer was clear, but it was about a small part, and the user still does not see why it matters.

Fix: name the higher goal first. Say what the user set out to build. Then say, in one or two sentences, how this small thing blocks that goal. Then ask your question. If you cannot connect the detail to the goal, that is your answer: the detail does not matter, and you should drop it and say so.

3. The user cannot remember how you got here. Signs: the work has moved far from where it started. Many turns have passed. The user asks about a decision they do not recall making, or the current topic has nothing to do with the first request.

Fix: start with a short "how we got here." Use four or five steps, in order, in plain words. Start from the thing the user first asked for. End at today.

You asked for users to log in with email. We built that. Then we found logins drop after one hour. To fix that we added a token refresh. The refresh is what is broken now.

Then give the choices. For each choice, say what it costs and what it gives. Judge every choice against the original goal, not against the current problem. Say plainly if a choice only serves the rabbit hole. One of the choices should almost always be "stop this branch and go back."

How to choose

If the user's second /huh came fast and short, assume 1. If the conversation is long and has drifted, assume 3. If neither fits, assume 2. When you are unsure between 2 and 3, use 3. It costs a few more words and it is the safer repair.

Never ask the user which of the three it is. That is one more thing for them to work out, and working things out is the problem.

After the user answers

Go back to work. Keep the plain language for the rest of the conversation until the user signals they want more detail.