/import-spec-file

name: import-spec-file
description: Import a handwritten spec document into Shipyard, replacing brainstorming. Use when a freeform spec, requirements, or design document exists.
argument-hint: "[file-path] — path to a spec document (e.g. docs/my-spec.md or /abs/path/spec.md)"

/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-ser