Markdown Conversion Checklist: End-to-End Requirements Quality

Purpose: Validate the completeness, clarity, consistency, and measurability of requirements for the single-article JSON to Markdown conversion pipeline, ensuring 100% adherence to PRD docs/prd_convert_json_markdown.md.
Created: 2026-08-21
Feature: spec.md | Plan: plan.md | Data Model: data-model.md | PRD: prd_convert_json_markdown.md

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

1. Validação de Entrada, Tipagem & Isolamento de Lotes

CHK001 Is the requirement to accept only a single-article JSON object (and explicitly reject root structures containing articles) unambiguous and testable? [Clarity, Spec §FR-001, §FR-002, PRD §6.1, §8.1]
CHK002 Is input encoding explicitly specified as UTF-8 without BOM with strict JSON parsing validation? [Completeness, Spec §FR-001, PRD §6.1, §10]
CHK003 Is the allowed set of selected_extractor values (trafilatura, newspaper4k, readability) strictly bounded, rejecting missing/unknown values? [Clarity, Spec §FR-003, PRD §6.2, §10]
CHK004 Are mandatory resolved output fields (non-empty Title, valid absolute Original URL, non-empty Body) explicitly defined as non-negotiable gates? [Completeness, Spec §FR-006, PRD §6.3, §10]
CHK005 Is the behavior for non-object JSON roots (e.g. lists, primitives) specified to exit with code 1? [Edge Case, Spec §FR-002, PRD §10]

2. Isolamento Estrito de Extrator & Conversão de Conteúdo (HTML/MD)

CHK006 Is the strict isolation rule prohibiting cross-extractor body fallback explicitly defined, terminating with code 1 if the selected extractor has no body? [Consistency, Spec §FR-005, PRD §8.2, §12 CA-005]
CHK007 Are primary and intra-extractor fallback fields unambiguously mapped for all three extractors (trafilatura.markdown → text, newspaper4k.article_html → text, readability.cleaned_html → cleaned_text)? [Completeness, Spec §FR-004, PRD §8.3]
CHK008 Is direct Markdown reuse for Trafilatura specified without redundant HTML re-parsing? [Clarity, Spec §FR-004, PRD §8.3, §12 CA-001]
CHK009 Are HTML-to-Markdown conversion rules via markdownify (ATX headings #, ##, ###, paragraphs, lists, tables, quotes, bold, italic, code blocks, links, body images) fully documented? [Completeness, Spec §FR-012, PRD §8.10, §15]
CHK010 Is it explicitly specified that external collections like newspaper4k.images must NOT be injected into the converted body? [Clarity, Spec §FR-013, PRD §8.11]

3. Resolução Determinística de Metadados & Mapeamento de SELECIONADO

CHK011 Are candidate priority fallback chains documented for every metadata field without gaps or ambiguity? [Coverage, Spec §FR-008, PRD §8.5]
CHK012 Is the exact field mapping for SELECIONADO defined per extractor (including unavailable fields for Readability and Newspaper4k)? [Completeness, Data Model §2, PRD §8.5]
CHK013 Is the fallback hierarchy for Site Name (SELECIONADO → trafilatura.sitename → newspaper4k.meta_site_name → trafilatura.hostname → Original URL hostname) fully covered? [Completeness, Spec §FR-008, PRD §8.5]
CHK014 Is the first-valid-source rule (picking the first valid source in priority order without merging values across different sources) clearly established? [Consistency, Spec §FR-010, PRD §8.4, §8.7]

4. Normalização de Escalares, Placeholders & Sanitização de Listas

CHK015 Are scalar string normalization rules (HTML entity unescaping, trimming leading/trailing whitespace, collapsing internal consecutive whitespace) testable and unambiguous? [Clarity, Spec §FR-009, PRD §8.6]
CHK016 Is the blacklist of ignored placeholder values (null, none, n/a, unknown, [no-author], no-author - case-insensitive) exhaustively defined? [Completeness, Spec §FR-009, PRD §8.6]
CHK017 Are list normalization rules specified for both array inputs and single strings delimited exclusively by semicolons (;)? [Completeness, Spec §FR-010, PRD §8.7]
CHK018 Is the filter discarding author entries starting with http://, https://, or www. explicitly defined? [Edge Case, Spec §FR-010, PRD §8.7]
CHK019 Is case-insensitive deduplication for list fields defined to preserve the original casing and first occurrence order? [Clarity, Spec §FR-010, PRD §8.7]

5. Normalização de Datas, Fusos & Validação Estrita de URLs

CHK020 Are date parsing expectations (supporting ISO 8601 and RFC 2822) with timezone preservation and YYYY-MM-DD date-only output format explicitly documented? [Clarity, Spec §FR-011, PRD §8.8]
CHK021 Is the behavior for unparseable date candidates specified to discard and advance to the next priority source? [Edge Case, Spec §FR-011, PRD §8.8]
CHK022 Are URL validation criteria (absolute http/https with non-empty hostname, rejecting data:, javascript:, and relative paths) defined for Original URL and Top Image without performing network calls? [Clarity, Spec §FR-007, PRD §8.9]

6. Sanitização Editorial, Tratamento de Imagens & Título Duplicado

CHK023 Are criteria for stripping the initial H1 heading from the body (exact match with resolved title after entity decoding, whitespace collapsing, and case-insensitive comparison) objectively measurable? [Measurability, Spec §FR-014, PRD §8.12, §12 CA-010]
CHK024 Is subtitle omission behavior when identical to the resolved title (after normalization) clearly specified? [Clarity, Spec §FR-015, PRD §7.2]
CHK025 Are body image sanitation rules (keeping only absolute http/https, removing relative/empty/data: images, deduplicating identical URLs) completely covered? [Coverage, Spec §FR-013, PRD §8.11, §12 CA-009]
CHK026 Is the main top image presentation format ![Imagem principal](URL) specified, and omitted when absent or invalid? [Completeness, Spec §FR-015, PRD §7.2]

7. Estrutura, Sintaxe do Markdown de Saída & Restrições

CHK027 Is the final Markdown section order (# Title → Subtitle → Metadata Block → Main Image → --- → Body) explicitly defined? [Completeness, Spec §FR-015, Contract §Markdown-Schema, PRD §7.2]
CHK028 Are metadata label formatting rules (**Autor:**, **Publicado em:**, **Site:**, **Categoria:**, **Tags:**, **Palavras-chave:**, **Idioma:**, **Fonte original:** [URL](URL)) strictly defined, omitting empty labels entirely? [Completeness, Contract §Markdown-Schema, PRD §7.2]
CHK029 Is it explicitly required that selected_extractor name and internal JSON debugging metadata MUST NEVER appear in the generated Markdown? [Consistency, Contract §Markdown-Schema, PRD §7.2]
CHK030 Are whitespace and formatting constraints (UNIX LF line endings, exactly 1 trailing newline at EOF, no trailing spaces per line, at most 2 consecutive newlines, UTF-8 unicode preservation) measurable? [Measurability, Spec §FR-016, PRD §8.13]

8. Interface CLI, Tratamento de Erros & Atomicidade

CHK031 Is the CLI script path scripts/convert_article_to_markdown.py and arguments (-i/--input required, -o/--output optional defaulting to <input_stem>.md) defined? [Completeness, Spec §FR-018, Contract §CLI, PRD §9]
CHK032 Are exit codes (0 for success, 1 for validation/runtime error, 2 for argument syntax error) explicitly documented? [Completeness, Spec §FR-018, Contract §CLI, PRD §9.4]
CHK033 Is stream routing specified (all error and informational diagnostics to stderr, no Markdown dumped to stdout on file write)? [Clarity, Contract §CLI, PRD §9.4]
CHK034 Is error message sanitization specified to ensure full article contents are never dumped to the terminal during failures? [Security/UX, PRD §10]
CHK035 Are atomic file write requirements (temporary file in same directory + atomic replacement via os.replace, with full cleanup on error leaving pre-existing targets untouched) defined? [Non-Functional, Spec §FR-017, PRD §8.14, §11 RNF-004]

9. Estratégia de Testes, Golden Fixtures & Definition of Done

CHK036 Are Golden Test Fixtures required for all 3 extractors (valid_trafilatura.json → .md, valid_newspaper4k.json → .md, valid_readability.json → .md) with exact byte-for-byte matching? [Test Quality, PRD §13.3, §14, Spec §SC-002]
CHK037 Are negative test fixtures required for invalid JSON, batch articles array, missing/unknown extractor, empty selected body, missing title, and invalid original URL? [Coverage, PRD §13.3]
CHK038 Are non-functional constraints (100% deterministic execution, fully local memory processing, no external network requests, sub-second latency) documented as testable gates? [Non-Functional, Spec §SC-006, PRD §11]
CHK039 Are Quality Gates (Ruff, Mypy, Pytest, SonarQube) and README documentation defined as mandatory completion criteria? [Completeness, Plan §Constitution-Check, PRD §14]

Notes

All 39 items have been rigorously validated against PRD docs/prd_convert_json_markdown.md, specs/005-convert-json-markdown/spec.md, plan.md, and data-model.md.
100% adherence to PRD requirements with zero ambiguity or unhandled edge cases.
All items are marked [x] confirming requirements-quality criteria satisfaction.
Ready for /speckit-tasks to break down implementation and TDD test tasks.

9.8 KiB Raw Blame History