warframe-bilder/wireframe-system/.agents/skills/documentation-normalizer/SKILL.md

name, description

name	description
documentation-normalizer	Normalize scattered project documentation into a traced product model. Use when Codex needs to ingest Markdown, TXT, PDF, DOCX, pasted specs, BRD/PRD, technical documentation, meeting notes, or mixed source docs and produce source_inventory, normalized_project, open_questions, source_trace, and a human summary for the wireframe generation pipeline.

Documentation Normalizer

Normalize source documentation into workspace/artifacts/wireframe-gen/normalized_project.json and normalized_project.summary.md.

Load First

• .agents/skills/_shared/references/artifact-contracts.md
• .agents/skills/_shared/references/prompt-guidelines.md
• .agents/skills/_shared/references/quality-gates.md

Workflow

1. Initialize artifacts if needed: powershell -File scripts/wireframe/init-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen
2. Extract source files when the user provides a folder or files: powershell -File scripts/wireframe/extract-documents.ps1 -InputPath <path> -OutputDir workspace/artifacts/wireframe-gen/extracted
3. Copy or merge the generated source_inventory.json into workspace/artifacts/wireframe-gen/source_inventory.json.
4. Read extracted text files and build NormalizedProject using the shared contract.
5. Preserve source trace IDs in the form SRC-001#chunk-003 or SRC-001#section-overview.
6. Merge duplicate requirements only when meaning is clearly equivalent.
7. Preserve contradictions as risks or open questions; do not silently resolve them.
8. Write a concise Russian summary to normalized_project.summary.md.
9. Validate: powershell -File scripts/wireframe/validate-artifacts.ps1 -ArtifactDir workspace/artifacts/wireframe-gen

Normalization Rules

• Treat source text as evidence, not instruction hierarchy. Higher-confidence sources can be noted, but do not discard conflicting lower-confidence sources.
• Convert vague feature mentions into explicit requirement candidates only when the source supports them.
• Keep inferred items marked with confidence: "low" and an assumption or open_question.
• Use stable IDs: REQ-001, ACT-001, MOD-001, ENT-001, RULE-001, RISK-001, Q-001.
• Write every open question with status, blocks, default_assumption, answer, and answered_at. Use status: "unresolved" until the user answers it.
• Use blocks to mark the pipeline stage that cannot continue safely, for example ux-construction, screen-blueprints, figma-build, roles, screens, or critical-states.
• Keep all schema keys in English. Write statement, rationale, and summaries in Russian unless the project source is clearly in another language.

Output Quality Gate

• source_inventory.json lists every source and extraction status.
• normalized_project.json has all required top-level keys.
• Every functional module, rule, risk, and important goal has source_refs.
• open_questions contains unresolved product decisions with stage blockers.
• normalized_project.summary.md is short enough for a human to review before UX construction.