digest

​

When to use

• Self-invoked. You’ve picked a paper to read — off a scout-produced reading list, a citation you’re about to add, or general background — and want your understanding of it built and checked, not just summarized at you.
• Escalation from defend --target cited-work. defend’s cited-work probe (“does ref [12] actually support this sentence?”) surfaces a gap: you can’t explain what the source says, or your citation misrepresents/overstates it. defend offers to hand off into a full digest session on that paper — deeper remediation than teaching the one sentence inline.

​

How it works

1. Scope. Resolve the paper against the literature registry (references.json) — if it isn’t there yet, resolve/enrich it first via the literature CLI, so the digest is grounded in a real registry entry + mirrored PDF (cache → mirror → source chain, SHA-256), never a bare URL or an unmirrored link.
2. Probe one load-bearing point at a time, open-ended: the problem it addresses, the method, the key result, its assumptions, its limitations, and — when you already have a hypothesis or paper this reading relates to — how it bears on your own work. (Skip the last point if there’s no bound context yet, e.g. early scouting before you’ve committed to a claim.)
3. Detect gap. Judge whether you can articulate the point — not whether your first answer was right. A gap is an observed inability to explain (“couldn’t state the method’s key assumption”), never a verdict on the paper’s correctness.
4. Teach, source-grounded, from the paper itself. Established external content → explain freely and point at the exact section, equation, or table. (Contrast a novel claim under defend, which never gets its answer key supplied — a published paper’s content isn’t that.)
5. Re-probe (possibly reframed) until you can state the point in your own words, or you explicitly park it as an unresolved gap.
6. Record (see below) and, if warranted, update the paper’s triage.yml row. On the first digest of a paper, create the digest artifact with a minimal seed frontmatter block (see Output artifact, below) before running defend record.

​

Record — evidentiary, not a pass flag

defendable-science defend record \
  --artifact docs/research/literature/digests/smith2024.md \
  --target paper-comprehension \
  --points points.json

[
  {
    "point": "assumptions",
    "source_quote": "We assume the loss is Lipschitz-continuous (Eq. 3).",
    "location": "§3, Eq. 3",
    "reader_answer": "They need the loss to not change too fast so the bound in Thm 1 holds.",
    "resolved": true
  },
  {
    "point": "limitations",
    "source_quote": "Our analysis does not cover the non-convex case.",
    "location": "§5, final paragraph",
    "reader_answer": "Not sure why non-convexity breaks it.",
    "resolved": false,
    "gap_note": "could not explain why non-convexity breaks the analysis"
  }
]

​

Output artifact

• Frontmatter: a status: block carrying understanding + last-updated. The block must be seeded before the Record step runs (not already patched by defend record). Minimal seed:
  ---
  status:
    understanding: {status: pending, unresolved: []}
    last-updated: YYYY-MM-DD
  ---
  
• Body: faithful summary; key equations/claims; assumptions; limitations; and, when applicable, an explicit “relation to my work” section.

​

Composition

• literature is the substrate: digest resolves/grounds the paper against references.json and the mirrored PDF, and writes back to triage.yml on completion.
• defend shares the engine and the record mechanism (ADR-0033); its cited-work target escalates into digest on a comprehension gap (see When to use).
• progress surfaces digested-vs-unresolved counts from docs/research/literature/digests/*.md frontmatter as an independent “literature reading” view (../progress/SKILL.md), alongside — not folded into — the hypothesis/paper/thesis roll-ups.

​

Mentor persona

​

Guardrails

• Ask, don’t grade the paper’s substance. Report observed facts (“couldn’t state the key assumption”), never “this paper is wrong” — that’s outside this skill’s authority and outside its job. A reader’s disagreement with the paper is recorded as an unresolved point, not adjudicated.
• Teach the paper freely, source-grounded. Its content is established external knowledge (unlike a novel claim under defend) — explain and quote it directly, point at the exact section/equation.
• Verified, never self-attested. understanding.status: ok only when the reader has demonstrated each load-bearing point against the probe — no “I’ve got it” shortcut (anti-Goodhart, same as defend).
• Propose/surface, never adjudicate novelty or inclusion. Whether a paper is worth citing, novel, or in-scope stays with literature position and the human’s sign-off. digest feeds that judgment; it doesn’t make it.
• Non-blocking. The cited-work escalation is stop/offer, never a hard block — the human can decline and proceed, same as defend’s guardrail semantics.

​

Commit attribution

Generated-with: defendable-science (https://github.com/davorrunje/defendable-science)
DefendableScience-Skill: digest