plan-from-spec

name	plan-from-spec
description	Add or update the implementation_plan section inside an approved executable spec.yml with traceability to scenarios, acceptance criteria, and tests
user-invocable	true
argument-hint	docs/specs/<slug>/spec.yml

Instructions

You are turning an approved executable product spec into a technical implementation plan inside the same spec.yml. This is still pre-code work. Do not edit product source files during this skill.

Step 1: Read The Spec And Guide

Read:

1. The provided docs/specs/<slug>/spec.yml
2. docs/contributing/guides/spec-driven-development.md
3. Relevant architecture docs and existing source patterns referenced by the spec

If the argument is missing or does not point to a spec file, ask for the spec path.

Step 2: Validate Spec Readiness

Before writing the plan, confirm the spec has:

• At least one scenario ID (S-*)
• At least one acceptance criterion ID (AC-*)
• Scope and non-goals
• Tests with assertions and red/green phase metadata
• Required assumptions are confirmed, corrected, waived, blocked with a user or external dependency, or explicitly scheduled for pre-implementation checking
• Required acceptance criteria have coverage_status, verification_scope, and verification_ids when the spec is ready for implementation

Run:

python3 scripts/spec_validate.py docs/specs/<slug>/spec.yml

If these are missing, stop and run or recommend specify first.

Step 3: Create The Plan

Create or update the implementation_plan key inside:

docs/specs/<slug>/spec.yml

The plan must include:

• Link to the spec
• Existing patterns and files to reuse
• Technical architecture and boundaries
• Data flow walkthrough with concrete example values
• API/data/UI/privacy/security impacts
• Affected files with reason for each
• Migration/backfill/rollout needs if any
• Observability/logging needs if any
• Verification strategy with exact test commands where known
• Required assumptions that must be checked before implementation and which source areas or subagents should verify them
• required assumptions must not be left unchecked when they block implementation
• Acceptance-criteria coverage mapping: each required AC must map to concrete verification_ids, a user-confirmed/manual check, a waiver path, or a blocker
• Open questions and risks

Step 4: Keep The Plan Minimal

Avoid speculative architecture. Prefer the smallest vertical slice that can prove the first scenario. For large features, explicitly identify the first slice.

If a plan has vague criteria such as "all tests pass" or "no regressions", do not leave them as final checks. Normalize them into concrete scoped checks such as backend pytest, CLI, npm SDK, pip SDK, Playwright, Apple build/test, full CI, manual review, or user confirmation.

Step 5: Output Summary

Report:

Plan: docs/specs/<slug>/spec.yml#implementation_plan
First slice: <short description>
Main files likely touched: <paths>
Verification: <tests or planned tests>
Validation: <spec_validate result>
Next: run `tasks-from-spec docs/specs/<slug>/spec.yml`

Rules

• Do not write implementation code during this skill.
• Every plan section must trace back to scenario or acceptance-criteria IDs.
• Prefer existing utilities, components, providers, schemas, and architecture.
• If a plan requires a risky dependency, schema, privacy, or auth decision not present in the spec, stop and ask.