---
schema_version: 1
id: RAC-KV3ZT2CXHG6G
type: roadmap
tags: [skills, onboarding, adoption]
---
# v0.17.0 — Single-Document Import Skill

## Status

Planned

## Context

A common adoption blocker is the on-ramp: new users have existing decisions in
Confluence, Notion, or loose Markdown and no guided way to get one into RAC
format. The `rac-ingest` skill converts and can mint identity across a whole
directory, but it is broad and unguided. This milestone adds a focused,
human-in-the-loop sibling for the most common first step — turning one existing
document into one valid artifact — opening the v0.17.x adoption series (the
import on-ramp, per-type standards, and CI distribution).

## Outcomes

- An agent in a host project has a bundled procedure to reshape exactly one
  existing document into one valid RAC artifact, with an explicit human-review
  step before any file is written and `rac validate` as the deterministic close.
- The skill adds no AI to RAC core: it proposes, the human ratifies, and the
  deterministic CLI checks. It reuses the released command surface only.
- The bundled skill set grows to four without weakening the install or
  byte-equality contracts.

## Initiatives

- Bundle `rac-import` alongside the existing skills, packaged identically
  (resource under `rac.skills`, byte-identical dogfood copy under
  `.claude/skills/`, per-skill sync test). Its procedure: take one document
  (paste or path); convert non-Markdown via `rac ingest`; choose the type and
  read its real shape with `rac schema <type>`; draft only from source content,
  flagging required sections the source does not cover; present the draft and
  require the user to confirm the type, title, and any relationships before
  writing; scaffold with `rac new` (which mints the id); then close on
  `rac validate`, offering fixes until it exits 0.
- Single-document by scope: the skill refuses a directory, a wiki, or several
  documents and points to `rac-ingest` for broader conversion. Relationships are
  suggestions the source itself names, each confirmed with `rac resolve` /
  `rac find` — never inferred by scanning the repository.
- Describe released CLI behaviour only: `rac ingest`, `rac schema`, `rac inspect`,
  `rac new`, `rac validate`, `rac resolve`, `rac find`. Normative-language
  conventions (BCP-14) are authoring guidance, not a check the skill claims,
  because `rac validate` does not enforce them yet.
- Document the on-ramp in the README ("Importing an existing decision") and
  refresh the skill list/install goldens for the new entry.

## Success Measures

- `rac skill install rac-import` writes `.claude/skills/rac-import/SKILL.md`;
  `rac skill list` enumerates it; re-running install exits 1 and writes nothing.
- The packaged skill is byte-identical to its dogfood copy (enforced by test).
- Following the skill, three realistic messy source documents (a decision, a
  requirement, a design) each produce an artifact that passes `rac validate`,
  faithful to the source with no invented facts.
- pytest, `rac validate rac/`, and `rac relationships rac/ --validate` pass.

## Assumptions

- Project-level skills (`.claude/skills/`) remain the documented discovery path.
- The host project has the `rac` CLI installed; the skill does not manage install.

## Risks

- Overlap with `rac-ingest` could confuse users. Mitigated: the descriptions and
  the skill body state the single-document, human-reviewed scope and cross-refer
  `rac-ingest` for broader conversion.
- Skill prose drifts from CLI behaviour as commands evolve; the sync tests catch
  drift between copies but not against the CLI itself.

## Related Decisions

- adr-003
- adr-007
- adr-021

## Related Requirements

- rac-growth-agent-skill
- rac-growth-adoption

## Related Roadmaps

- v0.10.5-review-and-ingest-skills
- v0.10.5-bundled-agent-skill
- v1.4-claude-skills
