asdecided/core/v0-17-x-adoption

v0.17.0 — Single-Document Import Skill

Status

Achieved

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