Media Routing Requirements Quality & Implementation Planning Checklist

Purpose: Validate requirements quality, architectural fidelity, and implementation plan completeness for the media routing feature Created: 2026-08-24 Feature: spec.md | plan.md | research.md | data-model.md

Note: This checklist is a reviewer-owned review artifact. Mark an item [x] only when the reviewer determines the quality criterion is satisfied. Marker Semantics: [x] means the criterion has been reviewed and satisfied. It does not mean implementation work is complete.

1. Requirement & Plan Fidelity

CHK001 Does the specification define behavioral requirements for structural media relevance to the publication while the plan and research define the concrete, minimal DOM parsing algorithm without contradiction? [Fidelity, Spec §FR-001, §FR-004; Plan §4.1; Research §Decisão 1]
CHK002 Are all 5 media subtypes (video, image, images, embed, mixed) exhaustively specified with their definitions? [Completeness, Spec §FR-009]
CHK003 Are the payload fields for compact LLM input generation fully defined across the plan and data model without arbitrary truncation of editorial text? [Completeness, Plan §4.2; Data-Model §2]
CHK004 Are the required fields, mandatory file generation in all successful batch runs, and minimal envelope structure (articles, containing [] when zero media articles) for *_media.json explicitly specified without extra report fields? [Completeness, Spec §FR-014, §FR-015; Plan §4.4; Contract: media-output.schema.json]
CHK005 Are all 11 mandatory operational metrics enumerated with their exact tracking points documented in the plan? [Completeness, Spec §FR-028; Plan §4.5]
CHK006 Are the specific conditions that trigger operational fallback defined for each provider? [Completeness, Spec §FR-019, §FR-020; Plan §4.3]
CHK007 Are error handling and reporting requirements specified when all 3 LLM providers fail, recording the failure inline in the main JSON with classification_status: "failed" without creating separate failure files or DTOs? [Completeness, Spec §FR-022; Plan §4.3; Data-Model §2.6]
CHK008 Are all ungrounded technical promises, invented latency SLOs (<1.5s, <10ms) and artificial benchmarks completely absent from the plan? [Fidelity, Plan §2, §4]

2. Minimal Implementation & Code Reusability

CHK009 Were real repository files inspected, reusing existing dependencies (beautifulsoup4, urllib.request) and avoiding new package installations? [Minimalism, Plan §2, §5]
CHK010 Is the implementation organized as lightweight functions in scripts/extract_article_contents.py rather than unnecessary class hierarchies or generic provider frameworks? [Minimalism, Plan §5]
CHK011 Are speculative abstractions, generic provider frameworks, and unnecessary domain DTOs (e.g. MediaBatchReport, MediaMetricsCollector, FailedArticle, ClassificationFailedArticle) completely absent? [Minimalism, Plan §5, §7]
CHK012 Was src/tools/adapters/llm.py evaluated and its non-reuse properly justified due to its coupling to the ECP domain rather than creating redundant provider frameworks? [Minimalism, Plan §5; Research §Decisão 3]

3. Structural DOM Gate

CHK013 Is the DOM structural gate defined without treating <source> alone as video, without double-counting <figure>/<picture> wrappers, and distinguishing editorial content from page structure (<header>, <nav>, <footer>, <aside>)? [Gate, Plan §4.1; Research §Decisão 1]
CHK014 Is the structural gate completely free of regular expressions (re), language-specific keywords, site-specific selectors, and ad detectors? [Constraint, Spec §FR-002; Plan §4.1]
CHK015 Does the gate bypass the LLM completely when no relevant candidate media is present, sending the article directly to extract_all_engines()? [Gate, Spec §FR-003; Plan §4.1]

4. Classifier Payload & Interface Contracts

CHK016 Is the compact payload defined with title, normalized editorial text without HTML and without arbitrary character truncation, and structural media summary? [Payload, Spec §FR-005, §FR-006; Plan §4.2]
CHK017 Does the classifier output contract contain exactly 2 fields (content_type and media_type), enforcing text -> media_type = null and media -> media_type != null in application validation? [Contract, Spec §FR-007, §FR-008, §FR-009; Contract: classifier-io.schema.json]
CHK018 Is the prompt unique, concise, and language-independent, explicitly prohibiting reasoning, summaries, rationale, and translation requests? [Prompt, Spec §FR-010; Plan §4.2]
CHK019 Does Ollama use JSON Schema in format, Groq use native JSON Schema Structured Output with openai/gpt-oss-20b, OmniRoute use JSON Schema Structured Output, and the application strictly validate the two-field schema? [Contract, Spec §FR-011; Plan §4.3]
CHK020 Is deliberative reasoning/thinking explicitly disabled/configured per provider (Ollama: think=false, Groq: reasoning_effort="low", OmniRoute: sem parâmetro inventado), ensuring no reasoning content appears in the output? [Reasoning, Plan §4.3; Research §Decisão 3]

5. Sequential Provider Chain & Fallback Rules

CHK021 Is the provider order strictly Ollama (qwen3.5:2b) → Groq (openai/gpt-oss-20b) → OmniRoute (cgpt-web/gpt-5.5), executing sequentially and stopping immediately on the first valid response? [Providers, Spec §FR-018, §FR-019, §FR-020, §FR-021; Plan §4.3]
CHK022 Are voting, model consensus, second opinions, LLM-as-a-judge, and confidence thresholds strictly excluded? [Boundary, Spec §FR-021; Plan §4.3, §7]
CHK023 Are automatic per-provider retries, exponential backoff, circuit breakers, discovery frameworks, and health services strictly excluded from the provider chain? [Boundary, Plan §4.3, §7]
CHK024 Are endpoints, models, timeouts, and API keys externalized via environment variables, with OmniRoute having no invented default hostname? [Security, Spec §FR-025; Plan §4.3]

6. I/O Persistence, Counter Semantics & CLI Interface

CHK025 Are the naming and path derivation rules for *_media.json explicit and identical for default (same stem/dir) and custom -o/--output paths? [I/O, Spec §FR-014; Plan §4.4; Contract: cli-interface.md]
CHK026 Does every successful batch run generate *_media.json, using { "articles": [] } when zero media articles were classified, without extra report counters or status aggregates? [I/O, Spec §FR-014, §FR-015; Plan §4.4; Contract: media-output.schema.json]
CHK027 Do the main JSON counters (total_articles, successful_articles, failed_articles) reflect strictly the items present in that file, excluding media articles and including classification failures? [Counters, Spec §FR-017; Plan §4.4]
CHK028 Does the implementation preserve 100% of the input metadata dictionary in input_meta across text, media, and failure records without dropping unknown fields or inventing default values? [Data Integrity, Plan §4.4; Data-Model §2.1]
CHK029 Does the implementation preserve 100% of the existing CLI interface (-i, -o, -l, --lang, -t, -s) without creating new flags like --media-output? [CLI, Spec §FR-030; Plan §4.4]

7. Observability, Logging & Security Constraints

CHK030 Are all 11 required operational metrics incremented in memory at the exact points defined and emitted via existing stderr logging mechanisms while respecting the -s/--silent flag? [Observability, Spec §FR-028; Plan §4.5]
CHK031 Are logs structured to record provider usage, fallback transitions, final classifications, and total failures without logging full text payloads by default? [Observability, Spec §FR-027; Plan §4.5]
CHK032 Are API keys, tokens, and credentials strictly prevented from appearing in logs, error messages, and JSON outputs? [Security, Spec §FR-026; Plan §4.5]

8. Test Coverage & CI Determinism

CHK033 Are all 13 normative test scenarios (A through M) plus zero-media batch generation covered in the test plan, spanning text-only, single media, multiple images, mixed media, long text with media, fallbacks, and multilingual cases? [Test Coverage, Spec §User Stories; Plan §6]
CHK034 Are deterministic unit and integration tests defined to simulate the 5 provider states in CI without requiring live network calls to Ollama, Groq, or OmniRoute? [Test CI, Spec §FR-024; Plan §4.3, §6]
CHK035 Is the zero-regex policy verified via static AST inspection in tests/scripts/check_zero_regex.py across all feature modules and tests? [Zero-Regex, Spec §SC-007; Plan §5, §6]

9. Global Artifact Consistency Check

CHK036 Are spec.md, plan.md, research.md, data-model.md, quickstart.md, classifier-io.schema.json, media-output.schema.json, and cli-interface.md 100% consistent with each other, confirming that classification failures are recorded inline with classification_status: "failed" and without any reintroduction of MediaBatchReport, MediaMetricsCollector, or DTOs de falha? [Consistency, Plan §5, §7; Data-Model §2]

Notes

Mark items [x] only after review confirms the quality criterion is satisfied
Leave items unchecked when they still require clarification, correction, or reviewer evaluation
/speckit-implement reads checklist checkbox state as a gate and must not modify markers
Items are numbered sequentially (CHK001–CHK036) for easy reference

9.6 KiB Raw Permalink Blame History Unescape Escape