think-before

A fast yes/no reflection before you change something.

A small change in a big app is rarely small. think-before is a tiny, zero-dependency CLI that walks you through a sharp set of yes/no questions so the side-effects you'd otherwise discover in production surface on the whiteboard instead.

It's the pause between "this is a one-line fix" and git push.

$ npx @geekyants/think-before

Quick — Blast-radius check
A small change in a big app is rarely small. 60 seconds of honesty before you start.
Answer fast — y yes · n no · s skip · ? why · q quit

  Blast radius
   3/16 Is this in shared/global code used in many places? [y/n] ✓ yes  ⚠ worth a second look
         ↳ Shared code multiplies the blast radius — one edit ripples everywhere it's imported.

Quick start

No install needed:

npx @geekyants/think-before            # quick blast-radius check (default)
npx @geekyants/think-before full       # the full pre-development discovery checklist

Or install it:

npm install -g @geekyants/think-before
think-before                           # the installed command is just `think-before`

Modes

| Mode | What it's for | | --- | --- | | quick (default) | The "I'm about to touch the big app" moment. Blast radius, data, contracts, your safety net, and timing. | | full | A team-level pre-development discovery sweep: problem, users, scope, risks, plus the questions specific to your role. |

Both modes ask at most 10 questions — the ones most relevant to you. Every question is tagged with the roles it applies to and a priority; pick a role and you get your fundamentals plus your own specialty, never a wall of questions meant for someone else:

think-before --role designer        # quick check, design-focused
think-before full --role engineer   # discovery, architecture-focused
think-before full --role developer  # discovery, implementation-focused

Smart, stack-aware questions

Before each run, think-before does a quick read-only scan of your working directory and figures out whether it's frontend, backend, or full-stack — by recognizing common frameworks and tooling:

• Frontend: React, Vue, Angular, Svelte, SolidJS, Preact, React Native, Expo, Vite, Tailwind …
• Backend: Express, NestJS, Fastify, Koa, Django, Flask, FastAPI, Laravel, Symfony, Rails, Spring Boot, Go (Gin/Echo/Fiber), Actix/Axum, .NET …
• Full-stack meta-frameworks: Next.js, Nuxt, Remix, SvelteKit, Astro
• It also notices a database/ORM (Prisma, TypeORM, Sequelize, Mongoose, pg/mysql/mongodb, migrations), Docker, monorepos, and whether tests exist.

Based on what it finds, it appends a Stack-specific section with the questions that actually apply — API-contract and migration-safety questions for a backend, breakpoint/accessibility/shared-component questions for a frontend, deploy-ordering for full-stack, and so on.

Detected full-stack · Next.js, React  ·  role: engineer

  Stack-specific — full-stack (Next.js, React)
  22/31 Does this change a request/response shape, field, or status code a client depends on? [y/n] …
  26/31 Is the schema/migration reversible and backward-compatible with the running code? [y/n] …

Skip the scan anytime with --no-detect.

Your role & saved config

The first time you run it in a project, it asks what your role is (designer / engineer / developer) and tailors the whole question set to you. Your answer — plus the detected stack — is remembered per project in:

~/.config/think-before/config.json      # honors $XDG_CONFIG_HOME

So next time it doesn't ask again. To change it: --role <r> to set explicitly, or --reset-role to be asked again. See everything that's stored with:

think-before config

Full-screen mode

By default, in an interactive terminal think-before takes over the screen like a classic text-mode installer — one boxed question at a time, no scrollback noise, so you can actually think about each one:

╔══════════════════════════════════════════════════╗
║                think-before · quick                ║
╠══════════════════════════════════════════════════╣
║                                                    ║
║  Question 5 / 10  ·  Blast radius                  ║
║                                                    ║
║  Could this change behavior in flows you are NOT   ║
║  going to manually test?                           ║
║                                                    ║
║  ↳ The side-effects you don't test for are exactly ║
║    the ones that reach production.                 ║
║                                                    ║
║              ‹ Yes ›   ‹ No ›   ‹ Skip ›           ║
║                                                    ║
╚══════════════════════════════════════════════════╝
  y yes  n no  s skip  ? why  q quit   [█████░░░░░] 5/10

It uses the terminal's alternate screen buffer (like vim or less), so when you're done — or quit with q/Ctrl-C — your terminal is restored exactly as it was, and the summary + report prompt print into your normal scrollback.

When input is piped or it's not a real terminal (CI, | node …), it automatically falls back to the classic scrolling line mode — so scripting and pipelines still work. Force either mode with --no-tui / --tui.

How to answer

Single keypress, no Enter needed:

| Key | Meaning | | --- | --- | | y | yes | | n | no | | s or Enter | skip (logs it as an open question) | | ? | show why this question matters | | q or Esc | quit |

Answers that point at risk get flagged with a one-line reason. At the end you get a summary of everything worth a second look — and the option to save it.

A skipped question is an open question, not a free pass. A short list of "we don't know yet" is more valuable than a confident plan built on untested assumptions.

Options

--role <r>       Set your role: designer | engineer | developer (remembered per project)
--reset-role     Forget the saved role and ask again
--no-detect      Skip the project scan and stack-specific questions
--no-tui         Use the classic scrolling line mode instead of full-screen
--tui            Force full-screen mode
--save [file]    Save a Markdown report (optionally to <file>) without asking
--no-save        Don't save and don't ask
--list           Print the checklist and exit (no prompts)
--no-color       Disable colored output
-v, --version    Print version
-h, --help       Show this help

There's also a config mode (think-before config) that prints where your config lives, your saved role, and what was detected in the current directory.

The report is plain Markdown — drop it into a PR description, a ticket, or your design doc.

Use as a library

import {
  quick, full, filterSections, selectSections, runSession, buildMarkdown,
  detectProject, stackSection,
} from "@geekyants/think-before";

const detection = detectProject(process.cwd()); // { kind: "fullstack", frameworks: [...] }
const extra = stackSection(detection, "engineer");

const all = [...filterSections(full, "engineer"), ...(extra ? [extra] : [])];
const sections = selectSections(all, "engineer"); // role-tailored, capped at 10
const result = await runSession(full, sections);
const markdown = buildMarkdown(full, result, new Date());

Develop

npm install
npm run dev        # run the CLI straight from TypeScript source
npm run build      # compile to dist/
npm start          # run the built CLI

Want to add or tweak questions? They live in src/checklists.ts — each question declares which answer (yes/no) is the risky one, an optional why, the roles it applies to, and a priority (higher = asked first when the 10-question cap kicks in). PRs welcome.

License

MIT