---
schema_version: 1
id: RAC-KTQ63DVG7S1C
type: requirement
---
# v0.3 Knowledge Ingestion

## Problem

Most product knowledge already exists in documents such as Word files.

Product Managers should not need to manually rewrite documents before using RAC.

RAC should provide a reliable way to convert external documents into Markdown, enabling future inspection, validation, analysis, and review workflows.

## Requirements

### Core Conversion

* [REQ-001] User can ingest DOCX files
* [REQ-002] RAC converts DOCX files into Markdown
* [REQ-003] RAC preserves document structure where supported by the conversion engine
* [REQ-004] RAC preserves headings
* [REQ-005] RAC preserves lists
* [REQ-006] RAC preserves tables where supported by the conversion engine
* [REQ-007] RAC preserves image references where supported by the conversion engine

### Output Handling

* [REQ-008] RAC writes output to a Markdown file by default
* [REQ-009] Default output filename is derived from the source filename
* [REQ-010] User can specify an output file using `-o`
* [REQ-011] User can specify an output directory using `-o`
* [REQ-012] RAC writes output to the requested location
* [REQ-013] RAC prevents accidental overwrite unless explicitly requested

### Preview & Pipeline Support

* [REQ-014] User can emit converted Markdown to stdout using `--stdout`
* [REQ-015] When `--stdout` is supplied, RAC does not create output files
* [REQ-016] Output emitted via `--stdout` is suitable for shell pipelines

### Machine Readability

* [REQ-017] Ingestion results can be emitted as JSON
* [REQ-018] JSON output includes the input path
* [REQ-019] JSON output includes the output path when applicable
* [REQ-020] JSON output includes success or failure status

### Error Handling

* [REQ-021] RAC reports unsupported file types
* [REQ-022] RAC reports conversion failures
* [REQ-023] RAC reports output write failures
* [REQ-024] Error messages include actionable guidance

## Examples

### Default Output

```bash
rac ingest prd.docx
```

Creates:

```text
prd.md
```

### Custom Output File

```bash
rac ingest prd.docx -o bond-dashboard.md
```

Creates:

```text
bond-dashboard.md
```

### Custom Output Directory

```bash
rac ingest prd.docx -o requirements/
```

Creates:

```text
requirements/prd.md
```

### Preview Conversion

```bash
rac ingest prd.docx --stdout
```

Outputs Markdown to stdout without creating files.

### JSON Output

```bash
rac ingest prd.docx --json
```

## Success Metrics

* Existing PRDs can be converted without manual preprocessing
* Generated Markdown can be consumed by future RAC commands
* Conversion succeeds on real-world PM documentation
* Output location options support common workflows
* Stdout mode enables future automation and pipeline workflows

## Risks

* Source documents may contain inconsistent formatting
* Tables may convert inconsistently
* Image handling depends on the conversion engine
* Users may expect artifact extraction rather than document conversion

## Non-Goals

The following are explicitly out of scope for v0.3:

* Artifact detection
* Artifact classification
* Requirement validation
* Artifact extraction
* Section normalization
* AI-assisted conversion
* Content rewriting
* Diagram understanding
* Image understanding
* Knowledge graph generation

## Future Considerations

Future releases may introduce:

* Inspect
* Improve
* Artifact detection
* Artifact extraction
* Section normalization
* AI-assisted review
