> ## Documentation Index
> Fetch the complete documentation index at: https://honest-scholar.science/llms.txt
> Use this file to discover all available pages before exploring further.

# Honest Scholar

> Research you can defend — keep your research honest, especially now that AI is in the loop.

<img src="https://mintcdn.com/honest-scholar/BjcxNeGsHKsyhHkA/docs-hero.svg?fit=max&auto=format&n=BjcxNeGsHKsyhHkA&q=85&s=221df38cf42c1eb6dfb84cdd1e3cbf48" alt="Honest Scholar" width="1600" height="420" data-path="docs-hero.svg" />

**`honest-scholar`** gives your whole *scientific* research workflow one uniform,
git-native home inside Claude Code — idea → literature → hypothesis → test →
publish-decision → paper → thesis — so you and your collaborators work the same way
and never re-derive the workflow, or its rigor, per project. Concretely, it:

* **scouts and positions the literature** over the citation graph (OpenAlex +
  Semantic Scholar) — forward/backward citations, co-citation and
  bibliographic-coupling neighbours, a CSL-JSON bib, and a decision triage sidecar;
* **runs the hypothesis → test → publish-decision lifecycle** with every result
  traced to a run-ref, refuted ideas retired (not deleted), and named human sign-off
  on each material decision;
* **keeps datasets reproducible** — a tiered registry with SHA-256 fixity, a private
  rclone mirror, datasheets, and Croissant import/export;
* **builds and checks your understanding** with a Socratic tutor-examiner
  (`defend`) so you can actually defend the work in review;
* **delegates the *engineering*** (design, plans, code) to a bound engineering
  backend, staying domain- and tool-neutral.

Because AI is in the loop, it is also built so the science stays honestly *yours*
and defensible (see [The mechanics of honesty](#the-mechanics-of-honesty)).

> **New here?** Read the docs at **[honest-scholar.science](https://honest-scholar.science/)** — start with the **[User Guide](/get-started/user-guide)**.
>
> **Status: pre-release, actively developed.** The design is complete and recorded
> (see [Design & reasoning](#design--reasoning)); the skills and their supporting
> `honest-scholar` CLI are implemented. See [`STATUS.md`](https://github.com/davorrunje/honest-scholar/blob/main/STATUS.md) for the current
> ledger.

## The mechanics of honesty

Honesty here is mechanical, not a slogan. Two principles do the load-bearing work
(both grounded in the literature — see [`resources/references/`](https://github.com/davorrunje/honest-scholar/tree/main/resources/references)):

1. **Assistants, not researchers (agency).** The skills keep the accounts, advise
   as a mentor, and discuss as a colleague — they do **not** perform independent
   research or make material scientific decisions. Every material decision (is a
   hypothesis confirmed/refuted, is a result real, is a paper worth publishing,
   what the thesis claims, is it defensible) is *yours*, recorded with a named
   sign-off. You author; the skill drafts. You cannot "run" the workflow to
   produce a paper or thesis — you drive it. **So the science is honestly *yours*.**
2. **You must understand it (understanding).** Every material claim, decision, and
   method must be understood to the standard a good mentor or reviewer expects.
   `honest-scholar` verifies *and builds* that understanding through Socratic questioning and
   teaching (the `defend` skill), and will not let work advance past a gap silently
   — including examining the *why* behind the methodology, to prevent cargo-cult
   rigor. **So "I understand my own paper" is true, not assumed.**

Around them sits the rest of the honesty kit: the **rigor kit** guards against
cargo-cult method (anti-cargo-cult), **provenance** makes evidence honest (every
number traces to a run-ref), **anti-Goodhart** keeps metrics honest (no
productivity scores to game), and **file-drawer + disclosure** discipline retires
dropped ideas rather than deleting them and discloses AI use truthfully (see
[`DISCLOSURE.md`](/disclosure)).

## The skills

A single object×action shape at **three nested levels**:

| Level                           | generate                 | resolve              |
| ------------------------------- | ------------------------ | -------------------- |
| **hypothesis** (within a paper) | `hypothesis-exploration` | `hypothesis-testing` |
| **paper** (portfolio)           | `paper-exploration`      | `paper-synthesis`    |
| **thesis** (optional top)       | `thesis` (framing)       | `thesis` (synthesis) |

Each resolve skill drives one candidate through **science-before-engineering**
staged documents, delegating the *engineering* (design, plans, code) to the bound
engineering backend via the engineering-delegation contract.

**Shared capabilities:** `literature` (scout/position over the citation graph;
CSL-JSON bib + a decision triage sidecar), `dataset` (tiered registry + private
rclone mirror + SHA-256 fixity + datasheets), and a pluggable **experiment-backend
contract**.

**Cross-cutting:** `progress` (frontmatter status + a generated, semantic
dashboard; refuted = done) and `defend` (the Socratic tutor-examiner, with
author-selectable mentor personas — never inferred from personality).

**Onboarding:** `research-init` scaffolds a fresh repo (`init`) or backfills an
existing one (`adopt`).

## Honest AI use — disclose & cite

When a paper is done you can add a truthful **AI-use disclosure** — a short,
evidence-based statement of what you and the AI each did — plus a citation to
`honest-scholar`. See [`DISCLOSURE.md`](/disclosure) for the template, how-to-cite,
and an optional badge. [`paper-synthesis`](/skills/paper-synthesis)
**proactively proposes** both at finalize (after the publish decision is signed),
drafted from your provenance record — who signed off what, which run-refs back
which results. It is opt-in and author-owned: you review, edit, adopt, or decline.

The growth angle, plainly: every published paper that carries the disclosure points
other researchers to the tool. But Honest Scholar only *supports* honest disclosure
— it does **not** certify that your research is honest, and there is no seal of
honesty. The statement says what was done and links the record; readers judge.

## Install

`honest-scholar` is a Claude Code plugin; the repo is its own marketplace.

```
/plugin marketplace add davorrunje/honest-scholar
/plugin install honest-scholar@honest-scholar
```

**Enable it for a whole project** (so collaborators get it on trust) — add to the
consuming repo's `.claude/settings.json`:

```json theme={null}
{
  "extraKnownMarketplaces": {
    "honest-scholar": { "source": { "source": "github", "repo": "davorrunje/honest-scholar" } }
  },
  "enabledPlugins": { "honest-scholar@honest-scholar": true }
}
```

To pin a fixed release, add `"ref": "v0.1.0"` inside the marketplace `source`;
omit it to track the plugin's `main`. See [`STATUS.md`](https://github.com/davorrunje/honest-scholar/blob/main/STATUS.md) for the current
state.

## Design & reasoning

The design is captured in three complementary layers:

* **Specs** — the *what*: [`docs/design/`](/design/00-meta-spec) (meta-spec + four
  sub-specs).
* **Decision log** — the *why*: [`decisions/`](/decisions/index) — MADR-style ADRs, each
  with the options considered and the **rejected alternatives and why**.
* **Reference digests** — the *evidence*: [`resources/references/`](https://github.com/davorrunje/honest-scholar/tree/main/resources/references)
  — verified primary-source digests behind each skill and principle.
* **Proposals** — [`docs/design/proposals/`](https://github.com/davorrunje/honest-scholar/tree/main/docs/design/proposals): the design
  specs for the `honest-scholar` CLI modules (now implemented) and for cross-repo
  thesis aggregation.

Also: the [User Guide](/get-started/user-guide), the commit-attribution / discovery
convention ([`resources/commit-attribution.md`](https://github.com/davorrunje/honest-scholar/blob/main/resources/commit-attribution.md)),
and the visual identity ([`docs/design/visual-identity.md`](/design/visual-identity)).

This record is intended to seed a blog post / paper explaining the skills and
their rationale — ideally written *using* `honest-scholar` itself.

## Contributing

See [CONTRIBUTING.md](https://github.com/davorrunje/honest-scholar/blob/main/CONTRIBUTING.md). `honest-scholar`'s own development uses
`superpowers`; **using** `honest-scholar` does not require it — engineering is delegated
via the [engineering contract](https://github.com/davorrunje/honest-scholar/blob/main/resources/contracts/engineering.md).

## License

[Apache-2.0](https://github.com/davorrunje/honest-scholar/blob/main/LICENSE).