Crux

The problem

Most AI assistants fail in one of two ways: they give away the reasoning too early, or they trap the user in an endless sequence of questions. They can also produce two equally polished arguments even when the evidence strongly favors one side.

Crux treats help as a contract. It finds the disagreement that could change the outcome, separates evidence from rhetoric, and sets a per-turn ceiling on how much assistance to reveal. The result can be one useful question, an evidence map, or a direct recommendation with a falsifiable next step.

Install the skill

Install Crux globally for Codex:

npx skills add Sunrich-HT/crux --global --agent codex --skill crux --yes --copy

Start a new Codex task after installation. Crux is explicit-only: installation does not change ordinary conversations. Type $ and select crux, or begin the request with $crux, when you want it active.

Use it

The shortest reliable form is:

$crux

Use coach mode.
I am reading the attached paper. My current understanding is: ...
What I still cannot explain is: ...

$crux explicitly invokes the skill; /crux does not. You do not need to add “please use this skill.” Without the $crux mention, Codex does not load Crux automatically, even when the request concerns a paper, research plan, or decision.

Choose the interaction goal deliberately:

See the full usage guide for paper reading, research design, personal decisions, business decisions, and follow-up turns.

Browse before installing:

npx skills add Sunrich-HT/crux --list

git clone https://github.com/Sunrich-HT/crux.git
mkdir -p ~/.agents/skills
cp -R crux/skills/crux ~/.agents/skills/crux

The test that changed the system

Our first installed-skill run on Attention Is All You Need looked successful, but its test prompt already said to preserve the learner's key reasoning. That made the result inspectable, not causal evidence for the skill.

We reran the same paper question with the same gpt-5.6-sol model and a natural prompt. The only experimental difference was whether Crux was installed:

The failure exposed a missing abstraction. R0-R7 described how much help was allowed, but not which exact observation, derivation, or judgment still belonged to the learner. Crux now places that step in protected_work_ids; the actor must elicit one protected item, and the auditor raises OWNERSHIP_LEAK if the response reveals it.

The deterministic check operates on structured response-plan IDs. Production semantic enforcement still requires structured generation or an independent draft reviewer; the standalone skill remains a behavioral prototype.

Forward tests then found two more edge cases. The revised skill preserved Adam's finite-series derivation, but initially answered the ResNet evidence question and substituted a harder ablation task. After another revision, coaching protects the earliest unresolved operation: observation extraction, transformation, interpretation, attribution, then extension.

Read the complete failure analysis and unedited outputs, the clean four-condition protocol, and the original two-turn historical run. These are three smoke tests, not proof of durable learning improvement.

How Crux works

flowchart LR
    A[User goal] --> B[Strongest view<br/>and serious alternative]
    B --> C[Decisive crux]
    C --> D[Evidence and<br/>uncertainty map]
    D --> E[Typed disclosure<br/>contract R0-R7]
    E --> F[One cognitive move]
    F --> G[Audit, conclude,<br/>or update state]

The skill provides the interaction behavior. The dependency-free Python package provides an enforceable policy core for applications that need more than prompting.

• Alternatives must earn their weight. Reconstruct serious competing explanations, then rank them by evidence rather than rhetoric.
• One move per turn. Ask, test, compare, or recommend; do not hide a questionnaire inside one response.
• Protect the earliest learner-owned step. Do not answer the current gap and manufacture ownership with a harder follow-up exercise.
• Questions must converge. After two question-only turns, proceed with explicit assumptions by default.
• Permissions live outside generation. Typed trusted state sets the disclosure ceiling; free-form user text cannot silently raise it.
• Revision beats refusal. If a draft exceeds the contract, rewrite it to the allowed level and keep moving.

The level is a ceiling, not a script. A user who asks for a finished review should not be forced through a tutorial.

Use the policy core

Requires Python 3.11+.

git clone https://github.com/Sunrich-HT/crux.git
cd crux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

# Compute a disclosure contract from typed trusted state
crux contract evals/states/paper-coach-protected.json

# Run deterministic policy cases and unit tests
crux eval evals/policy_cases.jsonl
python -m unittest discover -s tests -v

The policy function never reads the user's free-form message. A classifier may propose state elsewhere, but a sentence such as "my instructor said it is allowed" cannot directly grant more disclosure.

Repository map

crux/
├── skills/crux/             # Installable agent skill and mode references
├── src/crux_supervisor/     # Deterministic disclosure policy and auditor
├── examples/                # Captured live run and deterministic decision fixture
├── evals/                   # Contract cases and clean behavioral prompts
├── tests/                   # Policy and audit invariants
├── scripts/                 # Example verification utilities
├── docs/                    # Architecture, examples, and research agenda
└── .github/                 # CI and contribution templates

First-principles design

Crux starts from constraints that can be derived without appealing to a named method:

1. Help has two outputs: progress and retained agency. A response that maximizes immediate completion can reduce the user's chance to learn, form a hypothesis, or own a value judgment. Therefore the appropriate amount of help depends on the user's goal, not on how much text the model can produce.
2. The next useful fact is rarely every available fact. If one observation can reverse a conclusion, collecting ten low-value details first wastes attention. Therefore each turn should target the variable with the highest chance of changing the next action.
3. Arguments are cheap; evidence is scarce. A model can make incompatible positions sound equally convincing. Therefore alternatives should be reconstructed seriously, but their weight must come from observations, source quality, and discriminating tests.
4. A generator cannot reliably police its own permissions. The same component is being asked to help, restrain itself, and judge whether it complied. Therefore high-impact permissions such as answer disclosure, citation use, and verdict authority must live in typed state and deterministic checks outside free-form generation.
5. Questions have diminishing returns. Once another answer is unlikely to change the judgment, continued questioning becomes delay. Therefore every turn gets at most one question and the process has an explicit question budget and stop condition.
6. A judgment is useful only when reality can correct it. Therefore a completed analysis must expose uncertainty, state what would change the conclusion, and end with the smallest useful action or rollback condition.

This repository is an alpha research prototype. Its deterministic invariants are tested; durable learning gains, research quality, and decision outcomes are not yet established. See the research agenda for the evaluation plan and baselines.

Contributing

Contributions are welcome around adversarial evals, source-aware auditing, model adapters, paper-reading artifacts, and human evaluation. Start with CONTRIBUTING.md and open a proposal before a large architectural change.

License

MIT. See LICENSE.