product-thinking
Product Thinking
A runbook for changing anything a user interacts with. The agent defaults to building exactly what was asked; this pass adds the product checks it skips — whether the change earns its permanent place on the surface, and how you'll know it worked. Work the steps before you write code, fill in the brief as you go, and fold that brief into the PR. Use it to push back when a change isn't justified, not just to wave one through.
When to run it
Run the pass whenever a diff touches a surface a user — a developer running React Doctor, or their CI — depends on. Every surface is a contract: once it ships, people build on it and you can't quietly take it back. Find where the surface lives first, so you edit the right place and can search it for something to reuse before adding.
| Surface | Where it lives | Why it's load-bearing |
|---|---|---|
| CLI command / flag | cli/index.ts, cli/commands/*.ts, cli/utils/inspect-flags.ts |
Every flag is forever — it has to be parsed, documented, tested, and kept working across releases. |
| 0–100 score | core/src/calculate-score.ts, core/src/constants.ts |
The number people screenshot and gate CI on; changing the math silently moves every user's score. |
| Config option | core/src/types/config.ts, core/src/services/config.ts |
A long-lived contract that interacts with existing precedence; a new knob is rarely removable later. |
| JSON report field | core/src/schemas.ts, core/src/build-json-report.ts |
A wire format other tools parse; a shape change breaks integrations unless schemaVersion is handled. |
| Package API / exit code | react-doctor/src/inspect.ts, api/src/diagnose.ts |
Programmatic consumers pin to it, so changes are semver-breaking and need a changeset. |
| GitHub Action input/output | action.yml |
Versioned independently (vN); workflows in other repos break when an input or output changes. |
| Terminal output / UX | cli/utils/ renderers |
The first impression and the daily experience; noise or confusion here is what makes people stop running it. |
Not here: lint rules go through the rule-research → rule-writing → rule-validate pipeline, and rule configuration through doctor-explain — this pass is for the surface around the rules, not the rules themselves. Internal-only changes (the engine, private core types, tests, tooling) skip the pass entirely; note in one line why the change is internal and move on.