exloop 0.1.0__tar.gz → 0.3.0__tar.gz

exloop-0.3.0/.gitignore

@@ -0,0 +1,8 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.ruff_cache/
+.DS_Store
+# hatchling copies this file into the sdist as it is; keep it free of anything private.

exloop-0.3.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: exloop
+Version: 0.3.0
+Summary: Human-led exploration skills for any AI tool that reads SKILL.md: a persistent map, structured idea comparison, and a zero-dependency state helper.
+Project-URL: Repository, https://github.com/hzshen88/exloop
+Project-URL: Issues, https://github.com/hzshen88/exloop/issues
+Author: hzshen88
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: claude-code,codex,exploration,human-in-the-loop,research-questions,skill
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# exloop
+
+**Human-led exploration with a persistent map.** An AI companion that does not answer
+your question for you: it asks one or two honing questions, walks one edge at a time,
+keeps a map of where you have been, and offers the next step that is within reach. When
+you do not yet have enough language or background to form a question, it first offers one
+concrete foothold and lets your response set the direction. When
+several explanations are in play, Idea Lab helps draw, attack, compare, and check them
+without forcing an early winner. Both ship as skills for any AI tool that reads
+`SKILL.md` files — Claude Code, Codex, and the like.
+
+## Installing
+
+Most people get exloop by installing [newlife](https://pypi.org/project/newlife/), which
+depends on it:
+
+```bash
+python -m pip install newlife
+newlife start my-research
+```
+
+`start` installs the exloop and Idea Lab skills, together with newlife's own, into every AI tool found
+on the machine.
+
+On its own:
+
+```bash
+python -m pip install exloop
+python -c "import exloop; print(exloop.skills_dir())"
+```
+
+and copy the skill directories it contains into your AI tool's skills folder
+(`~/.claude/skills/`, `~/.codex/skills/`, ...).
+
+## Using it
+
+Open a folder in your AI tool and say:
+
+> Explore this with me: *your curiosity*
+
+The AI asks; you answer and decide. The map is kept silently in
+`~/.exloop/explorations/<slug>/`, one folder per exploration — the same folder whichever
+AI tool you switch to, because the identity is the slug, not the chat session. When you
+close an exploration the AI archives the record into your research repository
+(`explorations/<slug>/`). When a boundary has become a decidable question — you can say
+what measurement would make the answer different — the AI says so once, and on your yes
+hands the record to newlife (`questions/<slug>/origin/`), where the preregistration
+discipline takes over.
+
+Idea Lab is not a second entry point that must be completed first. It is an optional
+reasoning pattern inside exploration. The AI uses it when competing or underspecified
+explanations need to be made explicit, challenged, and distinguished.
+
+## What is in the package
+
+- `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
+  marked, pivoted, closed — and the map as their projection), the state model, and a
+  bounded evidence-review method that returns source checks to the current exploration.
+- `skills/idea-lab/SKILL.md` with domain profiles for formal theory, empirical and causal
+  research, simulation, engineering and product mechanisms, and interpretive research.
+- `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill
+  runs — `init`, `mark`, `pivot`, `show`, `close`, `list`, `archive`, `handoff`, and a
+  `self-test`.
+- `exloop.skills_dir()`: the one Python function, so that newlife can locate the skill
+  files. exloop has no other API and no dependencies.
+
+Requires Python 3.11 or newer.
+
+## This repository
+
+| Path | What it holds |
+|---|---|
+| `skills/exloop/` | The persistent, human-led exploration skill and state helper. |
+| `skills/idea-lab/` | The optional Draw—Attack—Compare—Check reasoning pattern and domain profiles. |
+| `src/exloop/__init__.py` | `skills_dir()`, the one Python function. |
+| `scripts/install-skill.py` | Installs the master byte for byte into AI tool directories; `--force` to overwrite drifted copies. |
+| `scripts/check_release_artifacts.py` | Refuses to ship anything but the skills: run it on `dist/` before `uv publish`. |
+
+```bash
+python3 skills/exloop/scripts/exploration_state.py self-test
+uv build --out-dir dist && python3 scripts/check_release_artifacts.py dist
+```
+
+The skill is used downstream by [newlife](https://github.com/hzshen88/newlife), which
+depends on this package. Apache-2.0.

exloop-0.3.0/README.md

@@ -0,0 +1,85 @@
+# exloop
+
+**Human-led exploration with a persistent map.** An AI companion that does not answer
+your question for you: it asks one or two honing questions, walks one edge at a time,
+keeps a map of where you have been, and offers the next step that is within reach. When
+you do not yet have enough language or background to form a question, it first offers one
+concrete foothold and lets your response set the direction. When
+several explanations are in play, Idea Lab helps draw, attack, compare, and check them
+without forcing an early winner. Both ship as skills for any AI tool that reads
+`SKILL.md` files — Claude Code, Codex, and the like.
+
+## Installing
+
+Most people get exloop by installing [newlife](https://pypi.org/project/newlife/), which
+depends on it:
+
+```bash
+python -m pip install newlife
+newlife start my-research
+```
+
+`start` installs the exloop and Idea Lab skills, together with newlife's own, into every AI tool found
+on the machine.
+
+On its own:
+
+```bash
+python -m pip install exloop
+python -c "import exloop; print(exloop.skills_dir())"
+```
+
+and copy the skill directories it contains into your AI tool's skills folder
+(`~/.claude/skills/`, `~/.codex/skills/`, ...).
+
+## Using it
+
+Open a folder in your AI tool and say:
+
+> Explore this with me: *your curiosity*
+
+The AI asks; you answer and decide. The map is kept silently in
+`~/.exloop/explorations/<slug>/`, one folder per exploration — the same folder whichever
+AI tool you switch to, because the identity is the slug, not the chat session. When you
+close an exploration the AI archives the record into your research repository
+(`explorations/<slug>/`). When a boundary has become a decidable question — you can say
+what measurement would make the answer different — the AI says so once, and on your yes
+hands the record to newlife (`questions/<slug>/origin/`), where the preregistration
+discipline takes over.
+
+Idea Lab is not a second entry point that must be completed first. It is an optional
+reasoning pattern inside exploration. The AI uses it when competing or underspecified
+explanations need to be made explicit, challenged, and distinguished.
+
+## What is in the package
+
+- `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
+  marked, pivoted, closed — and the map as their projection), the state model, and a
+  bounded evidence-review method that returns source checks to the current exploration.
+- `skills/idea-lab/SKILL.md` with domain profiles for formal theory, empirical and causal
+  research, simulation, engineering and product mechanisms, and interpretive research.
+- `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill
+  runs — `init`, `mark`, `pivot`, `show`, `close`, `list`, `archive`, `handoff`, and a
+  `self-test`.
+- `exloop.skills_dir()`: the one Python function, so that newlife can locate the skill
+  files. exloop has no other API and no dependencies.
+
+Requires Python 3.11 or newer.
+
+## This repository
+
+| Path | What it holds |
+|---|---|
+| `skills/exloop/` | The persistent, human-led exploration skill and state helper. |
+| `skills/idea-lab/` | The optional Draw—Attack—Compare—Check reasoning pattern and domain profiles. |
+| `src/exloop/__init__.py` | `skills_dir()`, the one Python function. |
+| `scripts/install-skill.py` | Installs the master byte for byte into AI tool directories; `--force` to overwrite drifted copies. |
+| `scripts/check_release_artifacts.py` | Refuses to ship anything but the skills: run it on `dist/` before `uv publish`. |
+
+```bash
+python3 skills/exloop/scripts/exploration_state.py self-test
+uv build --out-dir dist && python3 scripts/check_release_artifacts.py dist
+```
+
+The skill is used downstream by [newlife](https://github.com/hzshen88/newlife), which
+depends on this package. Apache-2.0.

exloop-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "exloop"
+version = "0.3.0"
+description = "Human-led exploration skills for any AI tool that reads SKILL.md: a persistent map, structured idea comparison, and a zero-dependency state helper."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "hzshen88" }]
+keywords = ["exploration", "research-questions", "skill", "claude-code", "codex", "human-in-the-loop"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/hzshen88/exloop"
+Issues = "https://github.com/hzshen88/exloop/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The masters are under skills/ at the repository top, the copies people read and edit; the
+# wheel carries byte copies under exloop/skills/, located via `import exloop; exloop.skills_dir()`.
+# newlife's `skills install` uses that to install the exploration skills alongside its own,
+# without importing any exloop code.
+[tool.hatch.build.targets.wheel]
+packages = ["src/exloop"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/exloop" = "exloop/skills/exloop"
+"skills/idea-lab" = "exloop/skills/idea-lab"
+
+# The sdist uses only-include, not include: include patterns are gitignore-style and unanchored,
+# so "README.md" would match every README.md in the tree. only-include takes exactly these paths.
+# scripts/check_release_artifacts.py compares the built artifacts file by file and must pass
+# before anything is published.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/exloop", "skills/exloop", "skills/idea-lab", "README.md", "LICENSE", "pyproject.toml"]

{exloop-0.1.0 → exloop-0.3.0}/skills/exloop/SKILL.md

@@ -36,23 +36,21 @@ Before the first substantive reply, read
 [references/protocol.md](references/protocol.md). It contains the interaction
 rules and the observed failure modes this skill must resist.
 
-## Before the first exploration in a research repository: set things up yourself
+## Set up only the persistence the person requested
 
-The person should never have to type a shell command. If the conversation is happening
-inside a research repository (or the person wants their explorations and questions kept
-somewhere), do the setup for them, telling them in one line what you are doing:
+The person should never have to type a shell command. Conversation-only exploration needs
+no setup. Sustained exploration uses the helper already shipped with exloop; initialize its
+map and continue without installing NewLife.
 
-1. `newlife` missing from PATH? Install it: `uv tool install newlife` (fallback:
-   `pipx install newlife`, then `python3 -m pip install --user newlife`). It brings the
-   `exloop` package along, so this skill's helper and the two newlife skills arrive too.
-2. Not yet a research repository (no `NEXT.md`)? Run `newlife start .` in it — git init,
-   `.gitignore`, `NEXT.md`, and the skills installed into every AI tool found. If it
-   reports a missing git identity, ask the person for a name and email once and set them.
-3. Then continue as below. Every later command — `newlife init`, `pilot`, `freeze`, `run`,
-   `check`, `audit`, this skill's `archive` and `handoff` — is yours to run at the moment
-   the skills say so; the person only decides.
+If the person explicitly asks to establish the full NewLife research workflow, install a
+compatible NewLife package and run `newlife start .` in the named repository. Say what will
+be installed and where before changing the environment. A request to explore, keep an
+exloop map, verify a source, or archive into an existing research repository does not by
+itself authorize another package or host-wide skill installation.
 
-Say what you installed and where; never install anything else on the strength of this.
+Run exloop's own helper commands when their documented trigger occurs. Offer `newlife init`
+and formal handoff only when NewLife is available and the person chooses to formalize the
+boundary.
 
 ## What you make while exploring goes into the research repository, not a temp directory
 
@@ -86,12 +84,21 @@ exactly how one exploration in 2026-08 ended up in three directories.
 
 ## Core loop
 
+Before step one, check whether the person can enter the question yet. If they want to
+explore but lack the language, background or current state to form a usable question, use
+the **receive — offer one foothold — return direction** move in
+[the protocol](references/protocol.md). This is a conditional opening move, not a new stage,
+profile or state transition. Skip it when the person already has a direction or wants a
+direct answer.
+
 1. **Hone the question.** If the curiosity is vague, ask one high-leverage
    question and offer a sharper restatement. Ask at most two rounds. If the
    person says to start, stop honing immediately.
 2. **Advance one edge.** Add one mechanism, distinction, counterexample, or
    piece of evidence—not a complete lecture. Match complexity to the person's
-   language and corrections.
+   language and corrections. When a material factual or novelty claim needs a
+   source, use [the bounded evidence review](references/evidence-review.md) and
+   return its evidence to this same edge; lookup is not a stage transition.
 3. **Name what is forming.** When the person offers an inchoate judgment from
    experience, give it a short reusable name and connect it to a mechanism.
 4. **Challenge the claim, not the person.** Restate the claim before testing it.
@@ -103,6 +110,30 @@ exactly how one exploration in 2026-08 ended up in three directories.
    boundaries. They are proposals, not a menu the person must select. A new
    judgment or fact from the person may legitimately redirect the exploration.
 
+## When several explanations are live
+
+**REQUIRED SUB-SKILL:** Use `idea-lab` when one observation supports two or more
+plausible mechanisms, the person asks to compare explanations, or a favored story
+needs alternatives before formal framing.
+
+Idea Lab is a reasoning pattern inside this exploration, not a stage before or
+after exloop. Do not ask the person to choose between them, start a second
+exploration, or make them complete a four-step worksheet. Exloop continues to own
+the conversation, persistent state, pivots, and handoff; Idea Lab supplies the
+Draw—Attack—Compare—Check structure one useful edge at a time.
+
+In sustained mode, project its useful changes into the existing map rather than
+inventing a parallel ledger:
+
+- a live candidate explanation is a `node`;
+- a missing discriminator or unsupported premise is `stuck`;
+- a mechanism that survives and transfers is a `framework`;
+- a rejected route, with its reason, is `abandoned`;
+- a reversal or unexpected connection is a `surprise`.
+
+Do not mark every row of an Idea Lab board. Preserve only changes that matter to
+future conversation.
+
 ## Human control and pivots
 
 - Never change the exploration target merely because another direction looks
@@ -135,8 +166,8 @@ artifact:
   paths, surprises, and pivots;
 - state what evidence was observed versus inferred;
 - record closure in sustained mode (`close`), then copy the record into the
-  person's **research repository** — the one `newlife start` created, the one
-  that holds `questions/` — with `archive --repo <research repo>`: it lands in
+  person's named **research repository** — including one created by `newlife start` —
+  with `archive --repo <research repo>`: it lands in
   `explorations/<slug>/process/` there, and the first time it also writes the
   four-section `README.md` skeleton and an empty `artifacts/`. The archive folder
   carries the same slug as the workbench, so the two never disagree about which
@@ -165,6 +196,15 @@ switch to a workflow that locks the hypothesis, analysis, prediction, and
 decision rule first. Label anything already inspected as exploratory. Anything
 run during the exploration counts as *seen* for a later preregistration.
 
+**The line is not "do not look at data".** Exploration looks at data — that is its job, and
+a hypothesis grown out of what you saw is exactly what it is meant to produce. The line
+falls one step later: once the question is handed off, **the hypothesis and the direction
+you expect must be written down before the pilot runs**, because the pilot looks at every
+quantity a criterion names and may hand you the answer before anything is frozen. Changing
+the hypothesis after that point is HARKing, even though changing it before was the method.
+`newlife-goal` §3 says what must be fixed by then; the second half of `newlife-prereg`
+rule one says what to do when the pilot has already answered the main criterion.
+
 ## Authorization boundary
 
 This skill changes conversational behavior and, in sustained mode, writes only

exloop-0.3.0/skills/exloop/references/evidence-review.md

@@ -0,0 +1,63 @@
+# Bounded evidence review
+
+Use this reference when a claim inside an exploration materially depends on a source,
+prior method, factual precedent, or novelty judgment. It is an operation inside the current
+conversation or exploration, not a new stage.
+
+## Start with a bounded question
+
+Write down, in one sentence each:
+
+- the exact claim to check;
+- what current choice or candidate route the answer could change;
+- what would count as enough evidence for that choice.
+
+If the request already supplies these, use them. Do not interview the person again. If the
+claim is incidental and cannot change the work, mark it unverified and continue rather than
+opening an unbounded survey.
+
+## Gather evidence in this order
+
+1. Check the current repository, cited artifact and prior work already supplied. Preserve
+   exact paths, versions and dates.
+2. When external lookup is authorized and needed, prefer primary sources: the paper for a
+   scientific claim, official documentation or source code for a technical claim, and the
+   original dataset/registry for a data claim.
+3. Read enough of the method and limitations to test the exact claim. A title, abstract,
+   search snippet or secondary paraphrase is not evidence for a precise implementation or
+   boundary claim.
+4. Seek the strongest relevant counterexample or conflicting source. Explain differences
+   in population, mechanism, implementation, measurement or date rather than averaging
+   incompatible evidence into one confidence label.
+5. Record what was directly observed, what is inferred, and what remains unknown. “No
+   source found” means unresolved, never novel or false.
+
+For a broad question, split independent searches only when the available host and the
+person's request allow delegation. Sequential work is equally valid. Report every
+pre-specified branch, including disconfirming evidence; do not search variants until one
+supports the favored route.
+
+## Return to the caller
+
+Return a compact evidence packet:
+
+```markdown
+**Claim checked:** <exact claim>
+**Finding:** supported | contradicted | mixed | unresolved
+**Evidence:** <source, version/date, and the fact it establishes>
+**Limits:** <what the evidence does not establish>
+**Effect on the current exploration:** <which route/assumption changed, or none>
+```
+
+Then resume the question or comparison that requested the check. Do not create a formal
+question, analysis plan, preregistration, repository edit or new persistent ledger merely
+because the lookup finished. Those actions require their own request or transition.
+
+## Provenance
+
+This bounded form adapts the useful source-grounding and anti-cherry-picking principles in
+K-Dense's Science-Superpowers `surveying-prior-work` and
+`dispatching-parallel-investigations`, pinned for this integration at commit
+`ccc1b2d41a389b2d6dadf1945603f81d66c5e85e` (MIT). The text and stage boundaries here are
+specific to exloop and were rewritten for its single-state workflow.
+

{exloop-0.1.0 → exloop-0.3.0}/skills/exloop/references/protocol.md

@@ -17,6 +17,25 @@ Do not fill all four slots mechanically. A short question can be the whole turn.
 The purpose is to advance one edge and leave room for the person to supply the
 fact or judgment that changes the target.
 
+## Make the question enterable when needed
+
+Use this opening move only when the person wants to explore but lacks the language,
+background or current state needed to form a usable question:
+
+1. **Receive.** Reflect the curiosity or difficulty without classifying the person. If they
+   explicitly sound tired or overwhelmed, reduce the ambition of the turn and leave stopping
+   as a valid path.
+2. **Offer one foothold.** Give one concrete example, distinction or minimal model they can
+   inspect. Supply only enough common ground for them to participate, not a prerequisite
+   lecture.
+3. **Return direction.** Ask what in that foothold feels alive, strange or connected to
+   their experience. Treat their answer, correction or rejection as the source of the
+   direction, then enter the ordinary exploration loop.
+
+Do not use an intake questionnaire, assign a readiness level, persist a deficit judgment or
+require a research-shaped question. Skip this move when the person already has a direction
+or only wants a direct answer.
+
 ## Hone without turning it into intake
 
 - Infer complexity from the person's language; do not ask for age, credentials,
@@ -105,6 +124,7 @@ an experiment, a decision, a design, or simply a map to resume later.
 | “They ignored my options, so I should ask again.” | Unselected candidates remain open; continue with the person's new material. |
 | “They changed topics, so the old path is abandoned.” | Silence or topic movement is not abandonment; retire only explicit or structurally obsolete paths. |
 | “I cannot paraphrase this, but the person has not said they are confused.” | Record the assistant's own blockage as `stuck`; it identifies missing structure. |
+| “They cannot answer my honing question, so I should diagnose their readiness or ask for background.” | Offer one concrete foothold, let their response supply direction, and keep any inference temporary and correctable. |
 | “This new direction is clearly better, so I can pivot.” | Only the person's new target supplies the pivot; the assistant may detect and record it, not invent it. |
 | “More explanation is more helpful.” | Prefer one mechanism and one pressure test; verbosity can bury the person's contribution. |
 | “A polished synthesis proves the exploration succeeded.” | Preserve unresolved boundaries and discarded paths; do not rewrite the route as inevitable. |

{exloop-0.1.0 → exloop-0.3.0}/skills/exloop/references/state-model.md

@@ -109,8 +109,8 @@ Render or inspect the current map (do this at the start of every resumed turn):
 python3 $H/scripts/exploration_state.py show --id 2026-09-05-university-after-ai
 ```
 
-Record explicit closure, then copy the record into the person's research
-repository (the one `newlife start` created):
+Record explicit closure, then copy the record into the person's named research
+repository (which may be one `newlife start` created):
 
 ```bash
 python3 $H/scripts/exploration_state.py close --id 2026-09-05-university-after-ai \

{exloop-0.1.0 → exloop-0.3.0}/skills/exloop/scripts/exploration_state.py

@@ -9,8 +9,8 @@ thread id** — that is how one exploration ended up scattered across
 `~/.codex/explorations/<thread>/` and `~/.workbuddy/explorations/<session>/`
 in 2026-08, and why the tool-specific defaults were removed.
 
-Where the record goes when the exploration ends is the **research repository** (the one
-`newlife start` creates): `archive --repo` puts it under `explorations/<slug>/process/`,
+Where the record goes when the exploration ends is the person's named **research repository**
+(including one created by `newlife start`): `archive --repo` puts it under `explorations/<slug>/process/`,
 `handoff --repo` under `questions/<slug>/origin/`. Not the exloop repository.
 """
 
@@ -431,8 +431,8 @@ def command_list(args: argparse.Namespace) -> None:
 def _target(args: argparse.Namespace, ident: str, default_rel: str) -> Path:
     """Where an archive or handoff lands: `--to <dir>` verbatim, or derived from `--repo`.
 
-    `--repo` is the research repository — the same one `newlife start` created and the
-    one that holds `questions/`. The archive goes to `explorations/<slug>/process/` there,
+    `--repo` is the person's named research repository. The archive goes to
+    `explorations/<slug>/process/` there,
     the handoff to `questions/<slug>/origin/`; same slug on both sides, so the two never
     disagree about which exploration a question came from.
     """

exloop-0.3.0/skills/idea-lab/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: idea-lab
+description: Use when an open-ended research, mechanism, or design question has competing or underspecified explanations and the person is not ready for formal framing or execution. Not for direct factual answers, implementation, debugging, or confirmatory analysis.
+---
+
+# Idea Lab
+
+Use **Draw—Attack—Compare—Check** to turn an intuition into a small portfolio of explanations
+whose differences can be discussed and eventually tested. This is an exploratory
+reasoning pattern, not an evidence-producing or confirmatory workflow.
+
+The person owns the question, target, and consequential choices. Do not replace
+their original idea merely because another route is easier to formalize.
+
+## Fit with the exploration workflow
+
+- For a short exchange, use this pattern in conversation only.
+- **REQUIRED SUB-SKILL:** Use `exloop` when the person asks for sustained
+  exploration, a persistent map, or a handoff into a research repository.
+- When source verification, prior art, or a novelty judgment becomes material,
+  follow [the bounded evidence review](../exloop/references/evidence-review.md),
+  then return to this comparison. It does not advance the workflow.
+- Hand off to `newlife-goal` only when the person can say what observation or
+  measurement would make the answer different.
+
+“Plan the next step” means the next exploratory discriminator while this skill is
+active. It does not by itself authorize a transition into study design,
+preregistration, implementation, or intervention. Name the possible handoff and
+let the person choose it.
+
+Anything observed, computed, or read during Idea Lab is exploratory and therefore
+*seen* for any later preregistration. This skill never freezes a hypothesis, runs a
+confirmatory analysis, or promotes an explored result to confirmation.
+
+## Choose the domain profile
+
+Classify by the dominant inferential risk, not by the researcher's department.
+Read only the one profile that fits:
+
+- [formal theory](references/formal-theory.md);
+- [empirical or causal research](references/empirical-causal.md);
+- [simulation or computational research](references/simulation-computational.md);
+- [engineering or product mechanisms](references/engineering-product.md);
+- [interpretive or historical research](references/interpretive-historical.md);
+- [generic mechanism exploration](references/generic.md) when none dominates.
+
+If two profiles genuinely apply, state the boundary and use only the relevant
+checks from each. Do not duplicate the whole workflow.
+
+## Draw — make the alternatives explicit
+
+Preserve the person's idea as one candidate. Add only enough alternatives to
+expose the consequential uncertainty—usually two to four live candidates, never
+cosmetic rewrites of the same story.
+
+For each candidate, make explicit:
+
+- the claim in one sentence;
+- the mechanism chain: what changes what;
+- necessary assumptions;
+- an expected pattern if it is right;
+- a boundary or observation that would weaken it.
+
+Include a reversed mechanism, selection effect, measurement artifact, or null
+explanation when one is genuinely plausible. Do not manufacture symmetry merely
+to fill a list.
+
+## Attack — challenge before repairing
+
+Attack each candidate on its own terms. Ask for the cheapest decisive weakness:
+a counterexample, violated invariant, hidden assumption, scope boundary, rival
+mechanism, or artifact that produces the same observation.
+
+Keep the roles separate:
+
+1. state the strongest version of the candidate;
+2. attack that version;
+3. classify the damage as contradiction, unsupported premise, limited scope, or
+   unresolved;
+4. repair only if the repair yields a new consequence that was not built into it.
+
+Do not erase failed routes. Record why they failed so they are not rediscovered
+later. A repair that merely fits the motivating observation is curve-fitting, not
+progress.
+
+## Compare — seek discriminators, not a winner
+
+Compare candidates at the point where they predict different observations,
+timings, interventions, counterfactuals, or failure signatures. Prefer the
+cheapest observation that can make one route lose while another survives.
+
+Do not rank explanations as “most likely” without evidence tied to the current
+case. General plausibility, familiarity, theoretical elegance, and labels such as
+“typical amplifier” are not case evidence. If the person asks for a ranking that
+the available evidence cannot support, refuse the ranking and state the first
+observation that would change it. Do not invent numerical thresholds.
+
+Candidates need not be mutually exclusive. When one is a trigger and another an
+amplifier, represent their composition and identify evidence for each link rather
+than forcing a single winner.
+
+## Check — audit provenance and claimed novelty
+
+Maintain these statuses for material claims:
+
+| Status | Meaning |
+|---|---|
+| `user` | Supplied by the person |
+| `observed` | Directly seen in a source, code, data, or run |
+| `established` | Supported by verified prior work |
+| `inferred` | Reasoned from stated premises but not independently verified |
+| `unverified` | Plausible factual claim awaiting a source |
+| `candidate-novelty` | A potentially new combination or claim, not yet established as novel |
+
+“No source found” never means “novel.” This skill does not itself authorize web
+research, data access, repository edits, or experiments; use the authority in the
+person's request and the appropriate skill.
+
+## Run it as a loop, not a four-part lecture
+
+Advance one useful edge per conversational turn. Do not dump every candidate,
+attack, comparison, source question, study design, and preregistration plan at
+once. “Help me explore” or “plan the next step” is not a request for a full board;
+reserve that for an explicit request for a synthesis, matrix, or complete map.
+
+After identifying the first useful discriminator, stop at that boundary. Do not
+specify randomization, estimators, sample sizes, success thresholds, or a frozen
+hypothesis unless the person explicitly chooses to leave Idea Lab for formal
+framing or design.
+
+Loop back when:
+
+- an attack changes a candidate's mechanism;
+- candidates make the same observable prediction;
+- prior work collapses a supposed distinction;
+- a new observation opens a materially different route.
+
+Stop adding branches when four or five live routes are open, or when several turns
+add routes without choosing, resolving, or retiring one. Inventory instead.
+
+## Compact board for synthesis or handoff
+
+When the person asks for a synthesis, or a boundary is ready for `newlife-goal`,
+render only what has actually been developed:
+
+```markdown
+## Current question
+<question and scope>
+
+## Candidate routes
+| Route | Mechanism | Necessary assumptions | Expected pattern | Status |
+
+## Attack ledger
+| Route | Strongest attack | Damage | Repair or reason retained |
+
+## Discriminators
+| Observation or intervention | Route A predicts | Route B predicts | Seen or unobserved |
+
+## Source ledger
+| Claim | Provenance status | Source or missing check |
+
+## Open boundary
+<the one missing distinction, fact, or judgment that most changes the next step>
+```
+
+The board is a map, not a scorecard. Preserve incompatible live routes, abandoned
+routes, and unresolved provenance. End with one reachable next edge, not a verdict.
+
+## Self-check
+
+- Did the person's original idea remain visible?
+- Are the candidates mechanistically different rather than differently worded?
+- Did every surviving route face a real attack?
+- Is there at least one discriminator, or an explicit statement that none is known?
+- Are trigger and amplifier separated where relevant?
+- Are factual support, inference, and possible novelty visibly distinct?
+- Did the exploration avoid inventing a threshold or jumping into confirmation?
+- If asked to rank, was the ranking supported by current case evidence rather than
+  a generic story about what is common?

exloop-0.3.0/skills/idea-lab/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Idea Lab"
+  short_description: "Explore ideas through draw, attack, compare, check"
+  default_prompt: "Use $idea-lab to turn this intuition into competing explanations and find what would distinguish them."

exloop-0.3.0/skills/idea-lab/references/empirical-causal.md

@@ -0,0 +1,19 @@
+# Empirical and causal research profile
+
+**Draw:** population, unit, exposure or treatment, outcome construct, time order,
+estimand, and a causal graph or verbal equivalent. Keep data-generating mechanisms
+separate from measurement mechanisms.
+
+**Attack:** confounding, reverse causation, selection, attrition, interference,
+measurement non-equivalence, post-treatment conditioning, researcher degrees of
+freedom, and external-validity limits.
+
+**Compare:** observations that distinguish mechanisms—timing, negative controls,
+heterogeneous predictions, natural or randomized variation, and measurements that
+do not reuse the motivating outcome. At this stage, identify the discriminator;
+do not turn it into a full design.
+
+**Check:** label all already-viewed outcomes as seen. Do not turn an exploratory
+chart into a confirmatory direction on the same data. When the person chooses to
+move toward testing, use fresh or protected evidence under the preregistration
+workflow.

exloop-0.3.0/skills/idea-lab/references/engineering-product.md

@@ -0,0 +1,17 @@
+# Engineering and product mechanism profile
+
+**Draw:** users or components, state transitions, interfaces, timing, feedback
+loops, incentives, and observability. Separate initiating faults from propagation
+and amplification.
+
+**Attack:** race conditions, stale state, correlated clients, retries, partial
+failure, telemetry gaps, survivorship, rollout interaction, and mitigation that
+masks rather than identifies the cause.
+
+**Compare:** event ordering, trace signatures, invariants, controlled fault
+injection, canaries, and reversible changes. A safe mitigation may be worthwhile
+without proving the root cause; label those outcomes separately.
+
+**Check:** ground claims in the actual request path, logs, code, and deployed
+configuration. Do not infer probability from a generic failure pattern and do not
+invent a success threshold from intuition.

exloop-0.3.0/skills/idea-lab/references/formal-theory.md

@@ -0,0 +1,16 @@
+# Formal theory profile
+
+**Draw:** primitives, actors, information, timing, feasible actions, objectives,
+solution concept, and predicted comparative statics. Seek minimal models that
+differ in one consequential assumption.
+
+**Attack:** consistency of primitives; existence and multiplicity; hidden
+regularity assumptions; degenerate cases; sign reversals; whether the claimed
+result is encoded directly in an assumption; counterexamples at the boundary.
+
+**Compare:** theorem statements, counterexamples, comparative statics, welfare
+ranking, or a prediction that survives when a disputed assumption is relaxed.
+
+**Check:** distinguish a known theorem, an adaptation of an established model, a
+new proof route, and a candidate-new proposition. Mathematical validity and
+literature novelty are separate questions.

exloop-0.3.0/skills/idea-lab/references/generic.md

@@ -0,0 +1,14 @@
+# Generic mechanism profile
+
+Use when no specialized inferential risk dominates.
+
+**Draw:** actors or objects, state, mechanism chain, assumptions, expected change.
+
+**Attack:** missing link, reverse direction, common cause, boundary case,
+measurement artifact, or a null process that yields the same observation.
+
+**Compare:** identify a timing, intervention, counterfactual, or failure signature
+on which the candidates diverge.
+
+**Check:** separate what the person supplied, what was observed, what was inferred,
+and what remains unverified.

exloop-0.3.0/skills/idea-lab/references/interpretive-historical.md

@@ -0,0 +1,16 @@
+# Interpretive and historical research profile
+
+**Draw:** candidate interpretations, relevant actors, chronology, proposed motives
+or structures, scope, and the source base each interpretation needs.
+
+**Attack:** anachronism, source dependence, archival silence, survivorship,
+translation or category drift, hindsight, and whether the account explains only
+selected cases.
+
+**Compare:** contradictory primary sources, chronology, coverage of difficult
+cases, assumptions required, and whether one interpretation explains evidence the
+other treats as exceptional.
+
+**Check:** record source type, date, authorship, transmission, independence, and
+contestation. Do not force statistical falsifiability onto a conceptual or
+interpretive claim; demand source-sensitive constraints instead.

exloop-0.3.0/skills/idea-lab/references/simulation-computational.md

@@ -0,0 +1,16 @@
+# Simulation and computational research profile
+
+**Draw:** entities, state variables, update rules, scheduler, environment,
+stochasticity, scale, initialization, and observables. Separate properties imposed
+by construction from behavior decided by running.
+
+**Attack:** implementation artifact, scheduler dependence, initial-condition
+dependence, finite-size effect, seed instability, parameter tuning, insufficient
+power, invalid proxy, and a control that cannot actually turn red.
+
+**Compare:** analytic limits, matched controls, mechanism ablations, sensitivity
+surfaces, seed ensembles, scaling behavior, and out-of-calibration predictions.
+
+**Check:** every number must be traceable to an artifact and configuration. Runs
+inside Idea Lab are exploratory and seen; they cannot later serve as blind
+confirmation.

{exloop-0.1.0 → exloop-0.3.0}/src/exloop/__init__.py

@@ -1,11 +1,11 @@
 """exloop — human-led exploration with a persistent map.
 
 This package exists so that installing newlife (which will depend on it) puts the
-exloop skill on the machine without a trip to GitHub. It ships the skill files
+exploration skills on the machine without a trip to GitHub. It ships the skill files
 and the zero-dependency state helper the skill uses, and nothing else. newlife never
 imports exloop's code: the interface between the two is files — `handoff` writes into a
-newlife question's `origin/`. The skill master is `skills/exloop/` in the exloop
-repository; the wheel carries a byte copy under `exloop/skills/`.
+newlife question's `origin/`. The skill masters are under `skills/` in the exloop
+repository; the wheel carries byte copies under `exloop/skills/`.
 """
 
 from __future__ import annotations
@@ -16,7 +16,7 @@ __all__ = ["skills_dir"]
 
 
 def skills_dir() -> Path:
-    """The directory holding the skill masters (`exloop/SKILL.md` and friends).
+    """The directory holding the skill masters (`exloop/`, `idea-lab/`, and friends).
 
     In an installed wheel it is `exloop/skills/`, force-included at build time. In an
     editable checkout the files are the repository's own `skills/`, two levels up from this

exloop-0.1.0/.gitignore

@@ -1,20 +0,0 @@
-node_modules/
-dist/
-build/
-*.egg-info/
-*.log
-.DS_Store
-__pycache__/
-.ruff_cache/
-*.pyc
-.gstack/
-
-# Local scratch and tool caches, never versioned
-tmp/
-output/
-.workbuddy/
-AGENTS.md
-
-# hatchling copies this file into the sdist as it is, so no path under the sealed
-# exploration archive is named here; per-exploration derived caches (npz, wiki caches)
-# are listed in the local .git/info/exclude instead.

exloop-0.1.0/PKG-INFO

@@ -1,72 +0,0 @@
-Metadata-Version: 2.5
-Name: exloop
-Version: 0.1.0
-Summary: Human-led exploration with a persistent map: the exloop skill for any AI tool that reads SKILL.md, plus the zero-dependency state helper it uses.
-Author: hzshen88
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: claude-code,codex,exploration,human-in-the-loop,research-questions,skill
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Science/Research
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# exloop
-
-**Human-led exploration with a persistent map.** An AI companion that does not answer
-your question for you: it asks one or two honing questions, walks one edge at a time,
-keeps a map of where you have been, and offers the next step that is within reach. It
-ships as a skill for any AI tool that reads `SKILL.md` files — Claude Code, Codex, and
-the like.
-
-## Installing
-
-Most people get exloop by installing [newlife](https://pypi.org/project/newlife/), which
-depends on it:
-
-```bash
-python -m pip install newlife
-newlife start my-research
-```
-
-`start` installs the exloop skill, together with newlife's own, into every AI tool found
-on the machine.
-
-On its own:
-
-```bash
-python -m pip install exloop
-python -c "import exloop; print(exloop.skills_dir() / 'exloop')"
-```
-
-and copy the directory that prints into your AI tool's skills folder
-(`~/.claude/skills/`, `~/.codex/skills/`, ...).
-
-## Using it
-
-Open a folder in your AI tool and say:
-
-> Explore this with me: *your curiosity*
-
-The AI asks; you answer and decide. The map is kept silently in
-`~/.exloop/explorations/<slug>/`, one folder per exploration — the same folder whichever
-AI tool you switch to, because the identity is the slug, not the chat session. When you
-close an exploration the AI archives the record into your research repository
-(`explorations/<slug>/`). When a boundary has become a decidable question — you can say
-what measurement would make the answer different — the AI says so once, and on your yes
-hands the record to newlife (`questions/<slug>/origin/`), where the preregistration
-discipline takes over.
-
-## What is in the package
-
-- `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
-  marked, pivoted, closed — and the map as their projection) and the state model.
-- `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill
-  runs — `init`, `mark`, `pivot`, `show`, `close`, `list`, `archive`, `handoff`, and a
-  `self-test`.
-- `exloop.skills_dir()`: the one Python function, so that newlife can locate the skill
-  files. exloop has no other API and no dependencies.
-
-Requires Python 3.11 or newer.

exloop-0.1.0/README.pypi.md

@@ -1,57 +0,0 @@
-# exloop
-
-**Human-led exploration with a persistent map.** An AI companion that does not answer
-your question for you: it asks one or two honing questions, walks one edge at a time,
-keeps a map of where you have been, and offers the next step that is within reach. It
-ships as a skill for any AI tool that reads `SKILL.md` files — Claude Code, Codex, and
-the like.
-
-## Installing
-
-Most people get exloop by installing [newlife](https://pypi.org/project/newlife/), which
-depends on it:
-
-```bash
-python -m pip install newlife
-newlife start my-research
-```
-
-`start` installs the exloop skill, together with newlife's own, into every AI tool found
-on the machine.
-
-On its own:
-
-```bash
-python -m pip install exloop
-python -c "import exloop; print(exloop.skills_dir() / 'exloop')"
-```
-
-and copy the directory that prints into your AI tool's skills folder
-(`~/.claude/skills/`, `~/.codex/skills/`, ...).
-
-## Using it
-
-Open a folder in your AI tool and say:
-
-> Explore this with me: *your curiosity*
-
-The AI asks; you answer and decide. The map is kept silently in
-`~/.exloop/explorations/<slug>/`, one folder per exploration — the same folder whichever
-AI tool you switch to, because the identity is the slug, not the chat session. When you
-close an exploration the AI archives the record into your research repository
-(`explorations/<slug>/`). When a boundary has become a decidable question — you can say
-what measurement would make the answer different — the AI says so once, and on your yes
-hands the record to newlife (`questions/<slug>/origin/`), where the preregistration
-discipline takes over.
-
-## What is in the package
-
-- `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
-  marked, pivoted, closed — and the map as their projection) and the state model.
-- `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill
-  runs — `init`, `mark`, `pivot`, `show`, `close`, `list`, `archive`, `handoff`, and a
-  `self-test`.
-- `exloop.skills_dir()`: the one Python function, so that newlife can locate the skill
-  files. exloop has no other API and no dependencies.
-
-Requires Python 3.11 or newer.

exloop-0.1.0/pyproject.toml

@@ -1,44 +0,0 @@
-[project]
-name = "exloop"
-version = "0.1.0"
-description = "Human-led exploration with a persistent map: the exloop skill for any AI tool that reads SKILL.md, plus the zero-dependency state helper it uses."
-# The repository README.md is the author's own (Chinese, linking into private directories); PyPI gets its own page.
-readme = "README.pypi.md"
-license = "Apache-2.0"
-license-files = ["LICENSE"]
-requires-python = ">=3.11"
-authors = [{ name = "hzshen88" }]
-keywords = ["exploration", "research-questions", "skill", "claude-code", "codex", "human-in-the-loop"]
-classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Intended Audience :: Science/Research",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-]
-dependencies = []
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-# The master is skills/exloop/ at the repository top, the copy people read and edit; the wheel
-# carries a byte copy under exloop/skills/, located via `import exloop; exloop.skills_dir()`.
-# newlife's `skills install` uses that to install the exploration skill alongside its own,
-# without importing any exloop code.
-[tool.hatch.build.targets.wheel]
-packages = ["src/exloop"]
-
-[tool.hatch.build.targets.wheel.force-include]
-"skills/exloop" = "exloop/skills/exloop"
-
-# The sdist uses only-include, not include: include patterns are gitignore-style and unanchored,
-# so "README.md" matches every README.md in the tree — on 2026-09-06 that pulled the READMEs of
-# 13 sealed explorations, docs/science-superpowers and vendor into the sdist. only-include takes
-# exactly these paths. scripts/check_release_artifacts.py compares the built artifacts file by
-# file and must pass before anything is published.
-[tool.hatch.build.targets.sdist]
-only-include = ["src/exloop", "skills/exloop", "README.pypi.md", "LICENSE", "pyproject.toml"]
-exclude = [".gitignore"]
-
-# No [project.urls]: the source repository is private and a public reader cannot open it. Point
-# here at the clean public repository once it exists (README.md, the paragraph on going public).