99 lines
9.6 KiB
Markdown
99 lines
9.6 KiB
Markdown
# 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](../spec.md) | [plan.md](../plan.md) | [research.md](../research.md) | [data-model.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
|
||
|
||
- [x] 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]
|
||
- [x] CHK002 Are all 5 media subtypes (`video`, `image`, `images`, `embed`, `mixed`) exhaustively specified with their definitions? [Completeness, Spec §FR-009]
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] CHK005 Are all 11 mandatory operational metrics enumerated with their exact tracking points documented in the plan? [Completeness, Spec §FR-028; Plan §4.5]
|
||
- [x] CHK006 Are the specific conditions that trigger operational fallback defined for each provider? [Completeness, Spec §FR-019, §FR-020; Plan §4.3]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] CHK009 Were real repository files inspected, reusing existing dependencies (`beautifulsoup4`, `urllib.request`) and avoiding new package installations? [Minimalism, Plan §2, §5]
|
||
- [x] 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]
|
||
- [x] CHK011 Are speculative abstractions, generic provider frameworks, and unnecessary domain DTOs (e.g. `MediaBatchReport`, `MediaMetricsCollector`, `FailedArticle`, `ClassificationFailedArticle`) completely absent? [Minimalism, Plan §5, §7]
|
||
- [x] 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
|
||
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] CHK018 Is the prompt unique, concise, and language-independent, explicitly prohibiting reasoning, summaries, rationale, and translation requests? [Prompt, Spec §FR-010; Plan §4.2]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] 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]
|
||
- [x] CHK022 Are voting, model consensus, second opinions, LLM-as-a-judge, and confidence thresholds strictly excluded? [Boundary, Spec §FR-021; Plan §4.3, §7]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] 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]
|
||
- [x] 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]
|
||
- [x] 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
|
||
|
||
- [x] 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
|