---
schema_version: 1
id: RAC-KTQ63DWPNXB1
type: requirement
---
# RAC v0.6.2 — Prompt Artifacts

## Context

RAC currently supports multiple first-class product knowledge artifact types:

- Requirements
- Decisions
- Roadmaps

Earlier releases introduced:

- Artifact inspection
- Artifact-aware validation
- Repository statistics
- Schema-guided improvement
- Schema reference and starter templates

v0.6.x expands RAC's artifact vocabulary before v0.7.x introduces cross-artifact relationships.

The next artifact type to formalize is the Prompt.

Prompts are increasingly important product knowledge artifacts. Teams use prompts to review requirements, summarize roadmaps, analyze decisions, prepare briefs, inspect documents, and guide AI-assisted workflows.

However, prompts are often stored informally in chats, notes, documents, or personal collections.

This makes them difficult to:

- Review
- Reuse
- Improve
- Version
- Share
- Audit

v0.6.2 introduces Prompt artifacts as first-class RAC artifacts.

Prompts are treated as durable product knowledge, not as executable AI workflows.

This release preserves the original intent of the earlier v0.7 Prompts roadmap while moving Prompt artifacts into v0.6.2 so that v0.6.x completes the initial artifact vocabulary.

---

## Problem

AI-assisted workflows increasingly depend on prompts, but prompts are rarely treated as structured source artifacts.

A useful prompt may capture:

- The objective it is intended to achieve
- The input or source material it expects
- The instructions it gives to an AI system
- The output shape it expects
- The constraints it should respect
- Examples of intended usage
- Evaluation criteria for good responses

Without structure, prompts become difficult to compare, validate, improve, or reuse.

RAC should help teams store important prompts as Markdown artifacts that can move through the existing RAC pipeline.

---

## Goals

Introduce Prompt artifacts as a supported RAC artifact type.

Support Prompt artifacts across existing RAC commands:

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

while remaining:

- Markdown-first
- File-first
- AI-optional
- Deterministic
- Read-only except for stdout template generation
- Focused on knowledge, not AI execution

---

## Prompt Artifact Schema

### Required Sections

- Objective
- Input
- Instructions
- Output

### Recommended Sections

- Constraints
- Examples
- Evaluation

### Optional Sections

- Related Requirements
- Related Decisions
- Related Roadmaps

---

## Requirements

### REQ-001 — Prompt Artifact Support

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

Prompt artifacts shall be registered in `ArtifactSpec`.

Prompt support shall reuse the existing artifact architecture rather than introducing prompt-specific engines.

---

### REQ-002 — Prompt Schema Definition

The Prompt `ArtifactSpec` shall define:

- Required sections
- Recommended sections
- Optional sections
- Section descriptions
- Section guidance
- Schema metadata, where applicable

Prompt sections shall be defined as:

Required:

- Objective
- Input
- Instructions
- Output

Recommended:

- Constraints
- Examples
- Evaluation

Optional:

- Related Requirements
- Related Decisions
- Related Roadmaps

---

### REQ-003 — Prompt Schema Reference

`rac schema --list` shall include:

```text
prompt
```

`rac schema prompt` shall display the Prompt schema.

`rac schema prompt --json` shall expose:

- type
- required sections
- recommended sections
- optional sections
- descriptions
- guidance
- metadata

---

### REQ-004 — Prompt Starter Template

`rac schema prompt --template` shall emit a structurally valid Prompt starter template.

Example:

```markdown
# Prompt Title

## Objective

TODO: describe what this prompt is intended to achieve.

<!-- What task should this prompt help complete? -->
<!-- What outcome should the model produce? -->

## Input

TODO: describe the information, context, or source material the prompt expects.

<!-- What context or source material does the prompt require? -->
<!-- What assumptions should the model make about the input? -->

## Instructions

TODO: describe the steps, rules, or approach the model should follow.

<!-- What should the model do first? -->
<!-- What process should it follow? -->

## Output

TODO: describe the expected response format or result.

<!-- What should the output contain? -->
<!-- Should the response be structured as bullets, JSON, Markdown, or prose? -->

## Constraints

TODO: describe any boundaries or restrictions.

<!-- What should the model avoid? -->
<!-- Are there tone, format, safety, or scope constraints? -->

## Examples

TODO: provide example inputs and outputs if useful.

<!-- What examples would make the desired behavior clearer? -->

## Evaluation

TODO: describe how the output should be judged.

<!-- What makes a good response? -->
<!-- How can the user tell whether the prompt worked? -->
```

Optional relationship sections shall appear in schema output and JSON but shall not be included in starter templates by default.

---

### REQ-005 — Prompt Inspection

`rac inspect` shall classify Prompt artifacts using the existing schema-driven classification model.

Prompt classification shall remain deterministic and based on section structure.

Invalid but sufficiently complete Prompt artifacts may still classify as Prompt when they meet the global classification threshold.

Example:

```markdown
# Requirement Review Prompt

## Objective

TODO: review a requirement.

## Input

TODO: provide a Requirement artifact.

## Instructions

TODO: identify missing sections.
```

Expected behavior:

- classify as Prompt
- fail validation due to missing Output

A Prompt artifact with too few Prompt-specific sections may classify as Unknown.

Prompt classification shall not use AI inference or title-only matching.

Prompt classification shall not change existing Requirement, Decision, or Roadmap classification behavior.

---

### REQ-006 — Prompt Validation

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

A valid Prompt artifact requires:

- one top-level title
- Objective
- Input
- Instructions
- Output

Missing required sections shall fail validation.

Stable error codes shall include:

- `missing-objective`
- `missing-input`
- `missing-instructions`
- `missing-output`

Recommended and optional sections shall not fail validation.

Recommended and optional sections shall not produce validation warnings.

---

### REQ-007 — Prompt Statistics

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

Prompt artifacts shall be counted separately from Requirements, Decisions, and Roadmaps.

Human output shall include Prompt counts when present.

Example:

```text
Artifacts

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

JSON output shall include Prompt statistics additively.

Example:

```json
{
  "prompts": {
    "count": 5
  }
}
```

Prompt support shall not modify existing Requirement, Decision, or Roadmap totals.

---

### REQ-008 — Prompt Improvement

`rac improve` shall support Prompt artifacts through existing schema guidance.

Improvement shall remain generic and schema-driven.

Example:

```bash
rac improve prompt.md
```

Output:

```text
Artifact Type: Prompt

Missing Recommended:
- Constraints
- Examples
- Evaluation
```

Guidance examples:

```text
Missing Input:
- What information should the user provide?
- What source material should the model use?

Missing Constraints:
- What rules or limitations should the AI follow?

Missing Output:
- What should a successful response contain?
```

Prompt support shall not introduce prompt-specific improvement engines.

Avoid:

```python
if artifact.type == "prompt":
    improve_prompt()
```

The pipeline shall remain:

```text
ArtifactSpec
      ↓
generic improve engine
      ↓
artifact output
```

---

### REQ-009 — Prompt JSON Output

Prompt support shall be reflected in JSON outputs for:

- `rac schema prompt --json`
- `rac inspect prompt.md --json`
- `rac stats . --json`
- `rac improve prompt.md --json`

JSON output shall remain additive and backwards compatible where possible.

Section names shall use existing normalization:

- lowercase
- snake_case
- derived from Markdown headings

Example:

```text
Expected Output
```

normalizes to:

```text
expected_output
```

The Prompt schema uses `Output` as the canonical section name.

---

### REQ-010 — Prompt Repository Analysis

Prompt artifacts shall participate in existing repository-level analysis through `rac stats`.

This release shall support basic repository analysis only:

- count Prompt artifacts
- separate Prompt artifacts from Requirements, Decisions, and Roadmaps
- preserve existing artifact counts

This release shall not introduce prompt quality analysis, prompt comparison, prompt scoring, or prompt repository health metrics.

---

### REQ-011 — No Prompt Execution

RAC shall not execute prompts.

Prompt artifacts are treated as structured knowledge, not runnable AI workflows.

Not:

```bash
rac prompt run prompt.md
```

or:

```bash
rac run prompt.md
```

---

### REQ-012 — No AI Dependency

Prompt artifact support shall not require an AI service.

RAC shall inspect, validate, improve, template, and count Prompt artifacts using deterministic schema rules only.

There shall be:

- no network calls
- no API keys
- no model selection
- no provider-specific behavior

---

## Deferred Original Scope

This release intentionally defers parts of the original v0.7 Prompts roadmap that are subjective or belong to later RAC capabilities.

Deferred:

- identifying ambiguous instructions
- comparing prompt versions
- prompt quality scoring
- prompt optimization
- provider-specific prompt handling
- prompt repository health analysis

These capabilities may be revisited later, but they are not required to make Prompt a first-class artifact.

---

## Non-Goals

### Prompt Execution

Not:

```bash
rac prompt run requirement-review.md
```

RAC shall not run prompts against AI models.

---

### AI Integrations

No AI provider integrations are included.

Not:

- OpenAI
- Anthropic
- Gemini
- Local model execution

---

### Prompt Optimization

Not:

```text
Rewrite this prompt to perform better.
```

RAC shall not optimize prompt wording.

---

### Ambiguous Instruction Detection

Not:

```text
This prompt contains ambiguous instructions.
```

Ambiguity detection is subjective and out of scope for v0.6.2.

---

### Prompt Quality Scoring

Not:

```text
This prompt is weak.
```

RAC shall not score prompt quality.

---

### Prompt Version Comparison

Not:

```bash
rac diff prompt-a.md prompt-b.md
```

Prompt version comparison belongs to future diff/history work.

---

### Token Analysis

Not:

```text
This prompt is 1,200 tokens.
```

Token counting and context-window analysis are out of scope.

---

### Model-Specific Behavior

Not:

```text
This prompt is optimized for Claude.
This prompt is optimized for GPT.
This prompt is optimized for Gemini.
```

Prompt artifacts remain model-agnostic.

---

### Prompt Testing

Not:

```bash
rac prompt test prompt.md
```

Testing prompt outputs against models is out of scope.

---

### Chat History Storage

Prompt artifacts shall not store conversations, completions, responses, or execution history.

---

### Generated Output Tracking

Prompt artifacts shall not track generated outputs or AI results.

---

### Relationship Analysis

Optional sections such as Related Requirements, Related Decisions, and Related Roadmaps may be represented structurally.

However, v0.6.2 shall not parse, validate, resolve, or analyze relationships.

Relationship analysis belongs to v0.7.x.

---

## Success Metrics

### Functional

- Prompt is registered as an `ArtifactSpec`.
- Prompt files classify correctly.
- Invalid but recognizable Prompt files receive Prompt-specific validation errors.
- Existing Requirement, Decision, and Roadmap classification behavior remains unchanged.
- `rac validate` supports Prompt artifacts.
- `rac inspect` supports Prompt artifacts.
- `rac stats` counts Prompt artifacts separately.
- `rac schema prompt --template | rac validate -` passes.
- `rac improve` supports Prompt artifacts through schema guidance.
- No AI provider behavior exists.
- No prompt execution behavior exists.

### Product

Users can store and review prompts as structured, version-controlled knowledge artifacts.

Users can create a structurally valid Prompt artifact using:

```bash
rac schema prompt --template
```

Users can understand whether a Prompt artifact contains objective, input, instructions, output, constraints, examples, and evaluation criteria without manually comparing against an external template.

---

## Risks

### Risk: RAC Becomes a Prompt Management Platform

Prompt support could pull RAC toward prompt libraries, prompt marketplaces, model comparison, execution tracking, or optimization scoring.

Mitigation:

Keep Prompt artifacts focused on product knowledge.

Do not introduce:

- prompt libraries
- prompt marketplaces
- model comparison
- optimization scoring
- execution tracking

---

### Risk: Prompt Support Creates AI Dependency

Because Prompt artifacts describe AI instructions, there is a risk that RAC begins depending on AI services.

Mitigation:

Maintain ADR-002.

Prompt support shall require:

- no network calls
- no API keys
- no model dependencies

Prompt artifacts remain plain Markdown.

---

### Risk: Artifact-Specific Logic Grows

Prompt support could introduce prompt-only validators, renderers, or improvement engines.

Mitigation:

Prompt must use the same architecture as Requirements, Decisions, and Roadmaps.

Any new behavior should improve the artifact system, not create Prompt-only paths.

---

## Assumptions

Prompts are source artifacts, not runtime artifacts.

A Prompt describes:

- objective
- input
- instructions
- output
- constraints
- examples
- evaluation criteria

A Prompt does not store:

- conversations
- completions
- model responses
- execution metadata

Relationship sections are structural only until v0.7.x relationship support.

Prompt artifacts may later participate in relationships such as:

- Prompt generated Requirement
- Prompt reviewed Decision
- Prompt supports Roadmap

but v0.6.2 does not implement relationship parsing.

---

## Acceptance Criteria

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

includes:

```text
prompt
```


```bash
rac schema prompt
```

displays the Prompt schema.

```bash
rac schema prompt --json
```

returns the Prompt schema as structured JSON.

```bash
rac schema prompt --template
```

emits a structurally valid Prompt starter template.

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

passes.

```bash
rac inspect prompt.md
```

classifies the file as a Prompt artifact.

```bash
rac validate prompt.md
```

validates required Prompt sections.

```bash
rac improve prompt.md
```

reports missing required and recommended Prompt sections with guidance.

```bash
rac stats .
```

counts Prompt artifacts separately from Requirements, Decisions, and Roadmaps.

Prompt support does not require AI services.

Prompt support does not execute prompts.

No model-specific behavior is introduced.

No files are modified.

Existing Requirement, Decision, and Roadmap behavior remains unchanged.

---

## Future Considerations

Future releases may introduce:

- Prompt relationship analysis
- Prompt-to-requirement links
- Prompt-to-decision links
- Prompt-to-roadmap links
- Prompt review workflows
- Prompt testing through optional external systems
- Prompt libraries built outside RAC Core
- Deterministic prompt linting, if clear non-subjective rules emerge
- Prompt diff/history support

These capabilities should build on Prompt artifacts without making AI execution part of RAC Core.
