# Skill Spec Product

> Generador de especificaciones de producto en YAML. Unico proposito: crear, estructurar y validar archivos .yml de historias de usuario. No edita codigo fuente.

- Skill: `leifermendez/skill-spec-product` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add leifermendez/skill-spec-product`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leifermendez/skill-spec-product/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: leifermendez (https://skillmd.com/u/leifermendez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leifermendez/skill-spec-product

---


# skill-spec-product

PROPOSITO UNICO DE ESTE SKILL: Crear, generar y validar archivos YAML de especificacion de producto.
Este skill NO edita, modifica, compila ni genera codigo fuente. Su unico entregable son archivos .yml.

Product Spec-Driven Delivery is a requirements-first workflow where YAML user stories are the single source of truth for product teams. Every feature request traces back to a spec. Every acceptance criterion is verifiable. Every handoff to engineering is complete.

This skill guides product teams through a 5-phase process from raw intake to a validated handoff package. The output of every phase is a set of structured YAML files.

---

## The 5 Phases

| Phase | Name | Tracker / Milestone | Deliverable |
|---|---|---|---|
| **01** | Discovery & Intake | Requirements Package Complete | Spec folders in `spec-product/`, Stakeholder Map |
| **02** | Prioritization | Roadmap Defined | Prioritized backlog (RICE/WSJF), Quarter roadmap |
| **03** | Specification | Specs Ready for Review | Detailed user stories with acceptance criteria, flows, metrics |
| **04** | Validation | Stakeholder Sign-Off | Approved specs, risk assessment, go/no-go decision |
| **05** | Handoff Package | Engineering Ready | Complete delivery package: specs, context, success criteria |

**Rule:** Do not begin a phase until the previous phase's `Exit Criteria` are fully satisfied. The agent executing this skill must verify the checklist before advancing.

---

## Pre-flight Check

Before starting any phase, run the spec validator and inspect the project root:

```bash
bash references/validate-specs.sh
```

1. The validator checks if `spec-product/` exists and creates it if missing.
2. If it exists:
   - Lists all subdirectories: `feat-XXXX-dd-mm-yy-hh-mm/`
   - Identifies the most recent by directory name timestamp
   - Reads the `feat-XXXX.yml` inside the most recent folder for context
   - Records the highest sequential ID to continue numbering from there
3. Validate: no gaps in ID sequence unless explicitly documented.

---

## Spec Folder & File Naming Convention

**Folder Format:** `spec-product/feat-XXXX-dd-mm-yy-hh-mm/`

- `XXXX`: Sequential 4-digit number (0001, 0002, ...). No gaps allowed.
- `dd-mm-yy-hh-mm`: Creation timestamp. 2-digit year.
- Example: `spec-product/feat-0001-15-05-26-14-30/`

**File Format (inside folder):** `feat-XXXX.yml` (archivo principal)

- Archivo principal: solo el ID, sin timestamp ni slug descriptivo.
- Se permite incluir archivos YAML adicionales relacionados con la misma feature (por ejemplo, discovery, especificacion, validacion, handoff).
- Todos los archivos `.yml` de una feature deben vivir dentro de su carpeta `feat-XXXX-.../`.
- Example:
  - `spec-product/feat-0001-15-05-26-14-30/feat-0001.yml`
  - `spec-product/feat-0001-15-05-26-14-30/feat-0001-discovery.yml`
  - `spec-product/feat-0001-15-05-26-14-30/feat-0001-handoff.yml`

---

## Post-phase Verification

After completing any phase, run the spec validator:

```bash
bash references/validate-specs.sh
```

Then verify manually:

1. List all `spec-product/feat-*/` directories created in this phase.
2. For each directory, verify:
   - [ ] Directory name follows `feat-XXXX-dd-mm-yy-hh-mm/` format
   - [ ] Directory contains at least the archivo principal: `feat-XXXX.yml`
   - [ ] Todos los archivos `.yml` dentro del directorio son YAML validos y no vacios
   - [ ] El archivo principal (`feat-XXXX.yml`) tiene los campos requeridos: id, type, as_a, i_want, so_that, product, metadata.created_at
   - [ ] `metadata.created_at` en el archivo principal coincide con el timestamp del directorio (dd-mm-yy-hh-mm)
   - [ ] ID en YAML del archivo principal coincide con el ID del directorio
3. If any check fails:
   - Do NOT proceed to the next phase
   - Report the exact failure
   - Fix before continuing

---

## Final Verification

After Phase 05 complete:

1. Inventory all `spec-product/feat-*/` directories.
2. Verify no orphaned IDs (gaps in sequence without documented reason).
3. Verify all P0/P1 stories have status `approved` or `done`.
4. Verify timestamps in directory names are chronologically ordered by ID.
5. Emit summary:
   - Total specs created
   - P0 count / P1 count / P2+P3 count
   - Timestamp range (first → last)
   - Coverage % of acceptance criteria

---

## Quick Start

1. Run **Pre-flight Check** above.
2. Load `references/phase-01-discovery-and-intake.md` and collect requirements.
3. When `Exit Criteria` pass, run **Post-phase Verification**, then load `references/phase-02-prioritization.md`.
4. Continue sequentially through all 5 phases, running **Post-phase Verification** after each.
5. After Phase 05, run **Final Verification**.

---

## Phases

- [Phase 01: Discovery & Intake](references/phase-01-discovery-and-intake.md)
- [Phase 02: Prioritization](references/phase-02-prioritization.md)
- [Phase 03: Specification](references/phase-03-specification.md)
- [Phase 04: Validation](references/phase-04-validation.md)
- [Phase 05: Handoff Package](references/phase-05-handoff-package.md)

---

## References

- [Risk Matrix](references/risk-matrix.md) - Risk identification & mitigation
- [Tools](references/tools.md) - Recommended software per phase
- [Books](references/books.md) - Essential reading for product managers
- [Spec Validator](references/validate-specs.sh) - Bash script to validate `spec-product/` structure and YAML contents
- [User Story Templates README](references/user-story-templates-README.md) - YAML schema & examples
  - [Discovery Template](references/feat-001-discovery.yml)
  - [Feature Template](references/feat-002-user-registration.yml)
  - [Pain Point Template](references/feat-003-manual-invoicing.yml)

---

## Core Principles

1. **Este skill genera specs en YAML** - No implementa features, no escribe codigo, no crea branches ni hace deploys. Su unico output son archivos .yml.
2. **Specs are the contract** - YAML user stories are the agreement between product and engineering.
3. **Traceability** - Every spec has an ID that follows the feature through design, development, and release.
4. **Acceptance criteria are non-negotiable** - If it cannot be verified, it is not a criterion.
5. **Start with the problem, not the solution** - Specs must articulate the user need before proposing features.
6. **Decisions are documented** - Priority changes, scope cuts, and trade-offs are recorded.
7. **Handoff is a package, not a meeting** - Engineering receives complete context, not a bullet list.

---

**Build YAML specs that serve as the unambiguous contract between product and engineering.**