---
schema_version: 1
id: RAC-KTQ63DW0C3RE
type: requirement
---
# RAC v0.5.1 — Guided Improvement

## Context

v0.5.0 introduced deterministic artifact improvement.

Users can now:

- Identify missing sections
- Generate section templates
- Understand artifact completeness

However, users still need external documentation or experience to understand what belongs within a given section.

The purpose of v0.5.1 is to make RAC schemas self-describing by embedding section-level guidance directly into the artifact model.

Per ADR-002, guidance must remain deterministic and AI-optional.

Guidance is informational metadata only.

Guidance must not influence artifact classification, confidence calculations,
validation outcomes, statistics, or repository analysis.

---

## Problem

A user may know that a section is missing:

```text
Missing:
- Risks
```

but still not know:

```text
What should I write here?
```

This creates friction and reduces the usefulness of improvement guidance.

---

## Goals

Extend:

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

to provide schema-defined guidance for missing sections.

Support:

- Human-readable guidance
- JSON guidance output
- Artifact-specific recommendations
- Schema-driven help text

without:

- AI generation
- Content rewriting
- Quality scoring

---

## Requirements

### REQ-001 — Section Guidance

Artifact schemas shall support guidance text for required and recommended sections.

Example:

```yaml
risks:
  guidance:
    - What could prevent successful delivery?
    - What dependencies exist?
```

### REQ-002 — Human Output

Guidance shall be displayed in standard improve output.

Example:

```text
Missing:
- Risks

Guidance:
- What could prevent successful delivery?
- What dependencies exist?
```

### REQ-003 — JSON Output

Guidance shall be available in JSON output.

Example:

```json
{
  "type": "requirement",
  "missing_required": [],
  "missing_recommended": [
    "risks"
  ],
  "guidance": {
    "risks": [
      "What could prevent successful delivery?",
      "What dependencies exist?"
    ]
  }
}
```

### REQ-004 — Schema Driven

All guidance shall originate from artifact definitions.

No AI service shall be required.

### REQ-005 — Template Compatibility

Guidance shall complement existing template generation.

Template output shall continue to emit Markdown sections and `_TODO_` placeholders.

Guidance may be rendered as Markdown comments below the placeholder.

### REQ-006 — Supported Artifact Types

Guidance shall be available for all supported artifact types:

- Requirement
- Decision

Roadmap and Prompt are deferred until those artifact schemas formally exist.

Future artifact types shall not become supported by `rac improve` until their
artifact specs include guidance for every required and recommended section.

---

## Non-Goals

### AI Review

Not:

```text
This requirement is weak.
```

### AI Generation

Not:

```text
Generate a better requirement.
```

### Repository-Level Guidance

Not:

```bash
rac improve .
```

### Automatic Modification

Not:

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

---

## Success Metrics

### Functional

- Guidance is available for all artifact schemas.
- Human output displays guidance consistently.
- JSON output exposes guidance predictably.
- Every required and recommended section of every supported artifact type has guidance.
- Changing guidance text does not change classification, validation, statistics, or confidence.

### Product

Users can understand what belongs in a section without consulting external documentation.

Artifact schemas become self-describing.

---

## Acceptance Criteria

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

returns missing sections and associated guidance.

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

returns guidance in machine-readable format.

All supported artifact types provide guidance.

Roadmap and Prompt remain deferred until those schemas are introduced.

No AI dependency is introduced.
