Quickstart

A runnable check that your checkout is intact and that the shipped tooling actually executes. It is the fastest way to decide whether this repository is useful to you.

Run it

git clone https://github.com/Furox-Art/quantum-reasoning-skill.git
cd quantum-reasoning-skill
python docs/quickstart.py

Requirements: Python 3.10 or newer. No third-party dependencies, no network access, no language-model calls. Exit code 0 means every structural check passed.

What each step proves — and what it does not

Step Proves Does not prove
1. Checkout identity The clone is complete and reports a commit, version and SKILL.md digest Anything about skill quality
2. Agent Skill contract SKILL.md opens with parseable YAML front matter, declares name: quantum-reasoning, and has a description inside the 1024-character host limit That any host has loaded it
3. Reference controller Scoring, rejection, dormancy, uncertainty-driven width, collapse gating and revival all execute on real inputs That the weights or thresholds are correct — they are uncalibrated defaults
4. Benchmark harness quantum_reasoning_skill/benchmark/evaluate.py reads the seed cases and emits a comparison document That the skill helps. The rows are synthetic placeholders

Step 4 writes byte-identical placeholder rows into both the baseline and the skill condition. A +0.0000 accuracy delta is therefore the expected output. It is a harness check, not a measurement.

Verified output

Captured on Windows 11 / AMD64, CPython 3.12.10, on an LF checkout (no core.autocrlf translation) at commit 0f32ce20ac81bf7ad07c9b883eab41efaa5ebb63 on main, so the commit is obtainable by anyone reading this repository.

The block below follows the current VERSION (1.2.0) and was captured on a 1.2.0 checkout; re-run python docs/quickstart.py to refresh it.

Provenance for the block below:

  • Script: docs/quickstart.py
  • Skill version: 1.2.0 (from VERSION)
  • Skill commit: 0f32ce20ac81bf7ad07c9b883eab41efaa5ebb63
  • Controller: quantum_reasoning_skill/reference/branch_controller.py, DEFAULT_THRESHOLDS
  • Benchmark inputs: quantum_reasoning_skill/benchmark/cases.jsonl, evaluated by quantum_reasoning_skill/benchmark/evaluate.py
  • Platform: Windows 11 (AMD64), CPython 3.12.10
  • SKILL.md digest: 7430 bytes, sha256:38e23ee1a23ee254 — the git blob

On a checkout with CRLF translation (Windows core.autocrlf=true) the SKILL.md line instead reads 7578 bytes sha256:f1ee3c89a671c3f0. That is the same content with line endings converted, not a different SKILL.md; 7430 is the value CI and every Linux and macOS user sees.

The commit and branch lines name whichever checkout you ran, so they change between runs and cannot match a pasted copy forever. The version lines follow the current VERSION file. Every other line is deterministic for a given commit. This file is the single source for this output — the README links here instead of repeating it, precisely because a duplicated copy drifts.

Quantum Reasoning Skill - quickstart verification
--------------------------------------------------------------

[1/4] Checkout identity
    commit      : 0f32ce20ac81bf7ad07c9b883eab41efaa5ebb63
    VERSION     : 1.2.0
    SKILL.md    : 7430 bytes  sha256:38e23ee1a23ee254
    branch      : main

[2/4] Agent Skill contract (SKILL.md)
    name        : quantum-reasoning
    description : 266 chars
    body        : 142 lines
    status      : front matter parses and is host-ready

[3/4] Reference controller (quantum_reasoning_skill/reference/branch_controller.py)
    scenario: 'should we migrate our monolith to microservices?'
      strangler-fig-incremental  active
      big-bang-rewrite           rejected
      modular-monolith           active
      feature-flag-carveout      dormant
    uncertainty : 0.9651
    next width  : 6-10 branches (high uncertainty -> widen)
    leader      : strangler-fig-incremental
    collapse    : BLOCKED - leader score below collapse threshold
    revival     : feature-flag-carveout -> active (evidence +0.25 >= 0.15)
    surviving   : 3 branches

[4/4] Benchmark evaluator smoke run - SYNTHETIC PLACEHOLDER ROWS
    No language model is called. Baseline and skill rows below are
    byte-identical placeholders that exist only to prove the harness runs.
    The resulting accuracy is NOT a measurement of this skill.
    cases       : 6 seed cases
    accuracy    : 0.1667 (both conditions)
    delta       : +0.0000 accuracy, +0.0% tokens
    reading     : 0.00 delta is the expected result for identical
                 placeholder rows. It is a harness check, not evidence.

--------------------------------------------------------------
Provenance for every number printed above
--------------------------------------------------------------
    script      : docs/quickstart.py
    skill ver   : 1.2.0   (VERSION)
    commit      : 0f32ce20ac81bf7ad07c9b883eab41efaa5ebb63
    platform    : Windows 11 (AMD64)
    python      : 3.12.10 (CPython)
    controller  : quantum_reasoning_skill/reference/branch_controller.py DEFAULT_THRESHOLDS
    benchmark   : quantum_reasoning_skill/benchmark/cases.jsonl + quantum_reasoning_skill/benchmark/evaluate.py

RESULT: PASS (structure verified; no performance claim implied)

Reading step 3

The scenario is the README's monolith-migration example. Three things happen:

  • big-bang-rewrite is rejected because its contradiction score is 0.91, at or above the reference reject threshold of 0.85.
  • feature-flag-carveout becomes dormant because its support score falls below 0.35, and it revives once evidence rises by 0.25 (threshold >= 0.15). Dormant branches are recoverable by design.
  • Collapse is BLOCKED. strangler-fig-incremental leads, but its score is below the 0.78 collapse threshold.

That last line is the point. A system tuned to look decisive would have collapsed anyway. These defaults deliberately refuse to, because nothing in this repository calibrates them. The weights are documented in MEASUREMENT.md so they can be measured rather than trusted.

Next