Turn-Into-Spec Skill

Purpose: Transform existing design documents, Architecture Decision Records (ADRs), or rough plans into well-structured feature specifications following the project's spec template.

User Input

$ARGUMENTS

If the input above is empty, use AskUserQuestion to ask: "Please provide a file path to your design doc/ADR/rough plan, or paste the content directly."

Do not proceed until you have material to transform.

Stage 1: Load Source Material

Determine input type and load accordingly:

• File path (e.g., docs/adr/001-auth.md , plans/rough-plan.md ): Read the file using the Read tool.

• Inline text: Use the pasted content directly.

• Multiple files: Read each file and merge context.

Also load the spec template for reference:

plugins/Vengineer/skills/reference/spec_template.md

Stage 2: Analyze & Extract

Parse the source material and extract:

Element What to Look For

Feature Name Title, heading, or dominant topic

Actors Who uses this — users, admins, systems, services

Core Actions What users/systems do — verbs and flows described

Constraints Limitations, non-goals, scope boundaries

Success Signals Goals, KPIs, "done when" statements

Decisions Made ADR rationale, chosen approaches, rejected alternatives

Open Questions Unresolved items, TBDs, items marked for future

Data Entities Models, schemas, key objects mentioned

Note: Design docs and ADRs often contain implementation details (tech stack, APIs, framework choices). Strip these during extraction — the spec must remain implementation-agnostic.

Stage 3: Map to Spec Structure

Using the loaded spec template, map extracted content to spec sections:

Feature Name & Branch

• Derive a 2-5 word feature name from the document title or dominant theme

• Format branch name as ###-feature-name (use 000 if no issue number is known)

User Scenarios & Testing

For each distinct user flow found in the source:

• Write it as a plain-language user story

• Assign priority (P1 = core flow, P2 = important variant, P3 = edge/advanced)

• Define acceptance scenarios as Given/When/Then

Requirements

• Convert design decisions into FR-XXX: System MUST [capability] statements

• Each requirement must be testable and implementation-agnostic

• Mark anything unclear: [NEEDS CLARIFICATION: specific question]

• Hard limit: Maximum 3 [NEEDS CLARIFICATION] markers total

Key Entities

• List entities from the source, stripped of implementation details (no table schemas, ORM fields, or type annotations — just what the entity represents and its relationships)

Success Criteria

• Transform goals/KPIs from the source into measurable, technology-agnostic outcomes

• Format: SC-XXX: [Measurable metric from user/business perspective]

Edge Cases

• Surface any unresolved scenarios, failure modes, or boundary conditions mentioned in the source

Stage 4: Write the Spec

Write the completed spec to specs/<feature-name>.md using the template structure.

Quality rules (apply before writing):

• No implementation details: no framework names, language choices, database types, API paths, or infrastructure specifics

• Written for non-technical stakeholders — business language, not engineering jargon

• Every requirement is testable and unambiguous

• Success criteria are measurable and technology-agnostic

• All mandatory sections from the template are present

Stage 5: Handle Gaps & Clarifications

If [NEEDS CLARIFICATION] markers remain after writing:

• Limit check: Keep only the 3 most critical (by scope/security/UX impact). Make informed guesses for the rest.

• Present each clarification using AskUserQuestion with suggested options:

Question: [Topic from NEEDS CLARIFICATION marker]

Context: [Relevant quote from source material]

Options:

• Option A: [Description + implications]

• Option B: [Description + implications]

• Custom: provide your own answer

• Ask one question at a time.

• After all answers collected, update the spec and remove the markers.

Stage 6: Validate & Finalize

After all clarifications are resolved, do a final pass:

• Confirm all [NEEDS CLARIFICATION] markers are resolved or removed

• Confirm no implementation details leaked into the spec

• Confirm every acceptance scenario follows Given/When/Then format

• Confirm success criteria are measurable

Report the result: spec path, number of user stories, number of requirements, any remaining notes.

Stage 7: Next Steps

Use AskUserQuestion to present options:

Question: "Spec ready at specs/<feature-name>.md . What would you like to do next?"

Options:

• Run /core:plan — Generate implementation plan from this spec (Recommended)

• Run /core:clarify — Ask targeted questions to deepen the spec further

• Run /core:plan_review — Get feedback from specialized reviewers

• Edit spec — Open the spec file for manual review

• Done — No further action needed

Behavior Rules

• Never invent requirements not grounded in the source material — flag gaps instead

• Strip implementation details aggressively: the spec is about what and why, not how

• Preserve intent: when source material contains rationale (especially ADR context), surface it in user stories or edge cases rather than discarding it

• One question at a time when clarifying

• Respect existing decisions: if the source explicitly chose an approach, note it in context but do not encode the choice as a requirement