Spec Distiller

spec-distiller

Skill 2 of the YouTube intelligence pipeline — a consumption-layer analysis. It reads the lossless artifacts produced by youtube-artifact-collector (Skill 1) and produces a Module → Feature → Requirement document. It never touches YouTube; the only input is artifact JSON, and the only coupling to Skill 1 is the artifact's schema_version (read defensively).

When to use this skill

Use it when the request is to analyze already-collected artifacts:

• "Extract the requirements from this artifact."
• "What features and business rules does this video/collection demonstrate?"
• "Build a requirements/spec document from this collection."

If the user instead wants to collect metadata/transcripts from URLs or a playlist, that is Skill 1 (youtube-artifact-collector), not this skill.

Engines

This skill ships two interchangeable engines that emit the same output shape:

• claude (default, offline) — no script runs. You (Claude) read the artifact and the external prompt/template files in-chat and produce the document. No API key required.
• openai — runs scripts/extract_requirements.py, which calls the OpenAI API. Selected with --engine openai; needs OPENAI_API_KEY (see .env.example).

The prompts and template are external and swappable — editing them changes the output for both engines without any code change.

Inputs

Either:

• a single artifact file — an artifact .json produced by Skill 1 (named after the video's title, e.g. what-is-claude-code.json), or
• a collection folder — a directory containing _manifest.json; process each member whose status is ok (in manifest order), using the manifest for module/collection context.

Claude-native engine — how to run it (default)

When asked to extract requirements with the default engine, do this in-chat:

1. Resolve the input. If given an artifact .json, use it directly. If given a collection folder, read its _manifest.json and process every member with status: ok, in order, resolving each member's file through its files.json entry rather than reconstructing the name; the manifest also gives the collection/module title.
2. Read the artifact JSON. Pull the video{} block (id, title, url, channel, description), the collection{} block (module/collection title), and the transcript.segments[] (each with its stable index, start, and verbatim text). Treat transcript text as read-only — never edit it.
3. Read the prompt files at runtime (this is what makes them swappable):
   • prompts/system_prompt.md — the analyst role, the strict output JSON contract, and the <MODULE>-<FEATURE>-<NNN> id rules.
   • prompts/extraction_prompt.md — the task instructions, the {{placeholders}} for the artifact data, and the module/action code lookup table.
4. Fill the prompt by substituting the artifact values for the placeholders ({{video_id}}, {{video_title}}, {{video_url}}, {{channel}}, {{description}}, {{collection_title}}, {{transcript}}).
5. Produce the structured document following the system-prompt contract: summary, modules[] → features[] → requirements[] (each requirement with id = <MODULE>-<FEATURE>-<NNN>, text, source_video_id, and a trace{timestamp, segment_index}), plus assumptions and open_questions. Number requirements video-locally from 001; never embed the video id in an id.
6. Render and save. Format the document using templates/requirement_doc.md and write <basename>.requirements.md plus a mirrored <basename>.requirements.json alongside the source artifact (same collection folder or _singles/), unless the user asks to print instead. <basename> is the source artifact's filename without its extension — 01-tek-tek-ogrenci-yukleme.json → 01-tek-tek-ogrenci-yukleme.requirements.md. Never rebuild the name from the video id: Skill 1 owns the naming policy, and mirroring the input keeps both engines emitting identical filenames.

OpenAI engine — how to run it (optional)

uv run skills/spec-distiller/scripts/extract_requirements.py \
  <artifact.json | collection_dir> --engine openai [flags]

It loads the same prompts/ and templates/ files, fills the placeholders, calls OpenAI requesting structured JSON output, and renders the same document shape. Configuration precedence is CLI flag > env var > built-in default.

The key is read from a .env in the working directory (then process env); copy .env.example to .env and set OPENAI_API_KEY. A missing key fails with a clear, secret-safe error.

Output

<basename>.requirements.md + <basename>.requirements.json, where <basename> mirrors the source artifact's filename (the JSON mirrors the document). The document = source header (title / url / channel / collection)

• summary + Module→Feature→Requirements (with per-requirement traces) + Assumptions + Open Questions.

Swapping the analysis

Because the prompt and template files are read at runtime, switching the analysis task (e.g. business-rule extraction, product discovery, a different doc style, or a different module/action code scheme) is done by editing prompts/extraction_prompt.md / prompts/system_prompt.md / templates/requirement_doc.md — no code change, and the change applies to both engines.