--- name: requirements description: Use when the user wants to extract F1 functional and non-functional requirements from a Discovery business proposal plus ready shared project inputs. Creates one Markdown item file per RF/RNF under docs/discovery//requirements/items/, maintains requirements/index.json, and assembles requirements/requirements.md. Triggers on "/machine-discovery:requirements ", "/requirements ", and requests to extract RF/RNF for Discovery. --- # Requirements Extract RF/RNF for F1 Discovery. This skill turns the Discovery proposal and ready shared inputs into individual requirement item artifacts, an index, and a consolidated requirements document. ## Inputs Required: ```text docs/discovery//inputs/business-proposal.md docs/inputs//index.json ``` Optional evidence: ```text docs/inputs//transcriptions/.md ``` Only `inputs[]` entries with `status: ready` are read. Failed and ignored inputs MUST be skipped. ## Outputs ```text docs/discovery//requirements/ index.json requirements.md items/ RF-001.md RNF-001.md ``` `requirements/index.json` and `requirements/items/*.md` are the source of truth. `requirements/requirements.md` is a consolidated document assembled from the item files. ## Requirement index contract `docs/discovery//requirements/index.json`: ```json { "project": "", "requirements": [] } ``` Each entry MUST use this shape: ```json { "id": "RF-001", "kind": "FR", "title": "Registrar cliente", "module": "Gestion de clientes", "md": "items/RF-001.md", "sources": ["business-proposal", "raw/notas.md"], "status": "draft" } ``` `kind` MUST be `FR` for functional requirements and `NFR` for non-functional requirements. IDs MUST be `RF-###` for `FR` and `RNF-###` for `NFR`. `module` MUST be a short functional module/area label (the doc requires RF grouped by module/area); if no module is evidenced, use `NEEDS INPUT: `. ## Operating protocol 1. Parse `$ARGUMENTS` and resolve the output language. - The first token MUST be a kebab-case ASCII project slug. - A second token MAY be `es` or `en`; if present, it wins. - If a second token is present and is not `es` or `en`, stop with `NEEDS INPUT: language must be es or en`. - If no language argument is present, inherit `language` from `inputs/business-proposal.md`; if missing, use the current user request language; if ambiguous, default to `es`. - If missing or invalid, stop with `NEEDS INPUT: indica el project slug, por ejemplo /machine-discovery:requirements acme-demo`. 2. Validate prerequisites: - `docs/discovery//inputs/business-proposal.md` MUST exist, be readable, and be non-empty. - `docs/inputs//index.json` MUST exist, be valid JSON, have `project` equal to the slug, and have `inputs` as an array. - Every ready input entry MUST have a readable `md` path relative to `docs/inputs//`. 3. Ensure these directories exist: - `docs/discovery//requirements/` - `docs/discovery//requirements/items/` 4. Read or initialize `requirements/index.json`. - If missing, create the empty index contract. - If present, validate `project`, `requirements` array, every `id`, every `kind`, and every `md`. - If an indexed requirement file is missing, stop and ask whether the user wants to restore it or intentionally remove the index entry. 5. Build the evidence set: - Always include the business proposal as source key `business-proposal`. - Include every ready shared input by its `src`. - Preserve concrete phrases, facts, constraints, actors, dates, numbers, and decisions. Do not invent missing facts. 6. Extract candidate requirements: - Functional (`FR`): system behavior, user workflow, business workflow, data operation, integration, notification, role permission, report, or automation. - Non-functional (`NFR`): performance, security, availability, reliability, compliance, accessibility, observability, scalability, portability, usability, data retention, or operational constraint. 7. Reuse existing requirements before adding new ones: - Normalize by `kind` + lowercase title without punctuation. - If a candidate matches an existing indexed requirement, reuse its ID and do not rewrite its file. - If a candidate is materially different, allocate the next ID in its sequence. 8. For each new requirement, select the template by `kind`: - `FR` → `templates/requirement..md.tmpl` - `NFR` → `templates/requirement-nfr..md.tmpl` Then: - Write a temporary content file beside the item output: `items/.blocks`. - The content file MUST contain one `@@KEY@@` block for each placeholder in the selected template, including `@@LANG@@`. - Fill all content blocks. Unknown information MUST be written as `NEEDS INPUT: `. - Assign a `@@MODULE@@`: a short module/area label that groups related requirements (e.g. `Gestion de clientes`, `Facturacion`). Reuse the same label across requirements of the same area. If none is evidenced, write `NEEDS INPUT: `. - Assign `@@PRIORITY@@` from the fixed scale — `es`: `Alta | Media | Baja`; `en`: `High | Medium | Low`. The field MUST NOT be empty and MUST be a scale value. When priority cannot be inferred from evidence, use `Media`/`Medium` and record the assumption under open questions. - For `FR` only: acceptance criteria MUST be numbered `AC--01`, `AC--02`, etc.; business rules MUST be numbered `BR--01`, `BR--02`, etc., or `N/A` when none are evidenced. - For `NFR` only: set `@@CATEGORY@@` to a category such as performance, security, availability, reliability, compliance, accessibility, observability, scalability, portability, usability, or data retention; set `@@VERIFICATION_CRITERION@@` to a verifiable condition, or `NEEDS INPUT: ` when none is evidenced. - Run `bash plugins/machine-discovery/scripts/assemble-doc.sh plugins/machine-discovery/skills/requirements/templates/ docs/discovery//requirements/items/.blocks docs/discovery//requirements/items/.md`. - Delete the `.blocks` file only after the assembled Markdown is validated. 9. Update `requirements/index.json`: - Preserve existing entries and order. - Append new entries in ID order. - Every entry MUST include `module` (same label used in the item file). - `sources` MUST include `business-proposal` and any ready input `src` used as evidence. - `md` MUST be relative to `docs/discovery//requirements/` and MUST point to `items/.md`. 10. Assemble `requirements/requirements.md`: - Write `docs/discovery//requirements/requirements.blocks`. - The content file MUST include `@@LANG@@` with the resolved language. - Run `bash plugins/machine-discovery/scripts/assemble-doc.sh plugins/machine-discovery/skills/requirements/templates/requirements..md.tmpl docs/discovery//requirements/requirements.blocks docs/discovery//requirements/requirements.md`. - Include a project overview section. - Include every indexed RF and RNF by reading the item file referenced by `md`. - In the `@@FUNCTIONAL_REQUIREMENTS@@` block, GROUP functional requirements by `module` (one subsection per module/area); within each module preserve index order. Non-functional requirements stay in their own section. - Do not invent content not present in the item files. - Delete `requirements.blocks` only after validating the assembled Markdown. 11. Score against [references/checklist.md](references/checklist.md). Pass criterion: 14/14. 12. Final report MUST print exactly `/machine-discovery:hla ` as the next-step suggestion. ## Hard rules - **Proposal required.** Do not run from shared inputs alone. `business-proposal.md` is the F1 starting point. - **Only ready sources.** Ignore failed or ignored shared inputs. - **One item file per requirement.** Every RF/RNF MUST have exactly one file under `requirements/items/`. - **Consolidated document required.** `requirements/requirements.md` MUST be generated from the item files after the index is updated. - **Script-owned Markdown.** Final requirement Markdown files MUST be assembled by `scripts/assemble-doc.sh` from `.blocks` files and templates. - **Selected-language output.** Generated titles, body prose, and template-owned headings MUST match the resolved output language; verbatim source quotes stay unchanged. - **Stable placeholders.** Keep block markers and template placeholders unchanged across localized templates. - **Kind is mandatory.** Every requirement index entry MUST declare `kind: "FR"` or `kind: "NFR"`. - **NFR template.** Non-functional requirements MUST be assembled with `requirement-nfr..md.tmpl` (category + verification criterion), never the FR template. FR MUST use `requirement..md.tmpl`. - **Priority from scale.** Every requirement MUST set priority to a scale value (`Alta|Media|Baja`, or `High|Medium|Low` in `en`). Empty or free-text priority is forbidden. - **Module grouping required.** Every requirement MUST declare a `module`/area in its index entry and item file; `requirements.md` MUST group functional requirements by module, never as a flat list. - **No duplicate IDs.** RF and RNF sequences MUST be independent and monotonically increasing. - **No silent overwrite.** Existing requirement files MUST NOT be overwritten unless the user explicitly asked to regenerate them. - **Traceability required.** Every requirement MUST cite at least one source key in the index and in the Markdown file. - **No auto-chaining.** Suggest `/machine-discovery:hla ` after success, but do not run it. ## References - FR templates: [templates/requirement.es.md.tmpl](templates/requirement.es.md.tmpl), [templates/requirement.en.md.tmpl](templates/requirement.en.md.tmpl) - NFR templates: [templates/requirement-nfr.es.md.tmpl](templates/requirement-nfr.es.md.tmpl), [templates/requirement-nfr.en.md.tmpl](templates/requirement-nfr.en.md.tmpl) - Consolidated requirements templates: [templates/requirements.es.md.tmpl](templates/requirements.es.md.tmpl), [templates/requirements.en.md.tmpl](templates/requirements.en.md.tmpl) - Quality checklist: [references/checklist.md](references/checklist.md) - Anti-patterns: [references/anti-patterns.md](references/anti-patterns.md)