---
schema_version: 1
id: RAC-KTQ63DWDWWAA
type: requirement
---
# RAC v0.6.1 — Roadmap Improvement

## Context

v0.6.0 introduced Roadmap artifacts as a first-class RAC artifact type.

Roadmap artifacts can now be:

- Registered in `ArtifactSpec`
- Inspected
- Validated
- Counted in repository statistics
- Displayed through `rac schema`
- Generated as starter templates

v0.6.1 extends this foundation by improving RAC's ability to help users complete and strengthen Roadmap artifacts through deterministic, schema-driven guidance.

This release continues the progression established in v0.5.x:

```text
v0.5.0  Identify missing structure
v0.5.1  Explain how to complete missing structure
v0.5.2  Show what an artifact should look like

v0.6.0  Add Roadmap artifacts
v0.6.1  Improve Roadmap artifacts
```

This release remains fully aligned with ADR-017:

```text
RAC manages knowledge, not work.
```

Roadmap improvement must therefore focus on knowledge completeness, not delivery management.

---

## Problem

Roadmaps often list initiatives without clearly explaining:

- What outcomes they support
- How success will be measured
- What assumptions influence the plan
- What risks may affect the intended outcomes

Even when a roadmap is structurally valid, it may still be incomplete as a knowledge artifact.

RAC should help users identify missing roadmap knowledge without introducing project-management concepts such as owners, timelines, priorities, due dates, or workflow states.

---

## Goals

Extend `rac improve` for Roadmap artifacts.

Support:

- Missing Roadmap section guidance
- Outcome-oriented roadmap completion
- Schema-driven improvement output
- JSON output
- Template output for missing sections

while remaining:

- Deterministic
- AI-optional
- Read-only
- File-first
- Knowledge-focused

---

## Requirements

### REQ-001 — Roadmap Improvement Support

`rac improve` shall support Roadmap artifacts.

Example:

```bash
rac improve roadmap.md
```

The command shall identify missing required and recommended Roadmap sections.

---

### REQ-002 — Roadmap Missing Section Analysis

Roadmap improvement shall identify missing required sections.

Required sections:

- Outcomes
- Initiatives

Missing required sections shall be reported separately from missing recommended sections.

---

### REQ-003 — Roadmap Recommended Section Analysis

Roadmap improvement shall identify missing recommended sections.

Recommended sections:

- Success Measures
- Assumptions
- Risks

Example:

```text
Artifact Type: Roadmap

Missing Recommended:
- Success Measures
- Risks
```

---

### REQ-004 — Roadmap Guidance

Roadmap improvement shall display guidance for missing Roadmap sections.

Example:

```text
Missing Recommended:
  - Success Measures
      • How will the team know the roadmap is succeeding?
      • What observable signals would show progress?
```

Guidance shall come from `ArtifactSpec.guidance`.

No AI services shall be used.

---

### REQ-005 — Roadmap Template Output

`rac improve roadmap.md --template` shall emit Markdown sections for missing Roadmap sections only.

Example:

```markdown
## Success Measures

TODO: describe how progress or success will be measured.

<!-- How will the team know the roadmap is succeeding? -->
<!-- What observable signals would show progress? -->

## Risks

TODO: describe risks that may affect roadmap outcomes.

<!-- What could prevent these outcomes from being achieved? -->
```

Required sections shall be emitted before recommended sections.

---

### REQ-006 — Roadmap JSON Output

`rac improve roadmap.md --json` shall include Roadmap improvement results.

Example:

```json
{
  "type": "roadmap",
  "missing_required": [],
  "missing_recommended": [
    "success_measures",
    "risks"
  ],
  "guidance": {
    "success_measures": [
      "How will the team know the roadmap is succeeding?",
      "What observable signals would show progress?"
    ],
    "risks": [
      "What could prevent these outcomes from being achieved?"
    ]
  }
}
```

---

### REQ-007 — Roadmap Template Validation

Roadmap improvement templates shall be structurally valid when combined with an existing Roadmap artifact.

Generated template sections shall not introduce content that violates validation rules.

TODO text may be used where validation permits free text.

---

### REQ-008 — No Work-Management Guidance

Roadmap guidance shall not suggest or require:

- Owners
- Assignees
- Due dates
- Delivery dates
- Timelines
- Sprints
- Priorities
- Workflow states
- Capacity estimates

Guidance shall focus on roadmap knowledge, not work coordination.

---

### REQ-009 — Existing Artifact Types Remain Supported

Existing `rac improve` support for Requirement and Decision artifacts shall remain unchanged.

Roadmap support shall be additive.

---

## Non-Goals

### Roadmap Scoring

Not:

```text
This roadmap is low quality.
```

RAC shall not assign roadmap quality scores.

---

### Initiative-to-Outcome Mapping

Not:

```text
Initiative X does not map to Outcome Y.
```

v0.6.1 shall not analyze relationships between individual initiatives and outcomes.

This belongs to future relationship analysis.

---

### Relationship Analysis

Not:

```bash
rac relationships .
```

Optional sections such as Related Decisions and Related Requirements may exist, but RAC shall not validate or analyze them in this release.

---

### Project Management

This release shall not introduce:

- Owners
- Assignees
- Due dates
- Timelines
- Sprints
- Priorities
- Status workflows
- Delivery tracking

These concerns belong to project-management tools.

---

### AI Roadmap Advice

Not:

```text
Here is a better roadmap.
```

or:

```text
You should prioritize Initiative A over Initiative B.
```

No AI-generated advice or prioritization is included.

---

## Success Metrics

### Functional

- `rac improve` supports Roadmap artifacts.
- Missing Roadmap sections are reported correctly.
- Roadmap guidance is displayed in human output.
- Roadmap guidance is included in JSON output.
- Roadmap missing-section templates are emitted correctly.
- Requirement and Decision improvement remain unchanged.

### Product

Users can identify missing Roadmap knowledge without manually comparing against the schema.

Users can complete a partial Roadmap artifact using:

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

without consulting external documentation.

---

## Acceptance Criteria

```bash
rac improve roadmap.md
```

reports missing required and recommended Roadmap sections.

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

returns Roadmap improvement results with guidance.

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

emits Markdown sections for missing Roadmap sections.

Roadmap improvement guidance does not mention owners, sprints, due dates, timelines, or delivery tracking.

Requirement improvement continues to work.

Decision improvement continues to work.

Unknown artifacts continue to return the existing unsupported guidance message.

No files are modified.

No AI services are required.

---

## Future Considerations

Future releases may introduce:

- Initiative-to-outcome relationship analysis
- Related Decision detection
- Related Requirement detection
- Portfolio health analysis
- Roadmap coverage analysis
- Repository-level roadmap intelligence

These capabilities should build on Roadmap artifacts while preserving the boundary that RAC manages knowledge, not work.