Vadim Flowed
48 lines
3.1 KiB
Markdown
48 lines
3.1 KiB
Markdown
---
|
|
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.
|