---
schema_version: 1
id: RAC-KTQ63DVQYZ6S
type: requirement
---
# RAC v0.4.1 — Inspection Expansion

## Context

v0.4.0 introduced `rac inspect <file>`.

Users can classify a single Markdown document and determine:

- Artifact type
- Confidence
- Present sections
- Missing sections

However, inspection currently operates on individual files only.

Users cannot understand repository composition, inspect collections of artifacts, or determine why a document was classified in a particular way.

Additionally, minor heading variations can reduce classification accuracy despite documents being structurally equivalent.

v0.4.1 expands inspection to support repository-level analysis, classification transparency, and heading synonyms while remaining deterministic and AI-optional.

This release supports inspection of:

- Requirement artifacts
- Decision artifacts

Roadmap, Prompt, and Meeting artifacts remain out of scope and shall be classified as Unknown.

---

## Problem

Inspection currently operates on a single file.

Users cannot easily determine:

- What artifacts exist across a repository
- How many artifacts of each type exist
- Why a document was classified a particular way

Additionally, documents that use alternative but equivalent headings may be classified incorrectly despite following the same structure.

---

## Goals

Expand inspection to support:

- Repository-level inspection
- Classification transparency
- Heading synonym support

for the following artifact types:

- Requirement
- Decision

while remaining:

- Read-only
- Deterministic
- AI-optional

---

## Requirements

### REQ-001 — Directory Inspection

The system shall support:

```bash
rac inspect <directory>
```

and inspect all Markdown files within the specified directory.

Directory inspection shall be recursive by default.

---

### REQ-002 — Non-Recursive Inspection

The system shall support:

```bash
rac inspect <directory> --no-recursive
```

to inspect only files within the specified directory.

Subdirectories shall not be traversed.

---

### REQ-003 — Recursive Compatibility

The system shall support:

```bash
rac inspect <directory> --recursive
```

for compatibility and documentation consistency.

This flag shall have no effect because recursive inspection is the default behavior.

---

### REQ-004 — Repository Summary

Directory inspection shall produce artifact counts.

Supported artifact types:

- Requirement
- Decision
- Unknown

Example:

```text
Requirements: 12
Decisions: 8
Unknown: 2
```

---

### REQ-005 — Repository JSON Output

Directory inspection shall support:

```bash
rac inspect <directory> --json
```

and return structured machine-readable output.

Example:

```json
{
  "directory": "rac",
  "recursive": true,
  "total_files": 22,
  "counts": {
    "requirement": 12,
    "decision": 8,
    "unknown": 2
  },
  "files": [
    {
      "path": "adr/adr-001.md",
      "type": "decision",
      "confidence": 0.88
    }
  ]
}
```

Only Requirement and Decision artifacts shall be classified in v0.4.1.

All other documents shall be reported as Unknown.

---

### REQ-006 — Verbose Inspection

The system shall support:

```bash
rac inspect file.md --verbose
```

and display classification details.

Example:

```text
Decision

Matched Required
✓ Context
✓ Decision
✓ Consequences

Matched Recommended
✓ Status

Missing
✗ Alternatives Considered

Confidence
3.5 / 4.0 = 0.88
```

---

### REQ-007 — Section Synonyms

Classification shall support heading synonyms.

Examples:

```text
Success Criteria → Success Metrics
KPIs → Success Metrics
Alternatives → Alternatives Considered
Options Considered → Alternatives Considered
```

Matching shall be deterministic and case-insensitive.

---

### REQ-008 — Confidence Transparency

Verbose output shall expose the confidence calculation used during classification.

---

### REQ-009 — Backwards Compatibility

Existing inspection behavior shall remain unchanged.

Single-file inspection output and JSON schemas introduced in v0.4.0 shall remain compatible.

---

## Non-Goals

### Additional Artifact Types

Not:

- Roadmap
- Prompt
- Meeting

These artifact types are deferred to future releases.

Documents matching these structures shall be classified as Unknown.

---

### Improvement Guidance

Not:

```bash
rac improve file.md
```

This capability belongs to v0.5.x.

---

### Relationship Analysis

Not:

```bash
rac relationships .
```

This capability belongs to future releases.

---

### AI Classification

Not:

```text
This appears to be a roadmap.
```

based on semantic analysis.

Classification shall remain schema-based and deterministic.

---

## Success Metrics

### Functional

- Repository inspection operates recursively by default.
- Repository counts are accurate.
- Verbose output explains classifications.
- Synonym support improves classification accuracy.
- Existing v0.4.0 workflows continue to function unchanged.

### Product

Users can understand repository composition without opening individual files.

Users can understand why an artifact was classified a certain way.

---

## Risks

- Synonym expansion may introduce ambiguity.
- Large repositories may produce lengthy JSON output.
- Users may incorrectly assume verbose output changes classification behavior.

---

## Acceptance Criteria

```bash
rac inspect rac/
```

returns repository counts for:

- Requirement
- Decision
- Unknown

```bash
rac inspect rac/ --json
```

returns counts and per-file classifications.

```bash
rac inspect decision.md --verbose
```

shows matched sections and confidence calculations.

```bash
rac inspect rac/ --no-recursive
```

limits inspection scope.

A document using:

```markdown
## Success Criteria
```

is classified equivalently to:

```markdown
## Success Metrics
```

Roadmap, Prompt, and Meeting artifacts are reported as Unknown.

Existing v0.4.0 inspection workflows continue to operate unchanged.