---
schema_version: 1
id: RAC-KTQ63DW94YN8
type: requirement
---
# RAC v0.6.0 — Roadmap Artifacts

## Context

RAC currently supports structured Requirement and Decision artifacts.

Recent releases introduced:

- Artifact inspection
- Artifact-aware validation
- Artifact improvement
- Guided improvement
- Schema reference and starter templates

The next step is to introduce Roadmap artifacts as a first-class RAC artifact type.

This release should focus on defining, validating, inspecting, and templating Roadmap artifacts.

It should not introduce project-management concepts such as owners, due dates, sprints, delivery tracking, or workflow states.

Per ADR-017, RAC manages knowledge, not work.

---

## Problem

Roadmaps often focus on outputs rather than outcomes.

Teams may list initiatives, features, or delivery items without clearly explaining:

- What outcome is being pursued
- Why the work matters
- How success will be measured
- What assumptions or risks exist

This makes roadmap quality difficult to assess and compare.

RAC should help teams represent roadmap knowledge as structured, inspectable artifacts without becoming a project-management tool.

---

## Goals

Introduce Roadmap artifacts as a supported RAC artifact type.

Support Roadmaps across existing RAC capabilities:

- `rac inspect`
- `rac validate`
- `rac stats`
- `rac improve`
- `rac schema`

while remaining:

- Markdown-first
- File-first
- AI-optional
- Read-only unless explicitly generating stdout templates
- Focused on knowledge, not work management

---

## Roadmap Artifact Schema

### Required Sections

- Outcomes
- Initiatives

### Recommended Sections

- Success Measures
- Assumptions
- Risks

### Optional Sections

- Related Decisions
- Related Requirements

---

## Requirements

### REQ-001 — Roadmap Artifact Support

RAC shall support Roadmap artifacts as a first-class artifact type.

Roadmap artifacts shall be registered in `ArtifactSpec`.

---

### REQ-002 — Roadmap Inspection

`rac inspect` shall classify Roadmap artifacts.

Example:

```bash
rac inspect roadmap.md
```

Output:

```text
Artifact Type: Roadmap
Confidence: 0.87
```

---

### REQ-003 — Roadmap Validation

`rac validate` shall validate Roadmap artifacts against the Roadmap schema.

Required sections:

- Outcomes
- Initiatives

Missing required sections shall fail validation.

Missing recommended sections shall not fail validation.

---

### REQ-004 — Roadmap Statistics

`rac stats` shall include Roadmap artifacts in repository statistics.

Roadmaps shall be counted separately from Requirements and Decisions.

Example:

```text
Artifacts

Requirements: 12
Decisions: 8
Roadmaps: 3
Unknown: 1
```

---

### REQ-005 — Roadmap Improvement

`rac improve` shall support Roadmap artifacts when guidance coverage exists for all expected Roadmap sections.

Improvement shall remain structural and schema-driven.

Example:

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

Output:

```text
Missing Recommended:
- Success Measures
- Risks
```

---

### REQ-006 — Roadmap Schema Reference

`rac schema roadmap` shall display the Roadmap schema.

The schema reference shall include:

- Required sections
- Recommended sections
- Optional sections
- Descriptions
- Guidance

---

### REQ-007 — Roadmap Template Generation

`rac schema roadmap --template` shall emit a structurally valid Roadmap starter template.

Example:

```markdown
# Title

## Outcomes

TODO: describe the outcomes this roadmap is intended to achieve.

<!-- What user, business, or operational outcomes matter? -->
<!-- Why are these outcomes important now? -->

## Initiatives

TODO: describe the major initiatives that support the outcomes.

<!-- What major bodies of work support these outcomes? -->
<!-- How does each initiative connect to an outcome? -->

## Success Measures

TODO: describe how progress or success will be measured.

<!-- How will the team know the roadmap is succeeding? -->

## Assumptions

TODO: describe assumptions that influence this roadmap.

<!-- What must be true for this roadmap to remain valid? -->

## Risks

TODO: describe risks that may affect roadmap delivery or outcomes.

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

---

### REQ-008 — Roadmap JSON Output

Roadmap support shall be reflected in JSON outputs for:

- `rac inspect --json`
- `rac stats --json`
- `rac improve --json`
- `rac schema roadmap --json`

JSON output shall remain additive and backwards compatible where possible.

---

## Non-Goals

### Work Management

This release shall not introduce:

- Owners
- Assignees
- Due dates
- Delivery dates
- Timelines
- Sprints
- Priorities
- Status workflows
- Capacity planning

These concerns belong to project-management tools, not RAC.

---

### Timeline Validation

Not:

```text
This roadmap item is due in Q3.
```

Timeline modelling is out of scope.

---

### Initiative Ownership

Not:

```text
Initiative owner: Alice
```

Ownership and accountability belong to work-management systems.

---

### Roadmap Scoring

Not:

```text
This roadmap is weak.
```

RAC shall not score roadmap quality.

---

### AI Roadmap Review

Not:

```text
Suggest a better roadmap.
```

No AI review or generation is included.

---

### Relationship Analysis

Not:

```bash
rac relationships .
```

Optional sections such as Related Decisions and Related Requirements may be represented as text, but RAC shall not validate or analyze those relationships in v0.6.0.

Relationship analysis belongs to a later release.

---

## Success Metrics

### Functional

- Roadmap artifacts can be inspected.
- Roadmap artifacts can be validated.
- Roadmap artifacts appear in repository statistics.
- Roadmap artifacts can be improved structurally.
- Roadmap schemas can be displayed through `rac schema`.
- Roadmap starter templates can be generated.

### Product

Users can create a structurally valid Roadmap artifact using:

```bash
rac schema roadmap --template
```

Users can understand whether a Roadmap artifact contains outcomes, initiatives, and success measures without manual review.

---

## Acceptance Criteria

```bash
rac schema --list
```

includes:

```text
roadmap
```

```bash
rac schema roadmap
```

displays the Roadmap schema.

```bash
rac schema roadmap --json
```

returns the Roadmap schema as structured JSON.

```bash
rac schema roadmap --template
```

emits a structurally valid Roadmap starter template.

```bash
rac schema roadmap --template | rac validate -
```

passes.

```bash
rac inspect roadmap.md
```

classifies the file as a Roadmap artifact.

```bash
rac validate roadmap.md
```

validates required Roadmap sections.

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

reports missing required and recommended Roadmap sections with guidance.

```bash
rac stats .
```

counts Roadmap artifacts separately from Requirements and Decisions.

No owners, timelines, sprints, due dates, or workflow states are introduced.

No AI services are required.

---

## Future Considerations

Future releases may introduce:

- Roadmap relationship analysis
- Initiative-to-outcome mapping
- Roadmap-to-decision links
- Roadmap-to-requirement links
- Portfolio health analysis
- Repository-level knowledge graph features

These should build on Roadmap artifacts without turning RAC into a project-management system.