import-spec-file

What this skill does

# /shipyard:import-spec-file - Import Handwritten Spec Document

You are executing the Shipyard spec-file import workflow. This is the path for handwritten, freeform, or pre-existing specification documents — use this instead of `/shipyard:brainstorm` when a spec already exists in a non-spec-kit format. Follow these steps precisely.

<prerequisites>

## Step 1: Parse Argument

- If an argument is provided, treat it as the spec file path. Resolve relative paths from the project root (cwd). Absolute paths are used as-is.
- If no argument is provided, check for common spec file patterns in the project root and one level deep:
  - Files matching `*spec*.md`, `*SPEC*.md`, `*requirements*.md`, `*design*.md`
  - If exactly one match: offer to use it. Ask: "Found `<path>`. Use this as the spec?"
  - If multiple matches: use `AskUserQuestion` to present the matches and ask the user to select one.
  - If no matches: tell the user: "No spec file found. Provide the path as an argument: `/shipyard:import-spec-file path/to/spec.md`" and stop.

## Step 2: Validate Prerequisites

1. Verify `.shipyard/` directory exists. If not, tell the user to run `/shipyard:init` first, then stop.
2. Verify the spec file exists and is readable. If not, tell the user: "Spec file not found: `<path>`" and stop.
3. Note the spec file's filename, directory, and size (line count) for use in later steps.

## Step 3: Check Existing PROJECT.md

If `.shipyard/PROJECT.md` already exists, use `AskUserQuestion` to ask:
> "A project definition already exists in `.shipyard/PROJECT.md`. What would you like to do?"
- `Replace with spec import (Recommended)` — overwrite PROJECT.md with content derived from the spec
- `Merge — update requirements section only` — keep existing PROJECT.md but replace the Requirements section with content from the spec
- `Cancel` — stop

</prerequisites>

<execution>

## Step 4: Read, Analyze, and Interview

Read the full spec file. Then analyze its structure to identify the following sections (the document may use any section names — use judgment to identify the semantic equivalent):

| PROJECT.md section | Look for in the spec |
|---|---|
| **Project Name** | Document title (first `#` heading), filename, or explicit name field |
| **Description** | Overview, Introduction, Summary, Purpose, Background, Scope sections |
| **Goals** | Goals, Objectives, Features, Intended behavior summary, What this covers |
| **Non-Goals** | Non-Goals, Out-of-Scope, Exclusions, What this does not cover |
| **Requirements (Functional)** | Requirements, Rules, Validation rules, Behavior specification, Protocol, Acceptance criteria |
| **Non-Functional Requirements** | Performance, Security, Scale, Reliability, Compliance, Non-functional constraints |
| **Success Criteria** | Test scenarios, Acceptance tests, Examples, Verification cases |
| **Constraints** | Assumptions, Constraints, Limitations, Dependencies, Technology choices, Deviations |
| **Open Questions** | Open questions, TBD, TODO, Unresolved items, `[NEEDS CLARIFICATION]` markers, flagged gaps |

**Mapping rules:**

- **Project Name**: use the first `#` heading; if absent, derive from the filename (e.g., `amver-validation-spec.md` -> `AMVER Validation`)
- **Description**: synthesize 1-2 paragraphs from the spec's overview/purpose prose; do not copy verbatim — write a summary that orients a new engineer
- **Goals**: each top-level capability or major section of behavior becomes a numbered goal; for rule-set specs, goals are the major categories of validation (e.g., "Structural validation", "Content validation", "Wire format handling")
- **Non-Goals**: extract explicit exclusions; if none present, write "Not explicitly defined in spec"
- **Requirements (Functional)**: for each major section or rule category in the spec, create a `### [Section Name]` subsection with bullet points derived from the rules. For rule-set specs with identifiers (e.g., VR-WF-1, VR-STR-4), group by category and summarize each rule as a requirement bullet. Do NOT copy rules verbatim — write them as requirement statements.
- **Non-Functional Requirements**: extract security notes, performance constraints, encoding requirements, compliance notes
- **Success Criteria**: derive from test scenarios, example inputs/outputs, or scenario tables in the spec. If no explicit test cases exist, write: "To be defined — see spec scenarios in RESEARCH.md"
- **Constraints**: extract all explicit assumptions, technology choices (e.g., "Rust regex crate"), deviations from prior behavior, and encoding requirements. Each becomes a constraint bullet.
- **Open Questions**: extract every item the spec marks as unresolved, flagged, or requiring confirmation. Include section references.

**After analyzing the spec, conduct a gap-filling interview before writing PROJECT.md.**

Identify which of the following are missing, ambiguous, or incomplete in the spec:
- Goals / intended scope
- Non-Goals (what is explicitly excluded)
- Success criteria or acceptance tests
- Non-functional requirements (performance, security, scale)
- Deployment or integration context (what system uses this? what calls it?)
- Known deviations from prior behavior or existing implementation

For each gap found, ask the user directly. Keep questions focused — one topic per question. Do not ask about things the spec already covers clearly. Aim for 2-5 questions total; stop when you have enough to write a complete PROJECT.md.

Invoke the `shipyard:shipyard-brainstorming` skill to guide this dialogue. Frame questions around the spec content — e.g., "The spec defines validation rules but doesn't describe where this library gets called from. Is it embedded in the report-service, or is it a standalone library?"

Continue until the user confirms they are satisfied or there are no remaining gaps.

**Handle open questions**: If the spec contains unresolved items (open questions section, TBD markers, `[NEEDS CLARIFICATION]` tags, or explicit "requires verification" language), surface these during the interview and let the user clarify or acknowledge them as open. Count remaining unresolved items after the interview for the Open Questions section.

**Write `.shipyard/PROJECT.md`** using this structure:
```markdown
# [Project Name]

> Imported from: `[spec file path]` on [date]

## Description
[1-2 paragraphs]

## Goals
1. [Major goal / capability]
2. [Major goal / capability]
...

## Non-Goals
- [explicit exclusions or "Not explicitly defined in spec"]

## Requirements

### [Major Section / Category Name]
- [requirement derived from spec rule or behavior]
- [requirement derived from spec rule or behavior]

### [Next Category]
...

## Non-Functional Requirements
- [security, performance, encoding, compliance constraints]

## Success Criteria
- [from test scenarios or derived verification statements]

## Constraints
- [from assumptions, technology choices, deviations, encoding requirements]

## Open Questions
- [unresolved spec items with section references]
```

## Step 5: Stage the Spec as a Research Artifact

Create the phase 1 directory and copy the spec file as the primary research artifact:

```bash
mkdir -p .shipyard/phases/1
```

Copy the spec file to `.shipyard/phases/1/RESEARCH.md`:
```bash
cp <spec-file-path> .shipyard/phases/1/RESEARCH.md
```

If the spec file is very large (>500 lines), prepend a navigation header to RESEARCH.md:
```markdown
# Research: [Project Name]

> Source: `[original spec file path]`
> This document is the full specification imported via `/shipyard:import-spec-file`.
> See `.shipyard/PROJECT.md` for the synthesized project definition.

---

[original spec contents follow]
```

## Step 6: Generate ROADMAP.md

Check if `.shipyard/ROADMAP.md` already exists.

**If ROADMAP.md does not exist (or user chose Replace in Step 3):**

Follow **Model Routing Protocol** (select the correct model for each agent role using `model_routing` from config; see `docs/PROTOCOLS.md`) — read `model_routing` fr