Cp Skill Ground

---
name: cp-skill-ground
description: Ground one source-side claim by retaining minimum verbatim quotes or requiring the pinned snapshot. Use when a note needs source support or retained quotes; choose this skill, not cp-skill-ingest, for quote retention.
type: types/instruction.md
user-invocable: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, Skill
context: fork
model: opus
argument-hint: "Target: <ingest path or canonical source URL>; Claim needed: <source-side proposition or question>"
---

# Ground a source-dependent claim

`$ARGUMENTS` supplies both inputs. Stop and ask if either is missing.

**Target:** exact repo-relative ingest path or canonical source URL.

**Claim needed:** source-side proposition or question. Do not include target
prose or a target-specific transfer argument.

This skill may reuse or append verbatim quotes and is the only procedure
that writes an ingest's Quotes section. It never edits the target artifact,
never changes any other part of an ingest, and never interprets a paraphrase
stored in an ingest as source support.

## Composition contract

This skill owns source resolution and retained source evidence, not target-side
interpretation. Its direct callers include `cp-skill-write`,
`cp-skill-write-multistage`, and
`assess-a-claim-bearing-artifact-against-external-literature.md`. It may invoke
`cp-skill-ingest` for a canonical URL with no ingest and may return the
conditional `re-ingest.md` route. `Target`, `Claim needed`, the three result
literals, ingest-creation authority, and Quotes ownership are shared interfaces.
Before changing one, inspect these composition siblings under the instruction
collection's edit-time rule.

## Procedure

1. Read the source collection and ingest type contracts.
2. Resolve one ingest. For a URL with no ingest, invoke `cp-skill-ingest` on the
   exact URL and use its validated result. Stop on ambiguity.
3. Read the complete `## Quotes` section. Judge the requested source-side
   proposition directly against its retained blockquote bodies. Ignore the ingest's Summary, Connections Found, Extractable Value,
   and Limitations as support.
   - If the retained quotes are sufficient, return the ingest path and
     `quotes sufficient` without mutation.
   - If they are insufficient, continue. Do not infer the answer from an ingest
     paraphrase or analysis.
4. Derive `kb/sources/.snapshots/<slug>.md` from
   `kb/sources/<slug>.ingest.md`. Do not search for a differently named
   checksum match.
   - If that file does not exist, stop and report `snapshot not available on
     this machine: <snapshot-path>`. The capture is local to the machine that
     took it (ADR 072), so a missing file is not a stale ingest: do not
     re-ingest or recapture. The operator can copy the capture from the machine
     that holds it and rerun.
   - If it exists but its exact-byte SHA-256 differs from the ingest's
     `snapshot_sha256`, or its frontmatter `source` differs from the ingest's
     canonical `source`, stop and report both checksums. The source was
     observed again or the capture drifted; route the source to re-ingest: `Read and execute the Commonplace library instruction re-ingest
     with Target: <ingest-path>.`
5. Read enough of the primary snapshot to determine the source-side
   proposition and its bounds. Stop if the source does not establish it or the
   request depends on a secondary resource.
6. Choose the smallest sound retained form:
   - If one or a few bounded excerpts let a later reviewer judge the
     proposition without missing material context, construct one or more
     adjacent quote items in this exact shape:

     ```markdown
     > <exact supporting content>
     > --- `kb/sources/.snapshots/<slug>.md` @ `sha256:<snapshot_sha256>` — <optional locator note>
     ```

     Repeat the complete block when support is non-contiguous. Line wrapping is
     not non-contiguity: verbatim matching normalizes whitespace. Copy the
     snapshot's text exactly and retain only the minimum passages needed for a
     sound check. Quote enough that the passage is unique in its source; if
     you supply a `:start-end` range after the snapshot path, the whole quote
     must occur exactly once inside it. Reuse an existing exact extract
     rather than appending it again.
   - If sound checking depends on broad or distributed context that should not
     be retained as a bounded set of quotes, do not append a substitute
     paraphrase or an oversized extract. Return `snapshot required` and tell
     the writer to include the exact marker `(snapshot required)` in the ingest
     link text. The source claim must pass `semantic/grounding-alignment` while
     the verified snapshot is present.
7. For the bounded-quotes route, append the items yourself:
   - Retain the ingest's complete incumbent bytes. Construct a candidate by
     splicing only within the `## Quotes` section, using the incumbent file's
     newline convention: when the section body is exactly
     `No source quotes have been retained yet.`, replace only that sentence;
     otherwise insert the new items after all incumbent items and before the
     next level-two heading, adding only the separator newlines valid adjacent
     items need. Preserve every incumbent item and every byte outside the
     section. Do not merge, deduplicate, reorder, or reword anything.
   - Recheck the paired paths, source identity, and checksum against the
     current bytes, write the candidate once, then run
     `commonplace-validate kb/sources/<slug>.ingest.md`. The validator resolves
     each attributed extract against the name-paired snapshot and
     fails on an absent, ambiguous, or out-of-range quote; that check, not your own reading, is
     the verification — an agent checking text it just transcribed confirms
     its own copy. Earlier grounding runs produced false extracts by silently
     repairing capture artifacts (line-break hyphenation, an inline footnote
     marker, a LaTeX arrow); quote the snapshot's bytes as they are.
   - Re-read the result and require the intended splice plus exact
     preservation of all other bytes. If any post-write check or validation
     fails, restore the retained incumbent bytes exactly, verify that
     restoration, and report failure rather than leaving an invalid or partial
     append. A `source quote` failure is about the item, not the splice: fix
     the extract against the snapshot, never rewrite the file around it.
     A `populated Quotes section conflicts` failure identifies stale prose
     outside Quotes. Restore the incumbent and report that non-quote prose must
     be repaired before grounding is retried; this skill must not repair it.
8. Return the ingest path and exactly one route: `quotes sufficient`, `quotes
   added`, or `snapshot required`. For `quotes added`, also return the appended
   quote texts. If validation warned that a populated Quotes section coexists
   with `(snapshot required)`, repeat that warning so the caller verifies that
   the marker still belongs to a claim needing broader snapshot context. For
   `snapshot required`, repeat the exact link-text marker and the requirement
   to run `semantic/grounding-alignment` before the source claim lands.

Semantic uniqueness is not required. Similar, overlapping, or disputed exact
passages are never merged, rewritten, or deleted by this procedure.