# Analysis contract: an evidence-backed space-science watchlist

This is a small independent study inspired by HackerTube. The target use is to find up to five
unique videos about astronomy and space science from a frozen public-comment sample. The search
keyword does not establish relevance. A useful outcome may contain fewer than five videos, or no
confident choices. The sample is not guaranteed to contain examples of every stance or error type.

## Units and input meaning

`hn_comments.jsonl` preserves the selected official HN comments, a convenience plain-text version,
links, up to three immediate parents and separately retrieved root-story information. Original HTML
is the authoritative wording. Parent limits and access failures are explicit. Context from another
comment must be attributed to that comment, not silently presented as the selected author's words.

`comment_video_links.csv` has one row per distinct `(comment_id, video_id)` mention. It is not a
recommendation table. One comment can mention several videos in different ways, and one video
can appear in several comments. Normalize videos by their 11-character ID, not the complete URL.

`video_metadata.csv` reports the observed public YouTube oEmbed response. Successful metadata
provides a title and author, not a verified video description, transcript, playback result or content
quality judgment. Blank metadata must remain unavailable rather than being filled from memory.
Neither the supplied title nor the comments establish that a video can be played in a given region.

## Freeze actual model judgments before summarizing them

Create a judgment table with one row for every input comment–video pair. Retain all pairs, including
unrelated, ambiguous and unavailable ones. Save the actual judgments and evidence before choosing
the final watchlist. Suggested output is `comment_video_judgments.csv` with these fields:

| Field | Allowed values or meaning |
| --- | --- |
| `comment_id`, `video_id` | Exactly match an input pair. |
| `stance` | `recommend`, `critical`, `neutral_or_reference`, `unclear`. |
| `stance_reason` | Short explanation of how this comment treats this specific video. |
| `evidence_comment_id` | Selected comment or supplied context comment supporting the interpretation. |
| `evidence_quote` | At most 20 English words from that source comment; exact wording. May be blank if no adequate quotation exists. |
| `topic_fit` | `yes`, `no`, `unclear` for astronomy/space science. |
| `topic_evidence_basis` | `comment_context`, `metadata_title`, `both`, `insufficient`. |
| `topic_reason` | Short explanation restricted to the supplied evidence. |
| `review_note` | Missing context, ambiguity or other evidence limits; blank when none is identified. |

`recommend` means the author positively recommends, endorses or appreciatively presents that
particular video in the supplied context. `critical` means explicit unfavorable judgment about it.
`neutral_or_reference` means it is cited, compared, used as evidence or mentioned without a clear
recommendation or criticism. `unclear` retains unresolved scope, sarcasm or missing context.
Do not assume that a recommendation for one link extends to every link in the same comment.
Disagreement with a video's factual claim does not automatically mean the author dislikes the video.

Stance and topic fit are different judgments: an enthusiastic recommendation may be off topic;
a critical comment may still concern space science. Title-based topic screening is provisional and
must not be described as watching or understanding the entire video.

## Review and output

Review the frozen judgments against the supplied original wording and context. Retain a first-pass
table and any later revision separately. Log each changed pair, old/new labels, the evidence and the
reason; make zero changes if the evidence supports the first pass. This is a non-blind evidence review,
not comparison against a hidden or human gold standard. Agreement between AI passes is not human
accuracy. Do not manufacture mistakes, label changes or a success-rate headline.

Deduplicate by video ID before selecting the watchlist. Where several comments support a video,
preserve their separate stances and source links rather than turning mention counts into votes for
quality. State selection criteria and unresolved conflicts. Every chosen video needs a supported
reason and a direct source-comment link; do not invent titles, endorsements or metadata to fill five
slots. Preserve deferred or omitted candidates and their reasons in a separate table.

Recommended visual evidence includes actual sample/relationship counts, a comment-to-video
network, stance versus topic-fit counts, metadata availability, and evidence-backed selection or
revision tables. These are descriptions of this bounded sample. Avoid population confidence intervals
or whole-site accuracy claims. A flow diagram must use mutually exclusive stage counts or explicitly
state that exclusion reasons overlap. The sum of stages must reconcile with the underlying tables.

Keep quotations in the report or cards to at most 20 English words per source comment across the
report, with attribution and a link. Long source text is supplied for local analysis, not wholesale
republication in the final report. Summarize and link to it instead.

## Reproducibility boundary

A rendering script may recompute counts, normalize IDs and redraw charts from the supplied source
tables plus the saved actual judgment, review and selection tables. Semantic labels are model
outputs, not deterministic facts derivable by Python alone. The script must not substitute invented
labels, silently invoke a fresh model or claim that rereading raw comments reproduces the same AI
judgments. Record the actual execution model/version and the final semantic-input tables used.
