# Deep Primer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-jcardonnet-claude-skills-deep-primer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jcardonnet](https://agentstack.voostack.com/s/jcardonnet)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jcardonnet](https://github.com/jcardonnet)
- **Source:** https://github.com/jcardonnet/claude-skills/tree/main/skills/deep-primer

## Install

```sh
agentstack add skill-jcardonnet-claude-skills-deep-primer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Deep Primer

Generate a research-grade primer for a senior practitioner moving into an adjacent domain — the
working map you'd build after reading a dozen papers, watching conference talks, and talking to
practitioners — delivered as one self-contained, depth-dialed HTML artifact.

This skill is governed by a **rule registry** (`references/rule-registry.yaml`, 61 rules). The
18 highest-leverage generation-time rules are inlined below as the **CORE**; hold them throughout.
The rest are enforced *after* generation by deterministic lints (`scripts/`), a model-verified
citation check (Phase 6), and scoped binary critics (`references/critic-prompts/`) — you needn't
recite them, but never contradict them.
Rationale and effect sizes for every rule are in `references/evidence-map.md`. Cite a rule by ID
(e.g. `R-CARD-01`) in any note you write to disk.

## The one test
A competent reader in the domain can stop at **any** depth — only the ledes, only the cards, only
the summaries, or the full prose — and come away with a coherent, correctly-scoped mental model at
that depth. Every rule serves this test.

## Parameters — resolve first
Set four parameters before anything else (`R-PARAM-01`). If the request is bare, infer from memory
and past chats (`conversation_search`, `recent_chats`); if still unknown, ask **one** compact
question. Write `parameters.yaml`.

- **home_domain** (list) — the reader's existing expertise; fills the card's anchor row, calibrates analogies and assumed vocabulary.
- **target_domain** — the primer's subject (the domain being bridged into).
- **seniority_band** — `early_career | mid_senior | staff_plus`; scales scaffolding suppression (`R-PARAM-02`, `R-EXPERT-01`). Default `mid_senior` if unknown.
- **length_budget** — drives depth allocation via the ledger-salience proxy (claim frequency / centrality), since V1 has no concept graph. Total length tracks the budget; allocate by salience rather than padding uniformly (`R-ARCH-06`), and scale the apparatus to each section's substance (`R-DEPTH-03`).
- **outputs** — which projections to render from the IR: `html` (human) and/or `llm_md` (operationally-distilled, block-id-aligned, provenance-tagged). Default `[html]`; add `llm_md` when the primer will also ground an LLM (`R-PROJ-01..06`).
- **seed_sources** — optional user-provided sources to consult ("check the work of John Doe and "): `url` / `file` / `project_ref` (direct — fetched, grounded, never dropped) and `author`/entity directives (seed a targeted brief). Treated as leads worth looking at, not gospel — still corroboration-graded and surfaced as contested where the consensus disagrees (`R-DISC-06`). `project_ref` resolves only in claude.ai.

## CORE — hold these throughout (the resident `must_core`)
1. **R-ARCH-03** Open with the thesis/answer (BLUF/SCQA), cuttable from the bottom; no throat-clearing intro.
2. **R-SCENT-01** Every heading is a complete predictive claim/question; banned generic labels: Overview, Introduction, Key Concepts, Background, Conclusion, Miscellaneous.
3. **R-CARD-01** Each section opens with an at-a-glance card that *activates prior knowledge*: lead with the home_domain analogue + 3–5 anchor concepts, then what's new vs renamed. Not a teaser/summary.  *(why: advance organizers fire only if they activate prior knowledge)*
4. **R-CARD-03** Every technique states when to reach for it **and** a specific when-to-skip.
5. **R-SUMM-01** The lede states a complete claim, not the topic.
6. **R-SUMM-03** Compression gradient: each layer is materially shorter and more abstract than the one below; a sub-sum is never longer than its source.  *(why: minimalism, d≈1.12 — compress, don't repeat)*
7. **R-SUMM-04** Each layer is self-contained; never assumes a deeper layer was read.
8. **R-MV-01** Each core concept appears in ≥3 distinct representation modes across the document (architecture / tradeoff-table / failure-taxonomy / benchmark / cost-model / code / mental-model / historical).
9. **R-PROSE-01** Given→new flow: sentences open with given/linking material and end with the new; chain subject entities across sentences; each section opening restates the prior section's terminal entity.  *(why: given→new is how prose coheres, not a style preference)*
10. **R-PROSE-02** Trade-offs as word-choice: never "X is good" — always "X buys A at the cost of B".
11. **R-EXPERT-01** No step-by-step worked examples in the primary layer above `early_career`; teach by contrastive comparison; worked examples only behind opt-in deeper layers.  *(why: expertise reversal — scaffolding that helps novices hurts experts)*
12. **R-VOCAB-01** One canonical term per concept; define only topic-specific terms-of-art; assume in-domain vocabulary per home_domain.
13. **R-RECALL-02** 3 generation (not recognition) questions per section, ≥1 forcing a cross-domain mapping, answerable from an attentive L1 read.  *(why: testing effect — generation beats recognition)*
14. **R-ART-03** Every recommendation/trade-off/superiority claim is a Toulmin block — Claim / Data / Warrant / Backing / Qualifier / Rebuttal — with the **Qualifier** (conditions/strength) and **Rebuttal** (when it fails) always present.
15. **R-EVID-01** Tag claims settled / contested / speculative; contested claims name ≥1 dissenting view; speculation never wears the grammar of fact.
16. **R-GROUND-01** Every number, citation, or effect size resolves to a source-ledger entry. **Never fabricate** a citation, statistic, or effect size; a believed-but-unsourced claim is marked "unverified", never given false precision.  *(why: the integrity floor — never traded off)*
17. **R-XREF-01** The home-domain mapping lives in the card's opening sentence, not a footnote.
18. **R-FIG-01** Every figure caption states the figure's conclusion (a claim), not a label.

## Anti-rules — never do (the `MUST_NOT` tier)
- **R-REJECT-01** No E-Prime constraint. **R-REJECT-02** Surprisal/UID is a diagnostic heuristic only, never an editing target. **R-REJECT-03** No strict-MECE quality gate. **R-REJECT-04** No content restructuring driven by an RST parse (soft signal only). **R-REJECT-05** Critic prompts ask **binary single-criterion** questions only — never "is this good/thorough?" — and use swap-and-average on any pairwise call; this is the guard against verbosity and self-preference bias in an all-Claude judge.

---

## The pipeline
Eight phases. Each declares inputs → outputs and an exit condition; the synthesizer reads its
**file artifacts** (external memory), never an in-context dump of everything, so the research phase
parallelizes later without rework. Write a `run-manifest.json` recording phase completion so a run
can resume after interruption.
**IR-first:** Phase 3 emits a canonical **document IR** (`references/artifact-schemas.md`), not HTML;
Phases 4–7 read the IR; Phase 8 renders it into the requested `outputs` (HTML and/or the distilled
LLM-MD), which share block-ids (`R-PROJ-01..06`).
**Discovery (Phase 1a):** before retrieval, a saturating cascade of parallel deep-research ensembles (`references/discovery-brief-templates.md`) augments recall, feeding leads — not evidence — into the grounding loop (`R-DISC-01..05`; deterministic engine `scripts/research/discovery.py`).
**Convergence guard:** the drafting↔structure loop is bounded by `R-CONV-01..02` — a loose escalate (re-front-load) threshold that auto-tightens to a hard `K_MAX`, and renders a `contested-structure` block when the structure won't settle (`scripts/research/convergence.py`).

### Circuit breakers (from registry `budgets`; tune in eval)
`max_retrieval_iterations: 6` · `min_sources_per_question: 2` · `min_independent_nonvendor_sources_for_perf_claim: 2` · `recall_calibration_target: 0.75` · `critic_human_divergence_recalibrate_threshold: 0.25` · `max_revise_iterations: 3` · `per_run_token_cap: TODO`. A loop that hits a cap halts and surfaces state rather than spending more.

### Phase 0 — Parameters
in: request, memory/past-chats → out: `parameters.yaml`. Exit: all four parameters resolved. (`R-PARAM-01/02`)

### Phase 1 — Research arc (single-agent, circuit-broken) — *detail below*
in: `parameters.yaml`, persistent KB (files + Mixedbread) → out: `research-plan.yaml`, `source-ledger.yaml` (+ KB upsert), `concept-map.yaml`, outline seed.
Exit: every research-plan question has ≥`min_sources_per_question` grounded claims (≥`min_independent_nonvendor` for any performance claim); coverage gaps closed or explicitly flagged. (`R-EVID-03`, `R-GROUND-04`)

### Phase 2 — Outline (lint-gated)
in: `concept-map.yaml`, `parameters.yaml` → out: `outline.yaml`.
Active: operational artifacts planned (`R-ART-01`), honest-limits section (`R-EVID-02`), multi-view coverage at outline level (`R-MV-01`), predictive headings (`R-SCENT-01`), L1 actionable (`R-DEPTH-01`).
**Scope control (broad topics):** a single artifact cannot hold an unbounded topic at depth — pick the 3–5 highest-leverage sub-areas to cover fully and treat the rest at a higher level with pointers; this is an editorial decision stated in the scope block, not collapsible-section hiding. Match the apparatus to substance — a thin section need not carry the full layer set (`R-DEPTH-03`).
Exit: outline lint passes.

### Phase 3 — Per-section drafting (the field-guide layer)
in: `outline.yaml`, `concept-map.yaml`, `source-ledger.yaml` → out: **document IR** (`document-ir.yaml`: sections→blocks with `role`/`concept`/`mode`/`claim_ids`/`provenance`, + meta). HTML is rendered later (Phase 8), not here.
Per section, in order: lede (`R-SUMM-01`) → card (`R-CARD-01/02/03`, `R-XREF-01`) → section summary ≤500w (`R-SUMM-02`) → subsections, each opening with one sub-sum → recall placeholder. Apply prose rules (`R-PROSE-*`), expertise rules (`R-EXPERT-01/02`), univocity (`R-VOCAB-01`) throughout.
Exit: per-section structural lints pass before moving to the next section.

### Phase 4 — Coherence + multi-view passes
in: draft + sidecars → out: revised draft. Checks: given-new entity grid (`R-PROSE-01`), representation modes per concept (`R-MV-01`). Exit: both clear.

### Phase 5 — Recall + figures
in: draft + `concept-map.yaml` → out: recall blocks (`R-RECALL-01/02`) and figures with complete-claim captions, one emphasis each, accessible (`R-FIG-01..05`). Exit: recall-count and figure checks clear.

### Phase 6 — Verification (citation recall / precision) — *model_verified, not a deterministic lint*
in: draft + `source-ledger.yaml` → out: `verify-report.json`. Checks: no fabrication (`R-GROUND-01`, deterministic — every marker resolves to a ledger source_id), citation recall (`R-GROUND-02`) and citation precision (`R-GROUND-03`), both **model_verified** via an entailment check (NLI / MiniCheck or a scoped Claude call) that the cited quote actually supports the claim. Source or mark-unverified any uncited factual statement. Exit: zero unresolved citations and recall/precision ≥ eval thresholds.

### Phase 7 — Critique + bounded revise loop — *detail below*
in: draft + all sidecars + reports → out: `lint-report.json`, `critic-report.json`, `revision-log.md`, revised primer.
Exit: zero MUST violations, or `max_revise_iterations` reached → surface persistent violations to the user.

### Phase 8 — Delivery (render projections from the IR)
in: validated IR → out: the requested `outputs` rendered from the IR — `primer.html` (human) and/or `primer.llm.md` (operationally distilled), sharing block-ids (`R-PROJ-02`) — plus `quality-card.md` (what passed, what was waived, known limits) + 2–3 concrete follow-up offers (an interactive drill-down on one section, a cheat-sheet / quick-reference card, an annotated bibliography). Present the artifact(s); keep the post-amble short.

---

## Phase 1 in detail — the research arc
The quality ceiling of the primer is the quality of this phase. Run it as a structured, multistep
arc, not one batch of searches. Perspective question-templates live in
`references/research-perspectives.md`.

1. **Plan into questions × perspectives.** Decompose the topic into key questions and sub-questions, each tagged with a perspective. Derive the perspectives from the primer's own structure — they are the lenses you must fill anyway: bridge-builder (home→target mapping), production practitioner (what breaks at scale), skeptic (failure modes, overclaims), historian (lineage, what was tried before), competing-school adherent (the rival approach's case), and a standards/compliance lens where relevant. Write `research-plan.yaml`.
2. **Consult the persistent KB first.** `search_store` (Mixedbread) for prior sources relevant to each question; reuse fresh hits, flag stale ones for re-fetch. Only then go to the web for gaps.
3. **Iterative, perspective-scoped retrieval.** For each question × perspective: search → fetch full pages (not snippets) → extract → identify gaps → re-query, bounded by `max_retrieval_iterations` and the coverage rule. Favor primary sources; tag every source's type (primary-paper / docs / blog / vendor) and a credibility tier.
4. **Claim-level extraction → ledger.** As you read, extract atomic claims with provenance: claim text, `source_id`, a **short** supporting quote (≤15 words) with location, source-type, recency stamp, confidence. Write `source-ledger.yaml`; upsert new sources into the KB (dedup by normalized-URL hash + embedding similarity). Keep quotes short — the primer paraphrases, never reproduces.
5. **Recency / version sweep.** Extract every named technology/library/model; search current versions and release notes; pin them; flag anything stale (`R-GROUND-04`).
6. **Conflict + coverage analysis.** Tag contradictions as contested with both sides cited; check coverage against the plan; gaps loop back to step 3 (bounded). Performance claims need ≥`min_independent_nonvendor` corroboration (`R-EVID-03`).
7. **Curate → concept map + outline seed.** Cluster claims into core concepts with canonical terms, home-domain anchors, and the representation modes each will get; emit `concept-map.yaml` and the outline seed.

## Phase 7 in detail — critique, bounded loop, block-scoped revision
- **Hard lints first** (deterministic, free of context): run `scripts/lint.py`, which loads the registry and dispatches every `hard_lint` check; plus the Phase 6 verification report.
- **Then scoped binary critics** — the **six** prompts in `references/critic-prompts/` (architecture, field-guide, coherence, expertise-calibration, evidence-grounding, figures), each reading only its slice of the registry and answering binary rubric questions against the parsed block list. Never ask a critic for holistic quality (`R-REJECT-05`). Run gating judgments ≥2× (test-retest) and flag unstable verdicts for human review; swap-and-average applies only when comparing two candidate revisions, not to pointwise verdicts.
- **Revise block-scoped.** Each violation points at a `data-block-id`; revise that block and its immediate neighbors only — never regenerate the whole document. Track which violations were fixed, which persisted, which appeared new, in `revision-log.md`.
- **Bounded.** Stop at zero MUST violations or `max_revise_iterations`; surface any persistent violations in the quality card rather than papering over them.
- **Calibration (maintenance, not per-run):** spot-check critic verdicts against the human-labeled eval set; divergence above `critic_human_divergence_recalibrate_threshold` means the rubric needs recalibration.

## Rendering (projections from the IR)
Both artifacts are rendered from the canonical IR (`R-PROJ-01`) and share block-ids (`R-PROJ-02`).
**HTML** (`render/render_html.py`): build on `assets/primer-template.html`, which provides the depth-dial shell (L1–L5 toggles),
dark/light mode, a floating font-size control, `data-block-id`/`data-concept`/`data-mode` on blocks,
and the embedded `primer-meta` JSON. Carry over the proven aesthetic: a distinctive readable font pairing (avoid Inter/Roboto/Arial);
no hard max-width on the content con

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jcardonnet](https://github.com/jcardonnet)
- **Source:** [jcardonnet/claude-skills](https://github.com/jcardonnet/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jcardonnet-claude-skills-deep-primer
- Seller: https://agentstack.voostack.com/s/jcardonnet
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.