---
schema_version: 1
id: RAC-KTQ63DVXAH8W
type: requirement
---
# RAC v0.5.0 — Artifact Improvement

## Context

RAC currently supports:

- Validation (`rac validate`)
- Statistics (`rac stats`)
- Document Ingestion (`rac ingest`)
- Artifact Inspection (`rac inspect`)

Inspection allows users to determine:

- Artifact type
- Confidence
- Present sections
- Missing sections

However, inspection remains descriptive.

Users can identify gaps but receive no assistance in completing artifacts.

Per ADR-002 (AI Optional), improvement guidance must not depend on AI services.

The purpose of v0.5.0 is to introduce deterministic, schema-driven improvement guidance that helps users complete artifacts while remaining fully transparent and reproducible.

This release builds directly on top of inspection.

---

## Problem

Inspection can identify missing sections:

```text
Missing:
- Risks
- Assumptions
```

but users must manually reference templates or documentation to determine what to add.

This creates unnecessary friction and limits the practical value of inspection.

---

## Goals

Introduce:

```bash
rac improve <file>
```

to provide deterministic improvement guidance.

Support:

- Missing section analysis
- Missing section templates
- Human-readable output
- JSON output
- File and stdin workflows

without:

- AI
- Content generation
- Automatic modification

---

## Requirements

### REQ-001 — Improvement Analysis

The system shall analyze an artifact and identify missing required and recommended sections.

### REQ-002 — Improvement Suggestions

The system shall generate deterministic improvement guidance derived from the artifact schema.

Example:

```text
Missing Required:
- Requirements

Missing Recommended:
- Risks
- Assumptions
```

### REQ-003 — Template Generation

The system shall support:

```bash
rac improve file.md --template
```

and output templates for missing sections.

Example:

```markdown
## Risks

_TODO_

## Assumptions

_TODO_
```

### REQ-004 — Read-Only Operation

The system shall not modify files.

All output shall be written to stdout.

### REQ-005 — JSON Output

The system shall support:

```bash
rac improve file.md --json
```

and return structured machine-readable output.

Example:

```json
{
  "type": "requirement",
  "missing_required": [],
  "missing_recommended": [
    "risks",
    "assumptions"
  ]
}
```

### REQ-006 — Unknown Artifacts

Unknown classifications shall return:

```text
Unable to generate improvement guidance.
Artifact type could not be determined.
```

### REQ-007 — Pipeline Compatibility

The command shall support file-first workflows and stdin.

Examples:

```bash
rac improve file.md

cat file.md | rac improve -

rac ingest file.docx --stdout | rac improve -
```

---

## Non-Goals

### AI Content Generation

Not:

```text
Rewrite this requirement
Improve this roadmap
Generate better content
```

### Automatic Modification

Not:

```bash
rac improve file.md --fix
```

### Quality Scoring

Not:

```text
This requirement is poorly written.
```

### Repository Analysis

Not:

```bash
rac improve .
```

Repository-level capabilities belong in later releases.

---

## Success Metrics

### Functional

- Missing sections are identified correctly.
- Template generation operates consistently.
- Human and JSON outputs are supported.
- File and stdin workflows behave identically.

### Product

Users can move directly from:

```bash
rac inspect requirement.md
```

to:

```bash
rac improve requirement.md --template
```

without consulting documentation.

### Completion

A user can take a valid but incomplete Requirement and generate a complete
RAC-compliant skeleton using only `rac improve --template`.

---

## Acceptance Criteria

```bash
rac improve requirement.md
```

returns missing required and recommended sections.

```bash
rac improve requirement.md --template
```

outputs templates for missing sections.

```bash
rac improve requirement.md --json
```

returns structured improvement data.

```bash
cat requirement.md | rac improve -
```

operates successfully.

Unknown artifacts return explanatory guidance.