Draft an ingest report

Type: types/instruction.md

Write a faithful, reusable account of what the source contributes to the installed KB and what its evidence supports.

Use this instruction only as the delegated drafting stage of source ingest. The caller has already resolved the target, captured the source, guarded its checksum, and run connection discovery. You own the analysis and the one output report. The caller owns orchestration, final handoff checks, and user reporting.

Do not invoke cp-skill-ingest, cp-skill-connect, cp-skill-snapshot-web, or another orchestration skill. Do not spawn another agent.

Inputs

Require the caller to supply these values in the task:

  • mode: create or repair
  • snapshot_path: one Markdown source snapshot
  • connect_report_path: its completed, non-empty connect report
  • output_path: where the accepted report will be published; do not write it
  • candidate_path: the file to write, in an ignored working directory
  • snapshot_sha256: the expected lowercase SHA-256 of the exact snapshot bytes
  • retained_quotes_path: a file holding the complete Quotes section to place in the report
  • handoff_record: the handoff record the finished report is checked against
  • code_grounding_context: none or the prepared paper-with-code context
  • occasion: none or the caller's question or job that brought the source in, stated before the source was read
  • validation_failures: none in create mode; a non-empty list of exact failures in repair mode

For a fresh output, the file at retained_quotes_path holds this block:

## Quotes

No source quotes have been retained yet.

For a same-checksum refresh, it holds the incumbent Quotes block unchanged. In both cases, treat the file's content as opaque retained text. Read the handoff record only through the check in step 7; do not edit it or the Quotes file.

Stop without writing if a required value or input file is missing, unreadable, inconsistent, or invalid for the selected mode. In create mode, do not read or reuse an existing output_path or candidate_path; write the candidate only after the checksum check passes. In repair mode, read the existing candidate only after the authoritative inputs below. Use the supplied failures as a repair target, then check the whole artifact rather than assuming the listed failures are exhaustive.

The snapshot and connect report are the complete source and discovery inputs. Do not browse the web, rerun connection discovery, or run broad KB searches. Read a conditional instruction linked below when its trigger applies, and any note that instruction requires. When the installed source collection contract allows topic search tags, you may read candidate tag heads under kb/tags/ to assign optional tags; do not run broader discovery for this purpose. You may also open a durable local artifact explicitly named in the connect report only when needed to verify a connection you may keep. Never follow or cite a local snapshot link in the durable report.

Procedure

  1. Read these authoritative files in order:
  2. kb/sources/COLLECTION.md
  3. the global ingest-report type spec
  4. snapshot_path
  5. connect_report_path

The ingest-report type spec wins if it conflicts with this instruction, but it never authorizes changing the retained Quotes. If the report cannot satisfy both, stop and return that conflict.

  1. Compute SHA-256 from the exact bytes of snapshot_path. Require it to equal snapshot_sha256 before analysis. Do not hash a companion PDF, JSON, image, or extracted text file.

In repair mode, read the existing candidate_path only after this check. If it does not exist, draft it from the authoritative inputs. Treat an existing draft as a repair candidate, not as source evidence.

The retained Quotes block is authoritative retained text, not an analysis input. Do not derive it from the snapshot, connect report, or repair candidate.

  1. Analyze the source under the ingest-report contract and the installed KB's goals and local collection contracts. In the Commonplace source repository, "our" means agent-operated KB methodology. In another installed KB, it means that project's declared system, work, codebase, policy, product, or domain. The loaded type owns metadata, section contents, and occasion semantics. Derive capture metadata from the snapshot frontmatter and use the connect report as candidate discovery input. Treat its Maintenance Observations as non-actionable context. One settled connection is sufficient.

For scientific papers, use your pretrained knowledge of the NeurIPS reviewing methodology as a coherent framework for the experimental Contribution assessment (our opinion), adapted to the paper's contribution type. Interpret it through Commonplace's Popperian approach: assess progress on the problem through conjectures, criticism, comparison with rivals, and tests of their consequences. Credit explanations, error elimination, and evidence or tools that enable stronger tests; surviving criticism leaves claims open to revision. Use the learned methodology to inform the short paragraph, with the ingest contract governing its scope and uncertainty.

Choose analytical emphasis from the source. Continue analysis only when you can name an unresolved question and explain how answering it could materially change the interpretation, evidential scope, useful contribution, or recommended next action. Apply this stopping rule after satisfying the required report sections and evidence checks.

  1. For an experiment-bearing source—an intervention, benchmark, ablation, controlled study, or other empirical evaluation used as design evidence—identify the tested comparison and consequential representations, component boundaries, interfaces, or other design choices held fixed. Distinguish improvement within that decomposition from evidence comparing alternative decompositions. Attribute an ablation only to the choice it varies. Carry material consequences into Connections Found, Extractable Value, or Limitations (our opinion).

When a result materially depends on the tested decomposition, keep that qualification beside the result in Summary, Connections Found, and Extractable Value wherever it appears. Name only architectural details needed to understand the comparison or bound its reuse; an exhaustive decomposition or architectural taxonomy is not required.

  1. If the source's subject or mechanism is learning or adaptation, including a conceptual account with no empirical results, read and apply Assess learning claims during ingest. Otherwise skip this step and omit the Learning Claims (our opinion) section.

  2. Write only candidate_path under the ingest-report contract. The report will be published at output_path, so write every relative link as it must read from output_path's directory, not from the candidate's. Do not create a capture_metadata field or cite a machine-local checkout such as related-systems/.

Place the content of retained_quotes_path immediately before ## Connections Found, verbatim: the file ends with the blank line that separates the block from that heading. Preserve every character, line ending, blank line, heading, and entry. Do not interpret, normalize, merge, re-indent, or rewrite it, and do not write another Quotes section. In repair mode, replace any Quotes block in the repair candidate with the file's content rather than using the candidate's version.

When code_grounding_context is none, omit secondary_sources and the Code Grounding section. Otherwise apply its pinned commit URLs, claim classifications, source citations, and evidence boundaries. State what code was executed. Do not turn static inspection into a reproduction claim.

  1. Run the handoff check:

bash commonplace-validate {candidate_path} --handoff {handoff_record}

It validates the candidate as if it were at output_path and also requires the snapshot still to hash to snapshot_sha256, the Quotes block to equal the retained block byte for byte immediately before ## Connections Found, and the occasion and code-grounding presence to match the run. Fix only candidate_path and rerun until it prints HANDOFF CLEAN. Confirm that every Extractable Value item has an effort tag and that Recommended Next Action contains one action. If the check cannot pass without changing the Quotes block, return the failure without changing it. Do not edit the snapshot, connect report, a connected artifact, an index, a collection file, or any other library artifact.

  1. Return only the validation result and the report's single recommended next action. Do not return a second analysis or an alternative draft in conversation.

Relevant Notes: