Skip to content

Capstone Review Worksheet

Page Maps

graph LR
  family["Reproducible Research"]
  program["Deep Dive Snakemake"]
  section["Capstone"]
  page["Capstone Review Worksheet"]
  capstone["Capstone evidence"]

  family --> program --> section --> page
  page -.applies in.-> capstone
flowchart LR
  orient["Orient on the page map"] --> read["Read the main claim and examples"]
  read --> inspect["Inspect the related code, proof, or capstone surface"]
  inspect --> verify["Run or review the verification path"]
  verify --> apply["Apply the idea back to the module and capstone"]

Use this page when you want to review the capstone as an inherited workflow repository, not just read it as course material. The point is to leave with explicit judgments you could defend in code review, maintenance planning, or a handoff.

How to use the worksheet

Work top to bottom. For each section:

  1. answer the question in your own words
  2. name the file or saved bundle that supports the answer
  3. record one risk only if you can point to the owning boundary

If you cannot name the evidence, the judgment is still too soft.

Repository contract

Ask:

  • what the repository claims to build and publish
  • which files are public contracts and which are internal execution detail
  • whether a new maintainer could discover the supported routes without oral explanation

Best evidence:

  • capstone/Snakefile
  • capstone/Makefile
  • capstone/workflow/contracts/FILE_API.md
  • Capstone Guide

Workflow truth

Ask:

  • where the real file contracts live
  • where dynamic discovery becomes a durable artifact
  • whether any important behavior still feels hidden or nondeterministic

Best evidence:

  • capstone/workflow/rules/preprocess.smk
  • capstone/publish/v1/discovered_samples.json
  • walkthrough or tour bundle surfaces

Policy and operating context

Ask:

  • which differences across local, CI, and SLURM are operational policy
  • what would count as semantic drift rather than policy drift
  • whether a profile change could silently alter the published meaning of the workflow

Best evidence:

Publish boundary

Ask:

  • which outputs are safe for downstream trust
  • which artifacts remain internal run state or supporting evidence
  • whether the promoted contract is smaller and clearer than the whole repository

Best evidence:

  • capstone/publish/v1/
  • capstone/workflow/contracts/FILE_API.md
  • verify-report bundle surfaces

Publish review route

Use this route when the question is not merely "did the workflow run?" but "what is the stable published contract and how is it defended?"

  1. Read Capstone File Guide.
  2. Run make PROGRAM=reproducible-research/deep-dive-snakemake capstone-verify-report.
  3. Compare the report bundle with this worksheet and Proof Matrix.

A good publish review should answer:

  • which promoted files belong to the public contract
  • which proofs are about publish trust rather than workflow execution generally
  • which future change would require a versioned publish boundary change

Architecture and ownership

Ask:

  • whether the top-level Snakefile still explains the repository shape
  • whether rule files, modules, scripts, and package code each have a readable job
  • where you would place the next non-trivial change and why

Best evidence:

  • capstone/Snakefile
  • capstone/workflow/rules/
  • capstone/workflow/modules/
  • capstone/workflow/scripts/
  • capstone/src/capstone/

Incident review

Use this section when the question is about incident response, reproducibility under pressure, or workflow debugging with evidence instead of intuition.

Recommended route:

  1. Read Capstone Walkthrough.
  2. Use Proof Matrix to choose the narrowest command for the current symptom.
  3. Compare the result with Capstone Architecture Guide and the earlier sections of this worksheet if the problem spans multiple boundaries.

A good incident review should answer:

  • whether the failure is about workflow semantics, execution policy, or downstream trust
  • which command gives the most honest first evidence
  • which files should remain unchanged until stronger proof exists

Record the result

Finish with one of these judgments:

  • trust as-is
  • trust with one named follow-up boundary
  • do not trust yet because one specific proof or ownership question is unresolved

If your conclusion is longer than a short paragraph, the review probably drifted away from one bounded question.