Skip to content

Latest commit

 

History

History
104 lines (62 loc) · 10.4 KB

concepts.md

File metadata and controls

104 lines (62 loc) · 10.4 KB

Concepts

A narrative walk through the ideas this plugin is built on. Read this once; you won't need most skill files until you actually invoke them.

The lifecycle

Research is a long process with phases that produce stable artefacts: an idea becomes a design doc; a design doc becomes a plan; a plan organises literature work, ingest, analysis, drafting, peer review, and finally a published artefact. The plugin gives each phase one skill — a checklist with discipline baked in.

brainstorming-research → writing-research-plan → literature-review ⇄ ingest-source
   → executing-research-plan → drafting-manuscript → revising-manuscript → requesting-peer-review → finishing-a-research-project

Plus four cross-cutting skills (wiki-lint, wiki-graph, semantic-wiki-review, grant-finder) that fire when context demands them rather than at a fixed phase. See phase-flow.md for the full graph including back-edges.

SOFT-GATE: discipline without authoritarianism

Earlier versions of this plugin used HARD-GATES: a skill would simply refuse to proceed unless a precondition held. That collapsed in practice — researchers ignored the gate (the model is supposed to obey the user, not block them), and once one gate was bypassed, the principle of gating eroded across the whole workflow.

v0.2 introduced SOFT-GATES instead. A SOFT-GATE has three parts:

  1. Check — verify a named precondition (e.g. "at least one synthesis page has status: stable").
  2. If unmet, prompt — the skill tells the user exactly which condition is missing and asks for a one-line reason to proceed anyway.
  3. Log and continue — the reason is appended to knowledge/_meta/gate-overrides.log (date, skill name, missed condition, reason). Work proceeds.

The audit trail does the disciplining. Override rate above 30% over the last 10 entries triggers a wiki-lint warning — overrides are meant to be the exception, not the routine.

This pattern preserves the researcher's authority while making slippage visible.

Pre-registration is methodology-aware

Pre-registered hypotheses come from quantitative psychology and medicine: state the hypothesis and the falsification criteria before looking at data, so the test is genuine. Adopted naively into humanities research, this becomes epistemically broken — hermeneutic disciplines (theology, exegesis, interpretive archaeology) are constituted by the iterative revision of understanding through engagement with sources. The hermeneutic circle is not a methodological failure.

v0.2 made pre-registration methodology-aware. Each project declares its methodology in the root CLAUDE.md frontmatter:

  • hermeneutic (default) — the plan documents research question, method sketch, expected sources. No frozen hypothesis. Hypothesis revision through new reading is legitimate and logged.
  • quantitative — full pre-registration applies (hypothesis, operationalisation, stop criterion). Deviations are logged; downstream results get marked exploratory rather than retconned.
  • mixed — pre-registration applies per sub-study. Quantitative tasks in the plan are marked pre-registered: true; hermeneutic tasks are not.

Skills like writing-research-plan and executing-research-plan read the methodology and adapt their behaviour: the plan template differs, the review mode differs (two-stage spec+quality for quantitative; single-stage synthesis review for hermeneutic).

SOT pattern: Skill is the only source of truth

A workflow has exactly one skill — the SOT. If the workflow also needs a subagent (for context isolation on a heavy task), an agent file is added; the agent never duplicates the skill checklist. Its only job is to declare:

  • which skill it implements (implements: <skill-name> in its frontmatter)
  • subagent-specific dispatch rules (no parent memory, one message, strict output format)
  • the output report template

In Claude Code the agent preloads its skill: the agent file's skills: frontmatter names the skill it implements, and Claude Code injects the full SKILL.md into the subagent's context at startup. The parent passes only the concrete inputs. On a host without skill preloading (a generic subagent type, or an agent loader without skills:) the parent embeds the SKILL.md into the prompt instead, as all versions before v0.42 did. Either way the agent file stays small and the checklist lives in one place.

This was a v0.2 change. Earlier versions had three artefact types (skill, agent, command) and the same workflow logic lived in all three — which divergence made literally inevitable. See skill-contract.md for the formal contract, including the inputs: / outputs: frontmatter.

There used to be a third artefact type — OpenCode slash-command shims (/ingest, /draft, …). v0.3 removed them: OpenCode now reads skills natively from .claude/skills/<name>/SKILL.md, and the slash shortcuts added no UX value over natural-language triggering or the skill tool.

Structural vs semantic review

Three skills look at the wiki, and they do different things:

  • wiki-lint runs scripts/lint-wiki.py — a deterministic, CI-tauglich Python script. It checks frontmatter completeness, wikilink resolution, status distribution, and (since Phase 3) the rate of SOFT-GATE overrides. Fast, mechanical, repeatable. Asks: is the wiki well-formed?
  • wiki-graph runs scripts/wiki-to-graph.py — also deterministic — and exports the wiki as a graph (graph.json / graph.graphml). It surfaces god nodes (most-connected pages), bridges (entities joining otherwise-unconnected sources), and the inference-rate of structured relations. Asks: what shape does the knowledge have? Validation is wiki-lint's job; this is structure analysis.
  • semantic-wiki-review is an LLM-driven content audit. It reads pages, builds a claim ledger, and flags contradictions, stale syntheses, unsupported claims, missing cross-references, and aggregator/suspect citations (by the rubric in source-classes.md). Slow, judgement-based, not a CI gate. Asks: are the claims sound?

Earlier versions promised semantic checks in wiki-lint. They were never implemented. v0.2 split the work so the lint script only claims what it actually does, and the LLM work lives in its own skill that's invoked manually.

Wiki is purpose-built, not a generic archive

This is the principle behind the focus-driven ingest-source skill (introduced in v0.5).

A generic RAG system indexes the full text of every document so anything can be retrieved. The result is faithful to the source but agnostic about what you need from it — and in practice, retrieval surfaces a lot of irrelevant material that the LLM then has to filter on every query.

This plugin takes the opposite stance. A source page documents what your project takes from a source under a specific focus, not a generic summary. Each ingest answers a per-source question: for the project's research question, and for the specific aspect you're working on right now, what does this source actually contribute? The skill asks for that focus (proposing the project's research question as the default) and extracts only the claims, quotes, and entities that bear on it. The raw PDF stays in the shared library (<library>/pdf/<bibkey>.pdf) as the canonical "everything"; the wiki is the curated interpretation.

When a new focus emerges — say you're working on a different chapter that draws on the same source from a different angle — you re-ingest. The skill detects the existing source page and appends a new ## Focus: … block rather than overwriting the previous one. One wiki page accretes multiple lenses over the project's life. The bibkey stays the same; later focuses just add new bullets, new quotes, new entities.

Two structural honesty conventions support this:

  • ## Boundary: what this source does NOT address (within this focus) — every focus block explicitly names what's not there. Researchers reading the page later (or downstream skills like drafting-manuscript) know exactly where the source's reach ends.
  • ## Other content in this source — one paragraph noting major topics not extracted under any current focus. A signpost to the PDF in case a future re-ingest needs them. Replaced (not appended to) on each re-ingest.

The trade-off: source pages are thinner than a full summary, and a colleague who later wants a "what does Finkelstein 2003 say overall?" view has to read the PDF or trigger a re-ingest with a broader focus. We think that's the right trade — it keeps the wiki aligned with the project rather than pretending to be a personal library.

This is also why the skill never silently overwrites an existing source page. The wiki is treated as accumulated interpretation, not a regenerable summary.

MCPs are soft-preference, not required

The plugin ships standalone. One recommended MCP (dao-paper-search-mcp) adds structurally verified citations — exactly the discipline problems the plugin's red flags talk about. Each skill that benefits from these MCPs has an "MCP Optimisation (recommended)" section that names the soft-preference: if the MCP is available, use it; otherwise stay on the documented manual path.

The plugin must never require an MCP to function. See recommended-mcps.md for setup.

What this plugin doesn't do

  • It doesn't write your manuscript for you. Drafting is collaborative; the skill enforces "every claim cites a source page, every citation resolves in BibTeX, render-check is part of drafting."
  • It doesn't replace your editor. Skills produce artefacts (wiki pages, plans, drafts); you read and revise them in your IDE.
  • It doesn't promote status: draft → status: stable. Only the user does. Agents are explicit about not self-promoting their own output.
  • It doesn't decide your methodology for you. The methodology field has a default (hermeneutic) but you set it; the plugin reads and respects what you wrote.

Where to go next