Better Decisions

简体中文

AI can give you pages of analysis and still leave you to reconstruct the decision yourself.

Sometimes the problem is quieter: AI recommends too quickly. The context is incomplete, the real decision has not been defined, no fitting framework has been chosen, and the critical evidence has not been organized into one judgment. The answer may sound decisive while resting on a first-pass intuition.

As a strategy consultant, I know that a reliable recommendation is the result of work that happens before the answer. A consultant must understand the context and consequences, define the real problem, choose a fitting decision framework, and organize the critical facts, inferences, and unknowns into reasoning that can withstand challenge.

Better Decisions turns that pre-recommendation work of strategy consulting into a decision discipline the Agent must follow. For a nontrivial decision, it does not jump from the question to a recommendation; it first builds the minimum-sufficient decision basis.

The result is a standalone decision brief that makes clear what is being decided and affected, which framework or model fits and why, what the current evidence supports or leaves unanswered, what to do now, and what would change the recommendation.

The final choice remains with the real decision-maker.

Read the full product story in Chinese.

What it does

1. Restores the context that could change the judgment and clarifies the real decision, who owns it, its impact and scope, and the material differences among realistic choices.
2. Chooses a fitting decision framework or model from the decision's objective and effects and explains why it fits; when no established model applies, it derives a simple lens from the objective and outcome mechanism.
3. Maps facts, inferences, and unknowns into that model and explains what they support, weaken, or leave suspended.
4. Forms a current recommendation when the basis is sufficient and states what would change it.

For a nontrivial decision, the result is a minimum-sufficient standalone decision brief, not a fixed set of headings, tables, or lengths. It stays brief for low-stakes, reversible choices and does not reopen work that the user has already decided.

One-line install

npx skills add jinhanbuilds/better-decisions --skill better-decisions -y

This package follows the Agent Skills specification. The command above uses the cross-host skills CLI; add --agent <host> when you need to select a supported host explicitly. For a manual install, copy skills/better-decisions/ into a directory your host scans, such as ~/.agents/skills/better-decisions/ where the shared convention is supported.

The core SKILL.md and its relative references are host-neutral. skills/better-decisions/agents/openai.yaml and .codex-plugin/plugin.json are optional OpenAI/ChatGPT/Codex metadata; compatible non-OpenAI hosts may ignore them.

Reopen the Agent host after installation, then invoke:

$better-decisions Help me decide whether to release this feature to every customer next week.

The Skill also permits narrow automatic invocation when a real decision-maker is asking for help with a material choice. Mentioning the Skill, requesting research, checking status, or asking the Agent to choose its own implementation steps should not trigger it.

Useful requests

$better-decisions Restore the background and tell me what you recommend.

$better-decisions Organize the evidence first. Do not force a conclusion yet.

$better-decisions I advise the board but do not make the final decision. Help me form the case I should present.

Boundaries

• It supports the person or body that owns the decision; it does not take over the choice.
• It distinguishes source facts, user statements, inference, assumptions, and unknowns.
• It does not turn important unknowns into confident conclusions or invent numbers to fill the gaps.
• It does not turn every trade-off into a ceremony, scorecard, or experiment.
• It stops at decision support unless the user separately asks for implementation.

The package contains no executable product code, network client, telemetry, or bundled credentials. It may read material the user provides or authorizes the Agent to inspect.

Package contents

• skills/better-decisions/ — the canonical runtime Skill, trigger cases, and three result-level evaluations.
• docs/product-story.zh-CN.md — the product problem, mechanism, and boundary.
• .codex-plugin/plugin.json — optional OpenAI/ChatGPT/Codex Plugin metadata.
• scripts/ and tests/ — package validation, reproducible release building, and maintainer-only canonical-to-local synchronization.

Status and validation

Current release candidate: v0.1.0.

npm run validate
npm test
npm run eval:validate
npm run eval:run -- --output-dir dist/better-decisions-eval --iteration 1
npm run build
npm run sync:check

The three result-level cases test a guarded release recommendation, an annual purchase with missing value evidence, and restraint on a five-minute reversible choice. These checks demonstrate the behaviors on those fixtures; they do not prove that every real decision will improve.

License

MIT © 2026 Jinhan