---
name: documentation-normalizer
description: 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.