System Requirements Document for crime-interrogation

1. Introduction

crime-interrogation is a Crime Interrogation Hook Agent: a working tool for true-crime researchers, editors, and solo YouTube channels that turns a supplied case-footage video link into a professional 30–60 second YouTube hook in the exact style and structure the user requests.

The product's intent is forensic, not editorial. It takes a case-footage video link (Google Drive or another supported video link), a requested video title, and optional YouTube reference videos, then produces a hook document built only from footage that was actually accessible. Every police or suspect quotation must match the footage as closely as possible; every selected clip must carry an exact beginning-and-ending timestamp; narration must be original, human-sounding documentary English that recreates a reference's structural style without copying its wording.

The audience is the working creator: a Crime Hook Writer who repeatedly analyzes footage transcripts, selects clips, writes narration, preserves exact dialogue and timestamps, and delivers a formatted hook; and a Case Footage Owner / Submitter who holds the interrogation footage and supplies it so the hook can be produced. The product carries the emotional register of an interrogation — institutional cold, withheld information, one line of red that means "this is what was actually said" — and it never invents footage, timestamps, or quotes.

2. System Overview

The current system is a first-party web application with application-owned identity, a protected hook-writing workspace, and generated-document delivery. It accepts a case video link, a requested title, and optional reference links; accesses and analyzes the supplied footage; obtains a timestamped transcript for long videos; searches the footage for the strongest evidentiary moments; organizes a supported case timeline; selects and orders approximately four to eight clips; writes original narration; preserves exact dialogue; assigns exact timestamps; assembles the formatted hook document; runs the required quality-control checklist; and delivers either a Google Docs link or the formatted hook with manual-link instructions.

Actors are the two accepted human personas — Crime Hook Writer and Case Footage Owner / Submitter — plus typed non-persona actors: the external video source (Google Drive or another supported video link), the optional YouTube reference videos used only as structure and feature references, and the Google Drive/Docs integration used for timestamp links and document publication when available.

Ownership is explicit. The application owns the anonymous entry surface, identity establishment and returning verification, intake, transcript processing, evidence search, timeline, clip selection, narration, dialogue preservation, timestamp assignment, hook document assembly, quality check, and delivery. Google Drive/Docs owns timestamp-link creation and document publication when that integration is available; when it is not, the application delivers the formatted hook and manual-link instructions instead. The supplied case footage remains owned by its source.

Narrow exclusions: the product does not create a full-length script; it does not invent footage, timestamps, or quotes; it does not claim access to a video it cannot access; it does not copy another creator's exact narration; it does not use reference videos for anything beyond structure, pacing, tone, and clip placement; it does not add emojis, unnecessary colors, or explanations inside the final hook; and it does not claim a Google Doc or link was created unless it actually was.

2a. Product Interpretation and Delivery Boundary

The product is a document generator with a forensic spine. Its delivery boundary is the hook document itself — a title, alternating timestamped police/suspect dialogue blocks and narrator paragraphs, with the title and narration in black, spoken dialogue in red, and timestamps clickable to the exact footage moment whenever technically possible.

Access is application-owned because a hook-writing run is durable, actor-specific work: a writer must be able to resume a run, revisit a generated deliverable, and keep a commitment bound to the correct participant. First-time writers and submitters establish identity through self-service enrollment; returning operators verify before reaching protected intake, analysis, editing, quality review, or delivery work. The anonymous entry surface explains the service and its intended users before identity is established.

Two external boundaries are preserved rather than absorbed. Google Drive/Docs owns timestamp-link creation and document publication when that integration is available; when it is unavailable, the application marks [ADD GOOGLE DRIVE TIMESTAMP LINK] with the exact timestamp and provides manual-link instructions. The supplied case footage is owned by its source; when it cannot be accessed, the product reports what is missing and asks for the video file or transcript rather than proceeding.

Current scope ends at the delivered hook document. No full-length script, no adjacent case-management capability, and no invented content are in scope.

2b. Source Content Inventory

The authoritative content source is the supplied CASE VIDEO LINK (Google Drive or another supported video link). Its verified content is the case footage itself, from which the product derives a timestamped transcript and the following searchable evidentiary moments:

• strongest opening statement
• suspect denial
• police accusation
• contradictions
• evidence reveals
• surveillance/video evidence
• suspect reactions
• suspicious statements
• admissions
• lies or changing stories
• emotional reactions
• moments where detectives expose the suspect
• strongest cliffhanger moment

From that footage the product derives the case timeline fields: victim, suspect, alleged crime, date/location if documented, major evidence, interrogation situation, suspect's stated version, detectives' evidence, and the major contradiction.

The optional REFERENCE VIDEOS are a structure and feature reference only. They supply structure, pacing, narration style, clip selection, transitions, and hook construction — never wording, facts, or content.

No populated factual collection beyond the supplied footage is asserted here; the product must not invent facts that could not be verified from the footage or reliable supplied case material.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous first impression explaining the crime-interrogation hook service and its intended users; the catalogue-entry composition — a 2px red-bordered specimen frame holding the case video desaturated to greyscale with a red recording dot and a live tabular timestamp, and the case title set in Archivo 900 uppercase at clamp(56px, 11vw, 156px) flush left, allowed to break across up to three lines and never truncated.
• Primary action: RUN HOOK AGENT — one red square button flush with the grid, the only other red on the first screen.
• Supporting actions: navigate to Login; navigate to Sign Up.
• Domain entities: case video link, case title, case ID, source, clip count.
• Component responsibilities: specimen frame (paused, never auto-playing, desaturated until a clip is active); recording dot; live tabular timestamp; three metadata rows (CASE ID / SOURCE / CLIPS 04 OF 08) in 12px uppercase with grey labels and bone values under a single hairline rule; persistent 72px left rail carrying the wordmark rotated 90°, the case ID, and a vertical clip index 01–08.
• States: loading (frame and metadata resolve); empty (no case loaded — frame holds the desaturated placeholder, metadata rows show unset values); success (case entry composed); error (case video link unreachable — the frame states the footage could not be accessed and the entry offers the path to supply a file or transcript); recovery (return to intake to supply a supported link or transcript).

Login

• Information/state: returning verification for operators resuming protected hook-writing runs and managing generated deliverables.
• Primary action: verify returning identity and continue to protected work.
• Supporting actions: navigate to Sign Up; return to Landing.
• Domain entities: returning operator identity, protected run continuity.
• Component responsibilities: verification form; error surface for failed verification; link to self-service enrollment.
• States: loading (verification in progress); empty (no credentials entered); success (protected destinations become reachable); error (verification failed — the message states the failure without revealing whether an identity exists); recovery (retry, or enroll via Sign Up).

Sign Up

• Information/state: self-service enrollment for a first-time Crime Hook Writer or Case Footage Owner / Submitter.
• Primary action: establish identity and enter the protected workspace.
• Supporting actions: navigate to Login; return to Landing.
• Domain entities: new operator identity.
• Component responsibilities: enrollment form; validation surface; link to returning verification.
• States: loading (enrollment in progress); empty (no fields entered); success (identity established, protected destinations reachable); error (enrollment rejected — the message states the reason); recovery (correct the input and retry, or use Login if an identity already exists).

Intake

• Information/state: the accepted inputs that start a hook-writing run — case video link (Google Drive or supported video link), video title, and optional YouTube reference links.
• Primary action: submit the case video link, title, and optional reference links to begin the run.
• Supporting actions: add or remove optional reference links; correct the title; replace the case video link.
• Domain entities: case video link, video title, reference video links, run.
• Component responsibilities: case video link field; video title field; optional reference link list; submission control; missing-input reporting surface.
• States: loading (link resolution and run start in progress); empty (no link or title supplied — the run cannot start); success (run started and the footage is handed to transcript processing); error (the link is unsupported or the footage cannot be accessed — the surface clearly states what is missing and asks for the video file or transcript); recovery (supply a supported link or a transcript and restart the run).

Transcript

• Information/state: footage access, timestamped transcript processing, and missing-input reporting when footage cannot be accessed; for long videos the product obtains a timestamped transcript rather than manually analyzing every second.
• Primary action: obtain and review the timestamped transcript.
• Supporting actions: inspect the footage where automatic transcription is unclear; correct obvious transcription errors; mark unresolved passages [unclear].
• Domain entities: footage, timestamped transcript, transcription uncertainty.
• Component responsibilities: transcript view with timestamps; footage inspection control; transcription-correction control; [unclear] marking; missing-input report.
• States: loading (transcript being produced); empty (no transcript yet, or footage inaccessible); success (timestamped transcript available for evidence search); error (footage cannot be accessed — the surface clearly tells the user what is missing and asks for the video file or transcript); recovery (supply the file or transcript, or correct the transcription and continue).

Evidence

• Information/state: the searchable evidentiary moments found in accessible footage — strongest opening statement, suspect denial, police accusation, contradictions, evidence reveals, surveillance/video evidence, suspect reactions, suspicious statements, admissions, lies or changing stories, emotional reactions, moments where detectives expose the suspect, and the strongest cliffhanger moment. Actual spoken footage is prioritized over generic narration.
• Primary action: select the evidentiary moments that will carry the hook.
• Supporting actions: filter by moment type; inspect the source moment; discard a moment that is not supported by the footage.
• Domain entities: evidentiary moment, moment type, source timestamp, spoken footage.
• Component responsibilities: moment list with type labels; source timestamp per moment; footage inspection; selection control.
• States: loading (search running over the transcript); empty (no moments found — the surface states that the footage yielded no usable moments); success (moments available and selectable); error (search could not complete because the transcript is unavailable); recovery (return to Transcript to resolve access or transcription, then re-run the search).

Timeline

• Information/state: the supported case facts — victim, suspect, alleged crime, date/location if documented, major evidence, interrogation situation, suspect's stated version, detectives' evidence, and the major contradiction — using only information supported by the footage or reliable supplied case material, with allegations never presented as established fact.
• Primary action: confirm the supported case timeline that the hook will draw on.
• Supporting actions: mark a field as undocumented; correct a field against the footage; flag wording that would present an allegation as fact.
• Domain entities: victim, suspect, alleged crime, date/location, major evidence, interrogation situation, suspect's stated version, detectives' evidence, major contradiction.
• Component responsibilities: timeline rendered as a single ruled horizontal line with tick marks; field rows with grey labels and bone values; factual-wording guard for suspect references; undocumented-field state.
• States: loading (timeline being assembled); empty (no supported facts yet); success (timeline confirmed and available to clip selection and narration); error (a field cannot be supported by the footage — it is marked undocumented rather than filled); recovery (return to Transcript or Evidence to supply support, or leave the field undocumented).

Clips

• Information/state: approximately four to eight short clips ordered into the required hook sequence — HOOK CLIP → NARRATOR INTRO → SUSPECT DENIAL → NARRATOR TRANSITION → EVIDENCE/CONFRONTATION → SUSPECT REACTION → FINAL CLIFFHANGER — with the opening preferably containing a shocking police statement, a suspect reaction, or an evidence reveal, and no unnecessary clips.
• Primary action: select and order the clips into the hook sequence.
• Supporting actions: reorder clips; remove an unnecessary clip; inspect a clip's source moment; confirm the opening choice.
• Domain entities: clip, clip order, hook sequence position, clip thumbnail.
• Component responsibilities: clip thumbnails as 1:1 monochrome stills; sequence positions; reorder control; clip count indicator (for example CLIPS 04 OF 08); vertical clip index 01–08 in the left rail acting as a transport control.
• States: loading (candidate clips resolving); empty (no clips selected); success (four to eight clips ordered into the sequence); error (fewer than four usable clips are supported by the footage — the surface states the shortfall rather than padding the sequence); recovery (return to Evidence to widen the search, or proceed with the supported clips and state the shortfall).

Narration

• Information/state: original documentary narration in natural human YouTube-documentary English — conversational, tense, clear, concise, suspenseful, easy to understand, not robotic, not overly dramatic, no unnecessary adjectives, no AI-sounding phrases — that does not repeat information unnecessarily, does not explain the entire case, and fits the selected footage within approximately 30–60 seconds.
• Primary action: write and place the narration against the selected clips.
• Supporting actions: insert a short transition such as "But detectives already had something he didn't know about.", "That's when the story started falling apart.", "But there was one problem with his story.", or "Then detectives showed him what they had." — only when supported by the footage; trim narration to fit the duration.
• Domain entities: narration paragraph, transition, duration budget.
• Component responsibilities: narration editor rendering narration in bone (#EDEBE6); duration indicator against the 30–60 second range; transition insertion control gated on footage support.
• States: loading (narration drafting in progress); empty (no narration yet); success (narration fits the selected footage within the 30–60 second range); error (narration overruns the range or a transition is unsupported by the footage — the surface states which); recovery (trim, rewrite, or remove the unsupported transition).

Dialogue

• Information/state: police and suspect dialogue preserved exactly as spoken, matching the footage as closely as possible, never rewritten, with unresolved transcription marked [unclear].
• Primary action: confirm each dialogue block against the footage.
• Supporting actions: inspect the footage for an unclear passage; correct an obvious transcription error; mark a passage [unclear].
• Domain entities: dialogue block, speaker (police/suspect), source passage, [unclear] marker.
• Component responsibilities: dialogue editor rendering spoken dialogue in red (#E4002B); speaker attribution; footage inspection; [unclear] marking; rewrite guard that prevents altering spoken wording.
• States: loading (dialogue blocks resolving from the transcript); empty (no dialogue blocks yet); success (every block matches the footage, with unresolved passages marked [unclear]); error (a passage cannot be resolved — it is marked [unclear] rather than invented); recovery (inspect the footage again, correct an obvious error, or leave the [unclear] marker in place).

Timestamps

• Information/state: an exact beginning-and-ending timestamp for every selected clip in the format [00:07–00:09], using the actual beginning and ending time of the spoken clip.
• Primary action: assign and confirm the exact timestamp for each selected clip.
• Supporting actions: generate or copy the timestamp-specific video link when Google Drive/Docs tools are available; mark [ADD GOOGLE DRIVE TIMESTAMP LINK] with the exact timestamp when timestamp-link creation is unavailable.
• Domain entities: timestamp, timestamp-specific video link, manual-link marker.
• Component responsibilities: timestamp fields in 13px Archivo 500 tabular-nums; clickable-link control; manual-link marker; vertical clip index in the left rail where the active timecode flips to red and the specimen frame scrubs to that exact second.
• States: loading (timestamps resolving from the transcript); empty (no timestamps assigned); success (every selected clip carries an exact timestamp, clickable where tools allow); error (timestamp-link creation unavailable — the surface marks [ADD GOOGLE DRIVE TIMESTAMP LINK] and shows the exact timestamp); recovery (add the link manually using the supplied timestamp).

Hook Document

• Information/state: the assembled final document — TITLE, then alternating timestamped POLICE/SUSPECT DIALOGUE blocks and narrator paragraphs — with TITLE = BLACK, NARRATOR = BLACK, POLICE/SUSPECT ACTUAL DIALOGUE = RED, and TIMESTAMP following the supplied reference-document formatting and clickable to the exact footage moment whenever technically possible; no unnecessary colors, no emojis, no explanations inside the final hook.
• Primary action: assemble and review the formatted hook document.
• Supporting actions: reorder blocks; correct a block's color role; verify the title matches the user's requested title.
• Domain entities: title, dialogue block, narrator paragraph, timestamp, color role.
• Component responsibilities: document assembly in the required structure; color-code enforcement (dialogue blocks render red, narration blocks render bone); the three-swatch legend pinned under the document (red #E4002B = spoken dialogue, bone #EDEBE6 = narrator, grey #6E6E73 = metadata); light-mode export inversion to #F4F2ED paper with #111111 type and the same #E4002B spot.
• States: loading (document assembling); empty (no blocks yet); success (document assembled in the required structure and colors); error (a block violates the color code or the structure — the surface states which); recovery (correct the block and reassemble).

Quality Check

• Information/state: the required pre-delivery checklist — hook is 30–60 seconds; title/angle matches the user's requested title; opening is strong; narration sounds human; actual dialogue is preserved; no invented dialogue; no invented facts; every clip has an exact timestamp; every timestamp is clickable if tools allow; narrator = black; police/suspect dialogue = red; title = black; structure resembles the supplied reference; hook ends with curiosity/cliffhanger; no full-length script was created.
• Primary action: run the checklist and resolve every failed item before delivery.
• Supporting actions: return to the owning surface for a failed item; re-run the checklist after correction.
• Domain entities: checklist item, pass/fail state, owning surface.
• Component responsibilities: checklist rendered as discrete items with pass/fail state; navigation from a failed item to its owning surface.
• States: loading (checks running); empty (checklist not yet run); success (every item passes); error (one or more items fail — each failed item names its owning surface); recovery (correct the item in its owning surface and re-run the checklist).

Delivery

• Information/state: the delivered result — the Google Docs link when that integration is available, or the final hook, exact timestamps, exact dialogue, clear color instructions, and exact clickable-link instructions when it is not.
• Primary action: deliver the hook document.
• Supporting actions: when Google Docs integration is available, create the Google Doc, apply the formatting, add clickable timestamp links, and set document sharing to "Anyone with the link → Editor"; when it is not available, present the formatted hook with color instructions and manual-link instructions.
• Domain entities: Google Docs link, formatted hook, color instructions, clickable-link instructions, sharing setting.
• Component responsibilities: delivery surface; Google Docs publication control; sharing-setting control; manual-delivery fallback; truthfulness guard that prevents claiming a Google Doc or link was created unless it actually was.
• States: loading (publication in progress); empty (nothing delivered yet); success (Google Docs link available, or the formatted hook and instructions presented); error (Google Docs integration unavailable or publication failed — the surface states this plainly and falls back to the formatted hook and instructions); recovery (retry publication, or deliver the formatted hook with manual-link instructions).

3. Functional Requirements

FR-1 — Accept the run inputs. As a Crime Hook Writer, I should supply a case video link (Google Drive or a supported video link), a video title, and optional YouTube reference links so that a hook-writing run can begin. (explicit)

• Trigger/input: the writer submits the case video link, the requested video title, and any optional reference links.
• Observable result: a run is created bound to those inputs.
• Access state: protected — the writer is verified before reaching Intake.
• Failure/recovery: if the link is unsupported or the footage cannot be accessed, the surface clearly states what is missing and asks for the video file or transcript.
• Continuation: the run proceeds to footage access and transcript processing.

FR-2 — Study reference videos as structure only. As a Crime Hook Writer, when I provide reference videos, I should have their structure, pacing, narration style, clip selection, transitions, and hook construction studied so that the structural style is recreated with original wording. (explicit)

• Trigger/input: optional reference video links supplied at intake.
• Observable result: the run carries a structural model derived from the references.
• Access state: protected.
• Failure/recovery: if a reference link is unusable, the run proceeds without it and states that it was not used.
• Continuation: the structural model informs clip selection and narration.
• Constraint: reference wording is never copied; references are used only to understand structure, pacing, tone, and clip placement.

FR-3 — Access and analyze the supplied footage. As a Crime Hook Writer, I should have the supplied footage opened or processed with available tools so that the hook is built from footage that was actually accessible. (explicit)

• Trigger/input: the case video link.
• Observable result: the footage is accessible to the run, or the run reports that it is not.
• Access state: protected.
• Failure/recovery: if the video cannot be accessed, the product clearly tells the user what is missing and asks for the video file or transcript; it never pretends to have watched footage it could not access.
• Continuation: accessible footage proceeds to transcript processing.

FR-4 — Obtain a timestamped transcript for long videos. As a Crime Hook Writer, when the video is long, I should have a timestamped transcript obtained rather than having every second manually analyzed. (explicit)

• Trigger/input: accessible footage whose length makes full manual analysis unnecessary.
• Observable result: a timestamped transcript is available for search.
• Access state: protected.
• Failure/recovery: if transcription is unclear, the footage is inspected where possible and obvious transcription errors are corrected; if still uncertain, the passage is marked [unclear] instead of inventing words.
• Continuation: the transcript feeds evidence search.

FR-5 — Search the footage for the strongest evidentiary moments. As a Crime Hook Writer, I should have the footage searched for the strongest opening statement, suspect denial, police accusation, contradictions, evidence reveals, surveillance/video evidence, suspect reactions, suspicious statements, admissions, lies or changing stories, emotional reactions, moments where detectives expose the suspect, and the strongest cliffhanger moment. (explicit)

• Trigger/input: the timestamped transcript and accessible footage.
• Observable result: a set of candidate evidentiary moments, each tied to its source moment.
• Access state: protected.
• Failure/recovery: if no usable moments are found, the surface states this rather than fabricating moments.
• Continuation: candidate moments feed clip selection.
• Constraint: actual spoken footage is prioritized over generic narration.

FR-6 — Build the internal case timeline. As a Crime Hook Writer, I should have an internal case timeline identifying the victim, suspect, alleged crime, date/location if documented, major evidence, interrogation situation, suspect's stated version, detectives' evidence, and the major contradiction, using only information supported by the footage or reliable supplied case material. (explicit)

• Trigger/input: the accessible footage and its transcript.
• Observable result: a supported timeline with undocumented fields left undocumented.
• Access state: protected.
• Failure/recovery: a field that cannot be supported is marked undocumented rather than filled.
• Continuation: the timeline informs clip selection and narration.

FR-7 — Keep suspect references factual. As a Crime Hook Writer, I should have allegations never presented as established fact, using factual wording such as "suspect", "18-year-old suspect", "police accused him of...", "investigators said...", and "according to investigators...". (explicit)

• Trigger/input: any narration or timeline wording that describes the suspect or the alleged crime.
• Observable result: suspect references use factual wording; unsupported labels such as "cold-blooded killer" are avoided unless the supplied source itself establishes that status and the context clearly supports it.
• Access state: protected.
• Failure/recovery: wording that presents an allegation as fact is flagged and corrected.
• Continuation: corrected wording carries into the hook document.

FR-8 — Select approximately four to eight short clips. As a Crime Hook Writer, I should have approximately four to eight short clips selected, with the opening preferably containing a shocking police statement, a suspect reaction, or an evidence reveal. (explicit)

• Trigger/input: candidate evidentiary moments and the structural model.
• Observable result: a clip set of approximately four to eight clips with a chosen opening.
• Access state: protected.
• Failure/recovery: if fewer than four usable clips are supported by the footage, the surface states the shortfall rather than padding the set.
• Continuation: the clip set feeds sequencing.

FR-9 — Structure the hook in the required sequence. As a Crime Hook Writer, I should have the hook structured approximately as HOOK CLIP → NARRATOR INTRO → SUSPECT DENIAL → NARRATOR TRANSITION → EVIDENCE/CONFRONTATION → SUSPECT REACTION → FINAL CLIFFHANGER, without unnecessary clips. (explicit)

• Trigger/input: the selected clips.
• Observable result: an ordered hook sequence.
• Access state: protected.
• Failure/recovery: a clip that does not serve the sequence is removed rather than retained.
• Continuation: the sequence feeds narration placement.

FR-10 — Keep the total spoken hook approximately 30–60 seconds. As a Crime Hook Writer, I should have the total spoken hook kept approximately 30–60 seconds, with narration plus selected footage fitting naturally within that range. (explicit)

• Trigger/input: the ordered sequence and its narration.
• Observable result: a duration within approximately 30–60 seconds.
• Access state: protected.
• Failure/recovery: an overrun is surfaced with the offending blocks so they can be trimmed.
• Continuation: the fitted hook proceeds to document assembly.

FR-11 — Write natural human narration. As a Crime Hook Writer, I should have narration written in natural human YouTube-documentary English — conversational, tense, clear, concise, suspenseful, easy to understand, not robotic, not overly dramatic, no unnecessary adjectives, no AI-sounding phrases. (explicit)

• Trigger/input: the ordered sequence and the supported timeline.
• Observable result: original narration placed against the selected clips.
• Access state: protected.
• Failure/recovery: narration that reads as robotic, overly dramatic, or AI-sounding is revised.
• Continuation: narration proceeds to document assembly.
• Constraint: the final hook must feel like it was written by a real human crime-documentary writer, not an AI.

FR-12 — Do not repeat or over-explain. As a Crime Hook Writer, I should have information not repeated unnecessarily and the entire case not explained, because the hook's purpose is to make the viewer want to watch the interrogation. (explicit)

• Trigger/input: drafted narration.
• Observable result: narration that withholds rather than summarizes.
• Access state: protected.
• Failure/recovery: redundant or over-explanatory narration is trimmed.
• Continuation: trimmed narration proceeds to document assembly.

FR-13 — Use short transitions only when supported by the footage. As a Crime Hook Writer, I should be able to use short transitions such as "But detectives already had something he didn't know about.", "That's when the story started falling apart.", "But there was one problem with his story.", and "Then detectives showed him what they had." — only when supported by the footage. (explicit)

• Trigger/input: a transition insertion against a selected clip.
• Observable result: the transition is placed only where the footage supports it.
• Access state: protected.
• Failure/recovery: an unsupported transition is refused or removed.
• Continuation: supported transitions carry into the hook document.

FR-14 — Preserve police and suspect quotations exactly. As a Crime Hook Writer, I should have every police/suspect quotation match the footage as closely as possible, with spoken dialogue never rewritten. (explicit)

• Trigger/input: a dialogue block drawn from the transcript.
• Observable result: the block matches the footage.
• Access state: protected.
• Failure/recovery: a rewrite attempt is blocked; the block is corrected against the footage instead.
• Continuation: confirmed dialogue proceeds to document assembly.

FR-15 — Resolve unclear transcription without inventing words. As a Crime Hook Writer, when automatic transcription is unclear, I should have the footage inspected where possible, obvious transcription errors corrected, and any still-uncertain passage marked [unclear] instead of having words invented. (explicit)

• Trigger/input: an unclear transcript passage.
• Observable result: either a corrected passage or an explicit [unclear] marker.
• Access state: protected.
• Failure/recovery: if the passage cannot be resolved, the [unclear] marker remains rather than being replaced with invented words.
• Continuation: the marked passage carries into the hook document.

FR-16 — Assign an exact timestamp to every selected clip. As a Crime Hook Writer, I should have every selected clip carry an exact timestamp in the format [00:07–00:09], using the actual beginning and ending time of the spoken clip. (explicit)

• Trigger/input: a selected clip.
• Observable result: an exact beginning-and-ending timestamp bound to that clip.
• Access state: protected.
• Failure/recovery: a timestamp that cannot be established is not invented; the clip is not presented with a fabricated time.
• Continuation: the timestamp carries into the hook document.

FR-17 — Create clickable timestamp links when Google Drive/Docs tools are available. As a Crime Hook Writer, when Google Drive/Docs tools are available, I should have the video generated or opened at the correct timestamp, the timestamp-specific video link created or copied, and only the timestamp text hyperlinked in the document, so the visible document shows the timestamp rather than a long raw URL. (explicit)

• Trigger/input: a selected clip with an exact timestamp.
• Observable result: the timestamp text is a clickable link to the exact footage moment.
• Access state: protected; requires Google Drive/Docs access when that integration is used.
• Failure/recovery: if timestamp-link creation is unavailable, the surface clearly marks [ADD GOOGLE DRIVE TIMESTAMP LINK] and provides the exact timestamp so the user can add it manually.
• Continuation: linked or marked timestamps carry into the hook document.

FR-18 — Assemble the final document in the required structure. As a Crime Hook Writer, I should have the final document created with the structure TITLE, then alternating timestamped POLICE/SUSPECT DIALOGUE blocks and narrator paragraphs. (explicit)

• Trigger/input: the title, confirmed dialogue blocks, narration, and timestamps.
• Observable result: an assembled hook document in the required structure.
• Access state: protected.
• Failure/recovery: a block that breaks the structure is flagged and corrected.
• Continuation: the assembled document proceeds to quality check.

FR-19 — Apply the required formatting. As a Crime Hook Writer, I should have TITLE = BLACK, NARRATOR = BLACK, POLICE/SUSPECT ACTUAL DIALOGUE = RED, and TIMESTAMP following the supplied reference-document formatting and clickable to the exact footage moment whenever technically possible. (explicit)

• Trigger/input: the assembled document.
• Observable result: the color roles are enforced — dialogue blocks render red, narration and title render black.
• Access state: protected.
• Failure/recovery: a block that violates the color code is flagged and corrected.
• Continuation: the formatted document proceeds to quality check.

FR-20 — Keep the hook free of decoration and explanation. As a Crime Hook Writer, I should have no unnecessary colors, no emojis, and no explanations inside the final hook. (explicit)

• Trigger/input: the assembled document.
• Observable result: only the required colors appear; no emoji and no explanatory text are present inside the hook.
• Access state: protected.
• Failure/recovery: an offending element is removed.
• Continuation: the clean document proceeds to quality check.

FR-21 — Run the quality-control checklist before delivery. As a Crime Hook Writer, I should have the required checklist run before delivery: hook is 30–60 seconds; title/angle matches the user's requested title; opening is strong; narration sounds human; actual dialogue is preserved; no invented dialogue; no invented facts; every clip has an exact timestamp; every timestamp is clickable if tools allow; narrator = black; police/suspect dialogue = red; title = black; structure resembles the supplied reference; hook ends with curiosity/cliffhanger; no full-length script was created. (explicit)

• Trigger/input: the assembled and formatted document.
• Observable result: every checklist item carries a pass/fail state.
• Access state: protected.
• Failure/recovery: each failed item names its owning surface so it can be corrected and the checklist re-run.
• Continuation: a fully passing document proceeds to delivery.

FR-22 — Deliver via Google Docs when that integration is available. As a Crime Hook Writer, when Google Docs integration is available, I should have the Google Doc created, the formatting applied, clickable timestamp links added, and document sharing set to "Anyone with the link → Editor", and then be given only the Google Docs link when I ask for final submission. (explicit)

• Trigger/input: a fully passing document and a request for final submission.
• Observable result: a Google Doc with the required formatting, clickable timestamp links, and the specified sharing setting; the Google Docs link is provided.
• Access state: protected; requires Google Docs access when that integration is used.
• Failure/recovery: if publication fails, the surface states this plainly and falls back to the manual delivery path.
• Continuation: the delivered link is the run's completion.

FR-23 — Deliver the formatted hook and instructions when Google Docs integration is not available. As a Crime Hook Writer, when Google Docs integration is not available, I should be provided the final hook, exact timestamps, exact dialogue, clear color instructions, and exact clickable-link instructions. (explicit)

• Trigger/input: a fully passing document and the absence of Google Docs integration.
• Observable result: the formatted hook with its timestamps, dialogue, color instructions, and clickable-link instructions.
• Access state: protected.
• Failure/recovery: if any part cannot be produced, the surface states which part is missing rather than implying it exists.
• Continuation: the delivered package is the run's completion.

FR-24 — Never claim an uncreated document or link. As a Crime Hook Writer, I should never be told that a Google Doc or link was created unless it was actually created. (explicit)

• Trigger/input: any delivery statement.
• Observable result: delivery statements match what actually exists.
• Access state: protected.
• Failure/recovery: an inaccurate claim is corrected to state the actual delivery state.
• Continuation: the run reports its true delivery state.

FR-25 — Begin the workflow immediately when only a video link is provided. As a Crime Hook Writer, when I provide only a video link, the workflow should begin immediately. (explicit)

• Trigger/input: a case video link supplied without further instruction.
• Observable result: the run starts without waiting for additional prompting.
• Access state: protected.
• Failure/recovery: if the link cannot be accessed, the run reports what is missing and asks for the video file or transcript.
• Continuation: the run proceeds through footage access and transcript processing.

FR-26 — Establish identity on first use. As a first-time Crime Hook Writer or Case Footage Owner / Submitter, I should be able to establish my own identity through self-service enrollment so that my hook-writing runs and generated deliverables remain mine to resume and revisit. (required_inference)

• Trigger/input: first arrival at the protected workspace.
• Observable result: an identity is established and protected destinations become reachable.
• Access state: anonymous entry at Sign Up; protected state remains unavailable until identity is established.
• Failure/recovery: a rejected enrollment states the reason and allows correction or a switch to returning verification.
• Continuation: the operator enters Intake.

FR-27 — Verify returning identity before protected work. As a returning Crime Hook Writer or Case Footage Owner / Submitter, I should verify my identity before reaching protected intake, analysis, editing, quality review, or delivery work so that I resume the correct run and manage the correct deliverables. (required_inference)

• Trigger/input: a returning visit to the protected workspace.
• Observable result: protected destinations become reachable and the correct run and deliverables are available.
• Access state: anonymous entry at Login; protected state remains unavailable until verification succeeds.
• Failure/recovery: a failed verification states the failure without revealing whether an identity exists, and allows retry or enrollment.
• Continuation: the operator resumes the run or starts a new one.

FR-28 — Report inaccessible footage and request the missing input. As a Case Footage Owner / Submitter, when the supplied footage cannot be accessed, I should be clearly told what is missing and asked for the video file or transcript so that the hook is never built on footage the product could not actually access. (explicit)

• Trigger/input: a case video link that cannot be opened or processed.
• Observable result: a clear statement of what is missing and a request for the video file or transcript.
• Access state: protected.
• Failure/recovery: the run pauses rather than proceeding on inaccessible footage.
• Continuation: supplying the file or transcript resumes the run at footage access.

FR-29 — Receive the delivered hook built only from accessible footage. As a Case Footage Owner / Submitter, I should receive a hook built only from footage that was actually accessible, with any missing-file or transcript gaps reported back to me. (required_inference)

• Trigger/input: a completed run.
• Observable result: the delivered hook and a truthful report of any gaps.
• Access state: protected.
• Failure/recovery: gaps are reported rather than concealed.
• Continuation: the delivered hook is the run's completion.

FR-30 — Never create a full-length script. As a Crime Hook Writer, I should never receive a full-length script; the deliverable is the 30–60 second hook only. (explicit)

• Trigger/input: any run output.
• Observable result: the deliverable is a hook, not a full-length script.
• Access state: protected.
• Failure/recovery: output that exceeds the hook scope is trimmed back to the hook.
• Continuation: the hook proceeds to quality check and delivery.

4. User Personas

Crime Hook Writer

The Crime Hook Writer is the primary human operator of the product. They work in the register of a true-crime channel: they need forensic legibility — timestamps, quotes, sources — while producing something that has to hold a viewer for thirty to sixty seconds and make them want to watch the interrogation.

Their product context is a repeated production loop. They arrive with a case-footage video link, a requested video title, and sometimes a set of YouTube reference videos whose structure, pacing, narration style, clip selection, transitions, and hook construction they want recreated with original wording. They do not want the reference's words; they want its shape.

Their primary goal is a delivered hook document that is accurate, sourced, and structurally right: a title matching their requested angle, an opening strong enough to stop a scroll, narration that sounds like a human crime-documentary writer, dialogue preserved exactly as spoken, and an exact timestamp on every clip.

Their distinct accepted responsibilities are: supplying the run inputs; studying reference videos as structure only; accessing and analyzing the footage; obtaining a timestamped transcript for long videos; searching the footage for the strongest evidentiary moments; building the supported case timeline; keeping suspect references factual; selecting approximately four to eight clips with a strong opening; ordering them into the required hook sequence; keeping the total spoken hook within approximately 30–60 seconds; writing natural human narration; avoiding repetition and over-explanation; using short transitions only when the footage supports them; preserving police and suspect quotations exactly; resolving unclear transcription without inventing words; assigning an exact timestamp to every selected clip; creating clickable timestamp links when Google Drive/Docs tools are available; assembling the document in the required structure; applying the required color formatting; keeping the hook free of unnecessary colors, emojis, and explanations; running the quality-control checklist; and delivering via Google Docs or the manual fallback.

Their relevant inputs and decisions are the case video link, the requested title, the optional reference links, which evidentiary moments to keep, which clips make the cut and in what order, where narration sits against footage, which transitions the footage actually supports, and whether a passage is resolved or marked [unclear].

They interact with the Case Footage Owner / Submitter when footage is inaccessible or a transcript gap must be reported, and with the Google Drive/Docs integration when timestamp links and document publication are available.

Their observable success is a hook document that passes every checklist item — within 30–60 seconds, title matching the request, strong opening, human narration, preserved dialogue, no invented dialogue or facts, exact timestamps, clickable where tools allow, correct colors, reference-like structure, and a curiosity/cliffhanger ending — delivered as a Google Docs link or as the formatted hook with manual-link instructions.

What makes this role's work different is the constraint stack: they are writing for suspense while being forbidden from inventing anything. Every line of narration is original; every line of dialogue is not theirs to change.

Case Footage Owner / Submitter

The Case Footage Owner / Submitter is the person who holds the interrogation case footage on Google Drive or another supported video link. They may be the same individual as the writer or a separate collaborator supplying the material.

Their product context is custody of the source. They provide the footage link, the requested title, and any reference videos so the hook can be produced, and they are the party who must be told the truth about what the product could and could not access.

Their primary goal is a hook built only from footage that was actually accessible, with any missing-file or transcript gaps reported back to them rather than papered over.

Their distinct accepted responsibilities are: supplying the case footage link and the requested title; supplying reference videos when they want a particular structural style recreated; supplying the video file or transcript when the footage cannot be accessed; and receiving the delivered hook together with a truthful report of any gaps.

Their relevant inputs and decisions are which footage to submit, which title angle they want, which references to include, and whether to supply a file or transcript when access fails.

They interact with the Crime Hook Writer by supplying the source material and receiving the delivered hook, and with the Google Drive/Docs integration as the owner of the footage location.

Their observable success is a delivered hook that traces entirely to footage the product could actually access, with no invented footage, timestamps, or quotes anywhere in it, and with any gap stated plainly.

What makes this role's work different is that their contribution is the evidence itself. The product's central prohibition — never invent footage, never invent timestamps, never invent quotes, never claim access to a video you cannot access — exists to protect the integrity of what they supplied.

5. Core User Flows

Flow 1 — First-time writer enrolls and starts a run

1. The Crime Hook Writer arrives at Landing and reads the anonymous catalogue entry: the desaturated specimen frame, the case title, the metadata rows, and the single red RUN HOOK AGENT button.
2. They choose RUN HOOK AGENT and are routed to Sign Up, because protected state is unavailable until identity is established.
3. On Sign Up, they establish their own identity through self-service enrollment.
4. Observable result: enrollment succeeds and the protected workspace becomes reachable.
5. Failure/recovery: if enrollment is rejected, the surface states the reason; the writer corrects the input and retries, or switches to Login if an identity already exists.
6. Continuation: the writer lands on Intake.

Flow 2 — Returning writer verifies and resumes

1. The Crime Hook Writer returns to Landing and chooses to continue protected work.
2. They reach Login and verify their returning identity.
3. Observable result: verification succeeds and their existing runs and generated deliverables become available.
4. Failure/recovery: if verification fails, the message states the failure without revealing whether an identity exists; the writer retries or enrolls via Sign Up.
5. Continuation: the writer resumes the correct run or starts a new one at Intake.

Flow 3 — Writer supplies run inputs and the run begins immediately

1. On Intake, the Crime Hook Writer enters the case video link (Google Drive or a supported video link) and the requested video title.
2. They optionally add YouTube reference links whose structure, pacing, narration style, clip selection, transitions, and hook construction they want recreated with original wording.
3. They submit. Because a video link alone is sufficient, the workflow begins immediately without waiting for further prompting.
4. Observable result: a run is created and the footage is handed to transcript processing.
5. Failure/recovery: if the link is unsupported or the footage cannot be accessed, the surface clearly states what is missing and asks for the video file or transcript.
6. Continuation: the run proceeds to Transcript.

Flow 4 — Writer obtains the transcript and resolves unclear passages

1. On Transcript, the Crime Hook Writer obtains the timestamped transcript. For a long video, the product obtains the transcript rather than manually analyzing every second.
2. Where automatic transcription is unclear, the writer inspects the footage.
3. They correct obvious transcription errors.
4. If a passage is still uncertain, they mark it [unclear] rather than inventing words.
5. Observable result: a timestamped transcript with unresolved passages explicitly marked.
6. Failure/recovery: if the footage cannot be accessed at all, the surface clearly tells the writer what is missing and asks for the video file or transcript; the run pauses rather than proceeding on inaccessible footage.
7. Continuation: the transcript feeds Evidence.

Flow 5 — Writer searches the footage for evidentiary moments

1. On Evidence, the Crime Hook Writer runs the search over the accessible footage and transcript.
2. The search surfaces the strongest opening statement, suspect denial, police accusation, contradictions, evidence reveals, surveillance/video evidence, suspect reactions, suspicious statements, admissions, lies or changing stories, emotional reactions, moments where detectives expose the suspect, and the strongest cliffhanger moment.
3. Actual spoken footage is prioritized over generic narration.
4. The writer inspects candidate moments and discards any that the footage does not support.
5. Observable result: a set of candidate evidentiary moments, each tied to its source moment.
6. Failure/recovery: if no usable moments are found, the surface states this rather than fabricating moments; the writer returns to Transcript to resolve access or transcription and re-runs the search.
7. Continuation: the candidate moments feed Timeline and Clips.

Flow 6 — Writer builds and confirms the supported case timeline

1. On Timeline, the Crime Hook Writer assembles the internal case timeline: victim, suspect, alleged crime, date/location if documented, major evidence, interrogation situation, suspect's stated version, detectives' evidence, and the major contradiction.
2. Only information supported by the footage or reliable supplied case material is used.
3. The writer keeps suspect references factual — "suspect", "18-year-old suspect", "police accused him of...", "investigators said...", "according to investigators..." — and avoids unsupported labels such as "cold-blooded killer" unless the supplied source itself establishes that status and the context clearly supports it.
4. Observable result: a confirmed timeline with undocumented fields left undocumented.
5. Failure/recovery: a field that cannot be supported is marked undocumented rather than filled; the writer returns to Transcript or Evidence to supply support, or leaves it undocumented.
6. Continuation: the timeline informs Clips and Narration.

Flow 7 — Writer selects and orders the clips

1. On Clips, the Crime Hook Writer selects approximately four to eight short clips from the candidate moments.
2. They choose the opening, preferably a shocking police statement, a suspect reaction, or an evidence reveal.
3. They order the clips into the required sequence: HOOK CLIP → NARRATOR INTRO → SUSPECT DENIAL → NARRATOR TRANSITION → EVIDENCE/CONFRONTATION → SUSPECT REACTION → FINAL CLIFFHANGER.
4. They remove any clip that does not serve the sequence.
5. Observable result: four to eight clips ordered into the hook sequence, with the clip count shown (for example CLIPS 04 OF 08).
6. Failure/recovery: if fewer than four usable clips are supported by the footage, the surface states the shortfall rather than padding the sequence; the writer returns to Evidence to widen the search or proceeds with the supported clips and states the shortfall.
7. Continuation: the ordered sequence feeds Narration and Dialogue.

Flow 8 — Writer writes narration that fits the footage

1. On Narration, the Crime Hook Writer writes original narration in natural human YouTube-documentary English: conversational, tense, clear, concise, suspenseful, easy to understand, not robotic, not overly dramatic, no unnecessary adjectives, no AI-sounding phrases.
2. They place each narration paragraph against its clip, keeping the total spoken hook approximately 30–60 seconds with narration plus selected footage fitting naturally within that range.
3. They avoid repeating information unnecessarily and do not explain the entire case, because the hook's purpose is to make the viewer want to watch the interrogation.
4. Where the footage supports it, they insert a short transition such as "But detectives already had something he didn't know about.", "That's when the story started falling apart.", "But there was one problem with his story.", or "Then detectives showed him what they had."
5. Observable result: narration that fits the selected footage within the 30–60 second range.
6. Failure/recovery: if narration overruns the range, the duration indicator names the offending blocks and the writer trims them; if a transition is unsupported by the footage, it is refused or removed.
7. Continuation: the fitted narration feeds Hook Document.

Flow 9 — Writer preserves dialogue exactly

1. On Dialogue, the Crime Hook Writer confirms each police and suspect dialogue block against the footage.
2. Every quotation must match the footage as closely as possible; spoken dialogue is never rewritten.
3. Where a passage is unclear, they inspect the footage, correct an obvious transcription error, or mark the passage [unclear].
4. Observable result: every dialogue block matches the footage, with unresolved passages explicitly marked [unclear].
5. Failure/recovery: a rewrite attempt is blocked; a passage that cannot be resolved keeps its [unclear] marker rather than receiving invented words.
6. Continuation: confirmed dialogue feeds Timestamps and Hook Document.

Flow 10 — Writer assigns exact timestamps and creates clickable links

1. On Timestamps, the Crime Hook Writer assigns each selected clip an exact beginning-and-ending timestamp in the format [00:07–00:09], using the actual beginning and ending time of the spoken clip.
2. When Google Drive/Docs tools are available, they generate or open the video at the correct timestamp, create or copy the timestamp-specific video link, and hyperlink only the timestamp text so the visible document shows the timestamp rather than a long raw URL.
3. Observable result: every selected clip carries an exact timestamp, clickable to the exact footage moment where tools allow.
4. Failure/recovery: if timestamp-link creation is unavailable, the surface clearly marks [ADD GOOGLE DRIVE TIMESTAMP LINK] and provides the exact timestamp so the writer can add it manually. A timestamp that cannot be established is never invented.
5. Continuation: the timestamps feed Hook Document.

Flow 11 — Writer assembles the formatted hook document

1. On Hook Document, the Crime Hook Writer assembles the final document in the required structure: TITLE, then alternating timestamped POLICE/SUSPECT DIALOGUE blocks and narrator paragraphs.
2. The formatting is enforced: TITLE = BLACK, NARRATOR = BLACK, POLICE/SUSPECT ACTUAL DIALOGUE = RED, and TIMESTAMP follows the supplied reference-document formatting and is clickable to the exact footage moment whenever technically possible.
3. No unnecessary colors, no emojis, and no explanations appear inside the final hook.
4. Observable result: an assembled document in the required structure with the color code enforced — dialogue blocks render red, narration and title render black.
5. Failure/recovery: a block that breaks the structure or the color code is flagged and corrected, then the document is reassembled.
6. Continuation: the assembled document feeds Quality Check.

Flow 12 — Writer runs the quality-control checklist

1. On Quality Check, the Crime Hook Writer runs the required checklist: hook is 30–60 seconds; title/angle matches the user's requested title; opening is strong; narration sounds human; actual dialogue is preserved; no invented dialogue; no invented facts; every clip has an exact timestamp; every timestamp is clickable if tools allow; narrator = black; police/suspect dialogue = red; title = black; structure resembles the supplied reference; hook ends with curiosity/cliffhanger; no full-length script was created.
2. Observable result: every checklist item carries a pass/fail state.
3. Failure/recovery: each failed item names its owning surface; the writer corrects the item there and re-runs the checklist.
4. Continuation: a fully passing document feeds Delivery.

Flow 13 — Writer delivers via Google Docs

1. On Delivery, with Google Docs integration available, the Crime Hook Writer requests final submission.
2. The product creates the Google Doc, applies the formatting, adds clickable timestamp links, and sets document sharing to "Anyone with the link → Editor".
3. Observable result: the Google Docs link is provided, and only that link is provided when the writer asks for final submission.
4. Failure/recovery: if publication fails, the surface states this plainly and falls back to the manual delivery path.
5. Continuation: the delivered link is the run's completion.

Flow 14 — Writer delivers without Google Docs integration

1. On Delivery, with Google Docs integration unavailable, the Crime Hook Writer requests final submission.
2. The product provides the final hook, exact timestamps, exact dialogue, clear color instructions, and exact clickable-link instructions.
3. Observable result: the formatted hook package with its timestamps, dialogue, color instructions, and clickable-link instructions.
4. Failure/recovery: if any part cannot be produced, the surface states which part is missing rather than implying it exists.
5. Continuation: the delivered package is the run's completion.

Flow 15 — Submitter supplies footage and receives a truthful result

1. The Case Footage Owner / Submitter supplies the case footage link and the requested title, and optionally the reference videos, through Intake.
2. If the footage cannot be accessed, the product clearly tells them what is missing and asks for the video file or transcript.
3. They supply the video file or transcript, and the run resumes at Transcript.
4. Observable result: the run proceeds on footage that is actually accessible.
5. Continuation: the run completes and the submitter receives the delivered hook through Delivery, built only from footage that was actually accessible, with any missing-file or transcript gaps reported back to them.
6. Failure/recovery: gaps are reported rather than concealed; no footage, timestamp, or quote is ever invented to fill them.

6. Visuals Colors and Theme

Muse and headline: Peter Saville — Austere evidence archive: one hot red signal on cold monochrome. The interface reads like a record sleeve or an evidence index, not a SaaS dashboard. The monochrome ground is the "do not invent" rule made visual; the red is a spot-colour code, not decoration.

Mode: dark mode is primary. The exported hook sheet inverts to light mode with the red held identical so the colour code never breaks.

Colour tokens — dark mode (primary):

Colour tokens — light mode (exported hook sheet):

Colour discipline: 80% near-black ground (#0B0B0C) and panel (#141517). Text is bone white #EDEBE6, never pure #FFF. #E4002B is a spot colour with a job: it marks ONLY spoken police/suspect dialogue, the live recording dot, the single active timestamp, and the primary action. Nothing else on the page may be red. #6E6E73 carries metadata, labels, and inactive timestamps. No blue or indigo anywhere — no #0057FF, #2563EB, #4F46E5, and no "link blue" for timestamps.

Typography:

• Headings: Archivo at 800–900 weight, uppercase, tracking +0.08em for the wordmark and section labels; tracking -0.02em for the oversized case title. Never italic, never a second display face.
• Body: Spectral.
• Scale: 1.333 modular.
• Case title: clamp(56px, 11vw, 156px).
• Section labels: 12px / 0.14em tracking, uppercase.
• Narration body: 18px / 1.7 Spectral regular.
• Dialogue: 20px Archivo 600.
• Timestamps: 13px Archivo 500, tabular-nums.
• Caption/meta: 11px.
• Small caps for metadata.

Shape language: hard edges everywhere — 0px radius on every surface, panel, and button. Structure comes from 1px hairlines in #26272A and full-bleed horizontal rules, never from cards or shadows. The one exception is the specimen frame around the case video: a 2px #E4002B border, the only rounded-adjacent gesture, and it stays square. No pills, no blobs, no soft shadows.

Layout: a strict 12-column grid with a persistent left rail (72px) carrying the wordmark rotated 90°, the case ID, and a vertical clip index 01–08. The main column runs an asymmetric 7/5 split: footage/specimen left, hook document right. Sections are separated by numbered rules — 01 CASE, 02 TIMELINE, 03 CLIPS, 04 HOOK, 05 EXPORT — so the page reads like a catalogue raisonné. At 375px the rail collapses to a 44px top strip, the 7/5 split stacks, and every section label stays whole and wraps rather than truncating.

Imagery: no stock photography, no illustration, no 3D. Imagery is the evidence itself: the case video in a bordered specimen frame, monochrome-desaturated until a clip is active, then full colour inside the red frame. Supporting graphics are diagrams — a horizontal case timeline as a single ruled line with tick marks, clip thumbnails as 1:1 monochrome stills, and a colour-code legend that is literally three swatches (red = spoken dialogue, bone = narration, grey = metadata). Found imagery only from the supplied footage.

Avoid: any blue or indigo; rounded cards, pill buttons, soft drop shadows, glassmorphism, gradient blobs, or a grid of identical hover-lift cards; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for any heading or body text; emoji, decorative icons, or any red used for something other than spoken dialogue, the recording dot, the active timestamp, and the primary action; tabloid or thriller-poster treatment — no drips, no distressed textures, no "KILLER" display type, no sensationalised labels; animating or auto-playing the case footage; truncating the case title, timestamps, clip labels, or dialogue at any viewport; a centred hero stack with a subheadline and a button.

Readable-content rule: headlines, wordmarks, labels, numbers, item images, cards, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Crops, bleeds, and off-edge placement are for decoration only. Moving and scrollable content may cross the viewport or container edge by design, judged by whether it actually moves and whether every item becomes fully readable as it passes; with prefers-reduced-motion it stops and shows whole items.

7. Signature Design Concept

The catalogue entry as first screen. The public entry is not a SaaS hero; it is a record-sleeve catalogue entry for a single case.

Left: a specimen frame with a 2px #E4002B border holding the case video, desaturated to greyscale, with a red recording dot and a live tabular timestamp in the corner. The frame is paused and never auto-plays; it is the only place on the page where colour is permitted to enter, and only when a clip is active.

Right: the case title set in Archivo 900 uppercase at clamp(56px, 11vw, 156px), flush left, allowed to break across up to three lines and span the full column width — the dominant element on the page. Below it, a single hairline rule, then three metadata rows (CASE ID / SOURCE / CLIPS 04 OF 08) in 12px uppercase with grey labels and bone values.

One red button, square, flush with the grid: RUN HOOK AGENT. No subheadline, no gradient, no centred stack, no floating cards. The only colour on the entire first screen is the red frame, the red dot, and the red button.

The signature moves carry through the whole product: the numbered-rule section system (03 — CLIPS, number in red, word in bone) so the page scans like a record sleeve tracklist; the dialogue/narration colour code rendered as an actual UI legend of three swatches pinned under the hook document, with the editor enforcing it — anything typed into a dialogue block renders red, anything in a narration block renders bone; timestamps as a vertical clip index 01–08 in the left rail, each a 13px tabular-numeral timecode, where the active one flips to red and the specimen frame scrubs to that exact second, making the rail a physical transport control rather than a list; the case title as a full-column oversized Archivo 900 headline that breaks across up to three lines and is never truncated, wrapping to five lines at 56px at 375px and staying entirely inside the viewport; and the monochrome specimen frame that only regains colour inside the red border when a clip is active, so the page's single colour event is always a piece of evidence being opened.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the case video inside the 2px red-bordered specimen frame, desaturated to greyscale, with the red recording dot and the live tabular timestamp in the corner.
• Input → transformation → outcome thesis: the writer selects a clip from the vertical clip index in the left rail; the specimen frame scrubs to that exact second and the footage regains full colour inside the red border; the outcome is that a piece of evidence has been opened, and the page's single colour event has occurred.
• Motion vocabulary: very little, precise. One slow 240ms crossfade when a clip is selected. The specimen frame's red border pulses to 60% opacity on a 2s loop only while a timestamp is playing. Timestamps underline-in at 120ms on hover. No parallax, no kinetic type, no bounce. Scroll is instant state change.
• Composed first frame: the desaturated specimen frame at rest with the red dot and live timestamp, the oversized case title breaking across the column, the hairline rule, the three metadata rows, and the single red RUN HOOK AGENT button — the only colour on the screen being the red frame, the red dot, and the red button.
• Reduced-motion state: with prefers-reduced-motion the pulse stops and the border sits at full opacity; the crossfade and underline-in resolve instantly; the specimen frame remains paused until the user selects a clip.

9. Non-Functional Requirements

NFR-1 — No invented content. The product must never invent footage, timestamps, or quotes, and must never claim access to a video it cannot access. (explicit)

• Rationale: these are the product's central integrity constraints; the deliverable is evidence-backed by definition.

NFR-2 — No copied narration. The product must never copy another creator's exact narration, and must not copy reference videos' wording; reference videos are used only to understand structure, pacing, tone, and clip placement, with the structural style recreated using original wording. (explicit)

• Rationale: the reference videos are a structure and feature reference, not a content source.

NFR-3 — Dialogue fidelity. Spoken dialogue must not be rewritten; every police/suspect quotation must match the footage as closely as possible, and unresolved transcription must be marked [unclear] rather than filled with invented words. (explicit)

• Rationale: the red dialogue is the product's evidentiary claim; altering it would falsify the record.

NFR-4 — Factual framing. Allegations must not be presented as established fact; suspect references must use factual wording, and unsupported labels such as "cold-blooded killer" must be avoided unless the supplied source itself establishes that status and the context clearly supports it. (explicit)

• Rationale: the product handles real cases and real people.

NFR-5 — Human-sounding narration. The final hook must feel like it was written by a real human crime-documentary writer, not an AI. (explicit)

• Rationale: stated acceptance criterion for the deliverable.

NFR-6 — Duration discipline. The total spoken hook must stay approximately 30–60 seconds, with narration plus selected footage fitting naturally within that range. (explicit)

• Rationale: the hook's format requirement.

NFR-7 — Clip economy. Approximately four to eight short clips must be used, with no unnecessary clips, and the hook must not repeat information unnecessarily or explain the entire case. (explicit)

• Rationale: the hook's purpose is to make the viewer want to watch the interrogation.

NFR-8 — Timestamp precision. Every selected clip must carry an exact timestamp in the format [00:07–00:09] using the actual beginning and ending time of the spoken clip. (explicit)

• Rationale: timestamps are the product's traceability mechanism.

NFR-9 — Link truthfulness. Timestamps must be clickable to the exact footage moment whenever technically possible; when timestamp-link creation is unavailable, the product must clearly mark [ADD GOOGLE DRIVE TIMESTAMP LINK] and provide the exact timestamp for manual addition. (explicit)

• Rationale: the visible document must show the timestamp, not a long raw URL, and must never imply a link that does not exist.

NFR-10 — Delivery truthfulness. The product must not claim that a Google Doc or link was created unless it was actually created. (explicit)

• Rationale: delivery statements must match reality.

NFR-11 — Formatting discipline. TITLE = BLACK, NARRATOR = BLACK, POLICE/SUSPECT ACTUAL DIALOGUE = RED; TIMESTAMP follows the supplied reference-document formatting. No unnecessary colors, no emojis, and no explanations inside the final hook. (explicit)

• Rationale: the color code is the product's visual contract with the writer.

NFR-12 — Scope discipline. No full-length script may be created. (explicit)

• Rationale: the deliverable is the hook only.

NFR-13 — Accessible-footage reporting. If the video cannot be accessed, the product must clearly tell the user what is missing and ask for the video file or transcript. (explicit)

• Rationale: the run must not proceed on footage it could not access.

NFR-14 — Identity continuity. Protected hook-writing runs and generated deliverables must remain bound to the correct operator, with self-service enrollment for first use and returning verification before protected work. (required_inference)

• Rationale: a run is durable, actor-specific work that must be resumable and correctly owned.

NFR-15 — Readable content at every viewport. Headlines, wordmarks, labels, numbers, item images, cards, and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering any part of them. (explicit)

• Rationale: stated viewport-integrity requirement; the case title, timestamps, clip labels, and dialogue must never truncate.

NFR-16 — Reduced-motion support. With prefers-reduced-motion, the specimen frame's pulse must stop and the border must sit at full opacity; moving and scrollable content must stop and show whole items. (explicit)

• Rationale: stated accessibility requirement in the creative direction.

10. Tech Stack

• Frontend: React — the interface is a document-generating workspace with a persistent left rail, an asymmetric 7/5 split, and a hook editor that enforces the dialogue/narration colour code. (Default — not specified by user)
• Backend: Python / FastAPI — the run orchestrates footage access, transcript processing, evidence search, timeline assembly, clip sequencing, narration and dialogue handling, timestamp assignment, document assembly, quality checking, and delivery. (Default — not specified by user)
• Storage: appropriate storage for runs, transcripts, timelines, clip selections, narration, dialogue blocks, timestamps, assembled documents, and delivery state. (Default — not specified by user)
• Containerization: Docker / docker-compose for local and deployment packaging. (Default — not specified by user)
• External integrations: Google Drive/Docs for timestamp-link creation and document publication when available; the supplied case video link (Google Drive or another supported video link) as the authoritative content source; optional YouTube reference videos as a structure and feature reference only. (explicit)

Kubernetes is not required by any source-stated deployment constraint and is therefore not included.

11. Assumptions and Constraints

Assumptions

• A1: The case video link resolves to footage the product can access, or the product can report the access failure and request a file or transcript. (required_inference)
• A2: Long videos are handled through a timestamped transcript rather than full manual analysis. (explicit)
• A3: Google Drive/Docs tools are available for timestamp-link creation and document publication in at least some runs; when they are not, the manual delivery path applies. (explicit)
• A4: Reference videos, when supplied, are usable as a structure and feature reference; an unusable reference is simply not used. (explicit)
• A5: Operators are the two accepted personas — Crime Hook Writer and Case Footage Owner / Submitter — and may be the same individual. (required_inference)

Constraints

• C1: Never invent footage. (explicit)
• C2: Never invent timestamps. (explicit)
• C3: Never invent quotes. (explicit)
• C4: Never claim access to a video you cannot access. (explicit)
• C5: Never copy another creator's exact narration. (explicit)
• C6: Use the reference videos only to understand structure, pacing, tone, and clip placement. (explicit)
• C7: Do not copy reference videos' wording; recreate the structural style using original wording. (explicit)
• C8: Do not rewrite spoken dialogue. (explicit)
• C9: Do not present an allegation as an established fact. (explicit)
• C10: Avoid unsupported labels such as "cold-blooded killer" unless the supplied source itself establishes that status and the context clearly supports it. (explicit)
• C11: Do not use unnecessary clips. (explicit)
• C12: Do not repeat information unnecessarily and do not explain the entire case. (explicit)
• C13: Do not use unnecessary colors. (explicit)
• C14: Do not add emojis. (explicit)
• C15: Do not add explanations inside the final hook. (explicit)
• C16: Do not create a full-length script. (explicit)
• C17: Do not claim that a Google Doc or link was created unless it was actually created. (explicit)
• C18: If the video cannot be accessed, clearly tell the user what is missing and ask for the video file/transcript. (explicit)
• C19: If automatic transcription is unclear and cannot be resolved, mark it as [unclear] instead of inventing words. (explicit)
• C20: If Google Drive timestamp-link creation is unavailable, clearly mark [ADD GOOGLE DRIVE TIMESTAMP LINK] and provide the exact timestamp so the user can add it manually. (explicit)
• C21: The final hook must feel like it was written by a real human crime-documentary writer, not an AI. (explicit)
• C22: The generic indigo/blue-on-white SaaS template is forbidden for this project. (explicit)

12. Glossary

• Hook — the 30–60 second YouTube opening produced by the product, structured as HOOK CLIP → NARRATOR INTRO → SUSPECT DENIAL → NARRATOR TRANSITION → EVIDENCE/CONFRONTATION → SUSPECT REACTION → FINAL CLIFFHANGER.
• Case footage — the interrogation video supplied through the case video link; the authoritative content source.
• Case video link — the Google Drive or other supported video link supplied by the user.
• Reference videos — optional YouTube links studied only for structure, pacing, narration style, clip selection, transitions, and hook construction; never a source of wording or facts.
• Timestamped transcript — the time-indexed text of the footage, obtained rather than manually analyzing every second of a long video.
• Evidentiary moment — a searchable point in the footage such as a suspect denial, police accusation, contradiction, evidence reveal, surveillance/video evidence, suspect reaction, suspicious statement, admission, lie or changing story, emotional reaction, moment where detectives expose the suspect, or the strongest cliffhanger moment.
• Case timeline — the internal supported record of victim, suspect, alleged crime, date/location if documented, major evidence, interrogation situation, suspect's stated version, detectives' evidence, and the major contradiction.
• Clip — one of approximately four to eight short footage selections ordered into the hook sequence.
• Narration — original documentary English written by the product, rendered in black (bone) in the hook document.
• Dialogue block — a police or suspect quotation preserved exactly as spoken, rendered in red in the hook document.
• Timestamp — the exact beginning-and-ending time of a selected clip, in the format [00:07–00:09].
• [unclear] — the marker used when a transcription passage cannot be resolved, in place of invented words.
• [ADD GOOGLE DRIVE TIMESTAMP LINK] — the marker used when timestamp-link creation is unavailable, accompanied by the exact timestamp for manual addition.
• Hook document — the assembled final deliverable: TITLE, then alternating timestamped POLICE/SUSPECT DIALOGUE blocks and narrator paragraphs.
• Run — one hook-writing execution bound to a case video link, a requested title, and optional reference links.
• Specimen frame — the 2px red-bordered frame holding the case video, desaturated until a clip is active.
• Clip index — the vertical 01–08 timecode list in the left rail that acts as a transport control.
• Colour code — red #E4002B = spoken dialogue, bone #EDEBE6 = narrator, grey #6E6E73 = metadata.