honest-scholar workflow. One skill, two modes —
both drive the repo to the same consumer layout (see the meta-spec
§5 and the content layout in
lifecycle §7). adopt is init plus an
inventory-and-map phase; it is the payoff for a sprawling, unsystematic research
folder — the reason this workflow exists.
The layout is git-native plain text (markdown, YAML, CSL-JSON): the repo is
the source of truth, external trackers are optional front-ends only
(ADR-0018). The plugin
ships generic scaffolding; the consumer owns all content, config, and the
experiment-backend implementation.
When to use
- First time a repository adopts the workflow — there is no
docs/research/or.honest-scholar/yet. - A repo already has research artifacts (reference PDFs, a bibliography, dataset
files or download scripts, prior results, an existing benchmark/experiment
harness) that are not yet systematically recorded — use
adopt. - Re-running is safe and additive: existing scaffolding is preserved, gaps are filled, nothing is overwritten without confirmation.
adopt, proposes the initial mapping.
Modes
Pick
adopt whenever prior research material exists; pick init for an empty
repo. Both leave the repo in the identical target layout — adopt simply arrives
with the registries already populated.
What it scaffolds
Both modes create (idempotently) the consumer layout:papers.md,
references.json, datasets.yml, triage.yml). Staged-doc scaffolding for each
paper comes from the shared templates in
resources/templates/; every hypothesis/paper/thesis
artifact carries the status frontmatter block that feeds progress.
.honest-scholar/config.yml records the four consumer bindings: the rclone remote
name for the private mirror, the literature anchors (seed works/authors the
literature capability ranks around), the experiment-backend binding
(which repo-local harness implements the run/evidence/tables/is-current
contract), and the engineering-backend binding (engineering_backend: — the
design/plan/implement delegate the pipeline skills hand engineering off to;
ADR-0023). .gitignore is updated to exclude .datasets-cache/ and
.honest-scholar/rclone.conf.
The thesis/ tree is optional — scaffold it only when the repo is a
thesis-by-publication; a plain portfolio repo omits the top level.
Adopt: backfill workflow
adopt runs the init scaffolding, then an inventory → propose → confirm →
materialize loop. The skill proposes mappings; the human confirms every
material classification — never silently guessed. The generic mapping rules
(domain-neutral; a monotonic-network repo is only one example consumer):
- Inventory. Walk the repo for research-bearing assets: reference PDFs and any digests/notes, bibliography files, dataset files and download/prep scripts, prior results and experiment specs/notes, and any existing benchmark/experiment harness.
-
Literature. Reference PDFs + digests + any existing bibliography →
literature/references.json(CSL-JSON) +triage.yml, with roles tagged (e.g. anchor / rival / prior-art / supporting). Confirm each role — the skill proposes from context, the human decides. (Example: in a monotonic-network repo, the foundational paper is the anchor and later competing constructions are rivals.) -
Datasets. Dataset files and download/prep scripts →
datasets.ymlentries, computing checksums, inferring source/license, and assigning a tier. License and tier are material classifications and must be human-confirmed — never assume redistribution is permitted. -
Retroactive hypotheses. Prior results, experiment specs, and informal
notes → retroactive hypothesis docs (
hypotheses/<YYYY-MM-DD-slug>/) withfindings.mdfilled from the recorded evidence — “a detailed record per hypothesis” applied historically. The human confirms which result maps to which hypothesis and signs off each retroactive verdict (it is still a material decision). -
Experiment backend. An existing benchmark/experiment harness → bound as
the repo’s experiment-backend implementation in
.honest-scholar/config.yml(the plugin ships only the contract; the harness stays in the consumer).
Composition
- Delegates per-item registration to the capability skills’ verbs — it does
not reimplement them. After scaffolding, populate via
literature(scout/position),dataset(init/register/fetch/verify/mirror/audit/export), and the pipeline skills (hypothesis-exploration,hypothesis-testing,paper-exploration,paper-synthesis). Inadopt, the mapping steps above call those same verbs so backfilled items enter through the normal front door. - Delegates all engineering to the bound engineering backend (via the engineering-delegation contract) — design, planning, implementation, and test authoring for the experiment-backend harness are not this skill’s job; it only binds the harness in config.
- Regenerates
dashboard.mdviaprogress dashboardonce the registries hold content — never hand-edit it.
Guardrails
- Human confirms every material classification. In
adopt, licenses/tiers and result→hypothesis mappings are material and require explicit sign-off; propose, never presume (ADR-0017, meta-spec agency principle §2.1). - Retroactive verdicts are still verdicts — each backfilled
findings.mdneeds a named human sign-off + date. - Git-native only. Do not introduce an external tracker as the source of truth; the committed files are authoritative (ADR-0018).
- Domain-neutral. Scaffold and map from what the repo actually contains; bake in no field-specific assumptions.
- Idempotent and non-destructive. Never overwrite existing content without confirmation; re-running fills gaps only.
- Do not commit as part of this skill — leave the scaffolding staged for the author to review and commit (ADR-0001 frames the plugin↔consumer boundary this respects).
Commit attribution
When you commit artifacts produced by this skill, add these git trailers — discovery + provenance (see../../resources/commit-attribution.md):