# os-ask-simple

Adopt this skill: https://proskills.md/skills/other/kharmanskyi-open-steps-skills-os-ask-simple

Page: https://proskills.md/skills/other/kharmanskyi-open-steps-skills-os-ask-simple
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/os-ask-simple/SKILL.md
size: 5435
upstream: https://github.com/kharmanskyi/open-steps/blob/main/skills/os-ask-simple/SKILL.md

````text
---
name: os-ask-simple
description: >-
  ALWAYS invoke this skill before asking the user any technical question or
  offering options, and whenever they ask to be asked in plain words - "ask
  simple", "ask me simply", "ask me in plain words" - in any language. ALWAYS
  invoke it too when the user asks for your view on a technical choice:
  whether it is worth doing, more than the problem needs, or replaceable by
  something simpler, and which option you would take. Invoke it even when the
  code makes the answer look obvious: the checks are what make the answer more
  than a guess. Rewrites the question in plain words and always ends with one
  marked recommendation. A structural choice first passes six checks, shown as
  a table: effort now, simpler substitute, extra work later, lock-in,
  over-engineering, easy to undo. Doing nothing is always weighed.
allowed-tools:
  - "Read(~/.claude/open-steps/**)"
---

# os-ask-simple

Two jobs. Ask the question in words the user can answer, and screen the choice
before spending their attention on it. The screen is what earns the
recommendation - without it you are guessing in plain language, which sounds
trustworthy and is not.

## Language

Write in the language the user speaks in this session. Detect it from the
conversation. Keep code, file names and identifiers in English.

## When to use

- You are about to ask the user a technical question.
- You are about to offer options.
- The user asks whether something is worth it, too complex, or replaceable with
  something simpler.
- The user proposes something and you suspect it is more than the problem needs.

## Before anything: is this even a question for them?

Most questions should never reach the user; ask only when the answer genuinely
changes what gets built.

- **Can you answer it by looking?** Read the code, the config, the last report.
  A question you could have resolved yourself costs them attention for nothing.
- **Is there a conventional default?** Take it and say you took it.
- **Would both answers lead to the same work?** Then it is not a fork.

## Light form - every question

```
<The question in one plain sentence. No jargon; if a term is unavoidable, give a
three-to-five word analogy.>

Why it matters: <one line, in terms of the product, not the code>
What changes later: <one line>
Easy to undo: <yes, and how - or no, and why>
```

Then the options, through your tool's question picker where it has one (in
Claude Code, AskUserQuestion). Offer two to four, each with a one-line
trade-off in plain words, the recommended one first and marked `(Recommended)`.

Keep the heading to 12 characters or fewer and each label to one to five
words. Claude Code's picker has the same limits, and short labels read well as
plain text too. Where there is no picker, write the same question and options
as plain text, the recommended one first and marked.

## Full form - six checks, for structural choices

Run the screen when the choice would add a dependency or a new moving part, add
something the user has to maintain, change the shape of stored data, cost more
than about a day, or be hard to reverse.

Show it as a table. Answer every row - "not checked" is allowed and honest;
silence is not.

| Check | What goes in the answer |
|---|---|
| How long now | Real effort, in hours or days, plus what has to be touched |
| Simpler substitute | The simplest thing that would also work - or "none found", having looked |
| Extra work for you later | Anything the user must do repeatedly afterwards: approvals, manual steps, watching a dashboard |
| Harder to change later | What this locks in, and what would be expensive to move afterwards |
| Over-engineering | Say yes when it is yes. A row that always answers "no" is decoration |
| Easy to undo | Reversible, and how - or one-way, and why |

Then the recommendation, in one line, as an actual opinion.

## Hard rules

1. **Always weigh doing nothing.** "Change nothing" is a real candidate, often
   the winner. If it lost, say in one line why.
2. **A recommendation is required.** Never lay out options and stop. "It depends"
   is not a recommendation - if it truly depends, say what it depends on and pick
   the option that is right under the more likely condition.
3. **Recommend against the user's own idea when the screen says so.** Plainly, in
   one sentence, with the simpler substitute named. They asked for a filter, not
   for agreement.
4. **Never recommend what you have not screened.** If the six checks were skipped
   because the choice looked small, say the choice looked small.
5. **One question at a time.** Two questions in one message means the second gets
   a careless answer.
6. **Watch your own bias.** The most interesting thing to build is not the
   recommendation. If an option is more fun to implement, that is a reason for
   suspicion, not for preference.

## Known gotchas

- **Two options that end in the same place are one option.** Do not pad the
  picker to look thorough.
- **"Over-engineering: no" answered reflexively kills the whole screen.** The row
  exists to be answered yes sometimes.
- **Effort estimates are guesses.** Say "roughly" and give a range. A confident
  number that turns out wrong costs more trust than a range ever does.
- **The user may pick the option you did not recommend.** That is the point of
  asking. Do it their way without re-arguing, and note the trade-off once.
````

## File: README.md
upstream: https://github.com/kharmanskyi/open-steps/blob/main/README.md

```text
# Open Steps

[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)

**English** · [Español](README.es.md) · [Français](README.fr.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [한국어](README.ko.md) · [中文](README.zh.md)

**Plain-language agent skills for Claude Code, Codex, Cursor and Gemini CLI.**

They keep development open to the person running it: the sessions, the
decisions, the next steps, the whole picture.

By [Pavlo Kharmanskyi](https://github.com/kharmanskyi).

I'm not an engineer. I'm a market-led builder: I look for where demand already
exists and the infrastructure doesn't, then build the missing piece. Twenty
years of building web and software products, always from the product side, and
more than 50 developers at my company today.

Apart from the company, I started building a product on my own, just
vibecoding. Partly to stay ahead of where all this is going, partly because I
think the moment has arrived for people like me: you can now imagine a serious
product and build it yourself, with no engineers or very few of them.

Then I ran straight into a wall. The agent does excellent work, then tells me
about it in commit hashes and jargon, and I genuinely cannot tell whether we
are done. Not because the work is unclear. Because nobody taught the agent to
talk to someone who doesn't speak engineering.

So I built this pack. I'm sharing it here for anyone in the same position, and
that's the whole idea behind the name: every step of building with an agent,
kept open to the person doing the building. Right now it changes what the agent
tells you. Where I want to take it next is the work itself, not just the
reporting.

## Before and after

The whole idea in one screen. Work ends, you ask "are we done?".

![The same session reported two ways: a wall of engineering detail, and a short plain-language report with a verdict](assets/before-after.svg)

<details>
<summary>The same thing as text, if the picture does not load</summary>

Without the pack:

> Hotfix deployed: session TTL misconfig in auth middleware caused 401
> cascades after key rotation; patched the refresh path, invalidated stale
> JWTs, redeployed api+web. p95 back to 180ms. Root cause: env drift after
> the 09-14 rollout. Two flaky e2e specs quarantined (known, tracked)…

With it you get this:

> People can sign in again. A bug was logging people out because their
> sessions expired far too early. The fix is live for everyone.
>
> | | |
> |---|---|
> | ✅ | Response times are back to normal |
> | ⚠️ | Until this shipped, people were being logged out over and over. |
>
> | Fully done? | Yes |
> |---|---|
> | **Anything needed from you?** | No |
> | **New debt?** | Two small ones, written down |
> | **Safe to close?** | Yes |

</details>

Same facts. One screen. The bad news gets its own row instead of hiding in
the middle of a paragraph. A second, longer example from a real session lives
in this repository, with notes on what the rewrite changed:
[`skills/os-done-or-not/references/01-prod-promote.md`](skills/os-done-or-not/references/01-prod-promote.md).

## The skills

| Skill | What it does | When it fires |
|---|---|---|
| [`os-done-or-not`](skills/os-done-or-not/) | A one-screen report with a verdict: done or not, anything needed from you, any new debt, safe to close | Work wraps up, or you ask how it went |
| [`os-step-by-step`](skills/os-step-by-step/) | Numbered steps a non-technical person can follow. The agent must first try everything itself and ask only for what truly needs you | The agent needs you to run, paste, click, approve or test something |
| [`os-ask-simple`](skills/os-ask-simple/) | The question in plain words, what it costs later, and one marked recommendation | The agent has a question or options for you |
| [`os-what-could-go-wrong`](skills/os-what-could-go-wrong/) | Assumes the decision already failed and works backwards to find out why, in a fresh agent that had no hand in it. Ends on one verdict | Something hard to undo is about to be agreed: a contract, a purchase, a migration, a launch |
| [`os-whats-next`](skills/os-whats-next/) | Merges what is verified and ready, then recommends the next task and says why in plain words | You ask what is left or what to do next |
| [`os-check-work`](skills/os-check-work/) | Does not trust another session's report. Checks every claim against what actually happened, then says what to do about it | Another session says it is done |
| [`os-say-simple`](skills/os-say-simple/) | Rewrites any text in plain words without losing facts or bad news. Give it a number and you get exactly that many points | Any text reads like engineering: a report, a comment, an error, the agent's own answer |
| [`os-big-picture`](skills/os-big-picture/) | Keeps one `BIG-PICTURE.md`: what the product is, every feature with how far it got, which parts nobody uses any more, and what is queued. It offers to open the queue as tickets in a tracker you already use | You ask where the project stands, or a session report was just written |

They work as a loop: `os-whats-next` picks the work, `os-step-by-step` walks
you through your part, `os-done-or-not` reports the result, `os-check-work`
accepts what other sessions did, `os-ask-simple` handles the questions on the
way, `os-what-could-go-wrong` attacks anything hard to undo before it is
agreed, and `os-say-simple` rescues any text that still reads like
engineering. `os-big-picture` keeps the standing file whose queue
`os-whats-next` reads as its backlog.

`os-big-picture` writes its file in plain words, so you get the whole picture
without reading code. It measures from git how old each part is and whether
anything still uses it, and it dates what it cannot measure. It opens tickets
in your tracker only after you say yes. The file stays out of your commits
unless you add it yourself. It never invents a task and never deletes
anything. The rules and the reasons behind them are in
[`skills/os-big-picture/`](skills/os-big-picture/).

## What it does on its own

**The pack finishes finished work by itself.** If a pull request has green
checks and an approved review, the agent verifies it once more and merges it.
On Claude Code that happens without a permission prompt. On Codex CLI, Cursor
CLI and Gemini CLI the merge command goes through that tool's own permission
settings, per their documentation. Whatever unblocks the most goes first.

Two things stop a merge: a claim that fails verification, or a note on the
task saying merges happen on command only. Write that note on the task
wherever another tool or person decides when to merge. To have merges on
command only, put the same note in your standing instructions file:
`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`, or the
project's `AGENTS.md` on Cursor CLI.

On Claude Code a skill can also pre-approve tools for the turn it runs in,
through its `allowed-tools` field. This pack keeps that list to what the
skills use:

| Skill | Pre-approved on Claude Code |
|---|---|
| Every skill | Reading its reports folder, `~/.claude/open-steps/` |
| `os-done-or-not` | Writing its report in that folder, and `gh pr view` and `gh pr checks` |
| `os-whats-next`, `os-check-work` | `gh pr list`, `gh pr view`, `gh pr checks` and `gh pr diff`, which read a pull request, and `gh pr merge`, for the merges above |
| `os-big-picture` | Editing its own `BIG-PICTURE.md`, its census script, `git rev-parse --git-dir` to find the repository folder, `gh repo view`, `gh issue list`, and `gh issue create`, which opens tickets after you say yes |
| `os-what-could-go-wrong` | Its premortem prompt script |
| `/open-steps:os-install-check` | `doctor.sh` |

Other commands, and files outside your project and the reports folder, go
through your own permission settings as usual. Other read-only `git` commands
need no entry, because Claude Code runs them without asking. Codex CLI, Cursor
CLI and Gemini CLI ignore the field, per their docume
```
