--- name: reversa-spec-sdd description: > Final agent of the Reversa Code New Project Agents team. Decomposes a PRD into logical components and generates SDD (Spec-Driven Development) specs per component, with automatic quality scoring. Use when the user types "/reversa-spec-sdd", "reversa-spec-sdd", or when invoked by the `/reversa-new` orchestrator. Reads `_reversa_sdd/prd.md` and produces `_reversa_sdd/sdd/.md`. On completion, hands off to `/reversa-forward`. Can also be used standalone to evaluate an existing spec (evaluation mode) or to generate a single spec from any input the user provides. Output: `.md` files in SDD format with a quality score (0 to 100) and gap analysis. license: MIT compatibility: Claude Code, Codex, Cursor, Gemini CLI, and other Agent Skills-compatible agents. metadata: author: pnocera version: "1.0.0" framework: reversa team: newproject stage: spec-sdd --- # reversa-spec-sdd, Spec-Driven Development in Reversa This skill drives the complete SDD process within the Code New Project Agents pipeline: **decompose → draft → evaluate → iterate** until each spec is ready for the forward cycle. The skill is a vendored version of the global `sdd-spec`, adapted to the Reversa context: reads `prd.md` as the primary source, writes to `_reversa_sdd/sdd/`, marks everything with seal 🟡, and ends with a handoff to `/reversa-forward`. ## Why SDD? Specs written before the code save time because they: - Make ambiguities visible before they turn into bugs - Align expectations between the requester and the implementer - Serve as a permanent reference for tests, reviews, and onboarding - Allow LLMs to implement with much greater precision The methodology here is **Pragmatic RFC plus LLM-First**: structured like an RFC (Problem / Goals / Design / Edge Cases), but optimized to be consumed by humans and AI agents alike. ## Before starting 1. Read `.reversa/state.json` for `user_name`, `chat_language`, `doc_language`, `output_folder` (default `_reversa_sdd`). 2. Check the precondition: **`/prd.md` must exist**. If absent, stop with a clear message: > "I could not find `/prd.md`. Run `/reversa-drafter` first, or invoke `/reversa-new` to run the complete pipeline." 3. Ensure the folder `/sdd/` exists. Create it if absent. ## Default output path Each generated spec goes to: ``` /sdd/.md ``` For example: `_reversa_sdd/sdd/user-authentication.md`, `_reversa_sdd/sdd/payment-checkout.md`. The component is decomposed from `prd.md` in the first phase. ## Mandatory seal 🟡 All items in specs generated by `reversa-spec-sdd` must use the seal **🟡 PLANNED** (a variant of 🟡 INFERRED used in other Reversa contexts). The seal 🟢 CONFIRMED is reserved for facts extracted from existing code by the Discovery Team — a rule inherited to avoid confusion between "legacy fact" and "forward hypothesis". Every requirement, behavior, edge case, and acceptance criterion in the specs must begin with 🟡. --- ## Workflow ### Phase 0, Component decomposition Read `/prd.md` in full. From the "Scope", "Target personas", and "Acceptance criteria" sections, propose a decomposition of the product into logical components. Each component should represent a cohesive unit that will become an individual SDD spec. Present the decomposition to the user: > "From the PRD, I identified these logical components: > > 1. ****: > 2. ****: > 3. ****: ... > > Do you agree with this decomposition? Do you want to add, remove, or rename any?" Wait for the response. Iterate until confirmed (maximum 2 adjustments). For each confirmed component, normalize the name to ASCII kebab-case. ### Phase 1, Interview per component (optional) For each component, decide whether the information in `prd.md` is already sufficient: - **Sufficient:** go directly to Phase 2. - **Insufficient:** ask at most 3 focused questions, covering the points below that are missing: 1. **The specific problem of that component:** "What is the role of `` in the product?" 2. **Success:** "How will you know this component worked? What can the user do?" 3. **Scope:** "What is explicitly OUT of scope for this component?" 4. **Edge cases:** "Can you already anticipate difficult cases or error situations in this component?" Total limit: 3 questions per component, choosing the most critical ones. ### Phase 2, Draft the spec Use the template in `references/spec_template.md` as the base. Fill in **all** sections: - **Functional requirements:** format `RF-01`, `RF-02`. Each one individually testable. Seal 🟡 mandatory. - **Behaviors:** describe what happens, not how to implement it. The spec defines the **what**, not the **how**. - **Zero ambiguity:** if unsure, mark with `⚠️ OPEN:` and add to the Open Questions list. - **LLM-readiness:** write as if a developer or LLM would implement without asking anything. - **Seal 🟡 on all spec items**, including RFs, edge cases, and criteria. Use `` for the spec content. ### Phase 3, Automatic quality evaluation After drafting each spec, run the scorer. **Python detection:** try `python --version` or `python3 --version` via shell. - **If Python is available:** ``` python scripts/spec_scorer.py --spec /sdd/.md ``` Use the literal output of the script. - **If Python is not available (manual mode):** apply the procedure in the "Scoring in engines without Python" section below. Scoring returns: - **Total score** (0 to 100) with breakdown by dimension - **Critical gaps** that need resolution - **Suggestions** ordered by impact Evaluated dimensions (see `references/evaluation_rubric.md` for details): | Dimension | Weight | What it evaluates | |---|---|---| | Completeness | 30% | All sections filled, requirements covered | | Testability | 25% | Verifiable requirements, clear acceptance criteria | | Clarity | 20% | No ambiguities, precise language | | Scope | 15% | Non-goals defined, clear boundaries | | Edge Cases | 10% | Error and system-limit cases covered | ### Phase 4, Iteration Based on the score: 1. Score **≥ 80**: spec is ready. Persist and move to the next component. 2. Score **60 to 79**: fix obvious gaps automatically, then confirm with the user whether anything critical is still missing. Redo scoring. 3. Score **< 60**: go back to Phase 1 with focused questions on the gaps. Redo scoring. Limit: **3 iterations per component**. After 3 attempts, persist with the current score and add a `## Quality gaps` section to the file. On each iteration, show the delta: "score went from 54 to 71, 2 critical gaps remain". ### Phase 5, Persistence and handoff For each completed component: 1. Write `/sdd/.md` with atomic write (tempfile then rename), UTF-8 without BOM. 2. Include at the end of the file the **evaluation report** (score + gaps + suggestions). 3. If the file already exists, ask the user whether to overwrite. After generating **all** specs, display the consolidated report: > "``, SDD generation complete. Specs created in `/sdd/`: > > | Component | Path | Score | Iterations | > |---|---|---|---| > | | /sdd/.md | 87 | 1 | > | | /sdd/.md | 73 | 2 | > | | /sdd/.md | 68 | 3 (with gaps) | > > All items marked with seal 🟡 (planned). > > Next step: run `/reversa-forward`, which will consume these specs and start the evolution cycle through to code. > > Type **CONTINUE** to start `/reversa-forward`, or pause here." Never proceed automatically. --- ## Scoring in engines without Python When `python --version` and `python3 --version` both fail, activate manual mode: 1. **Read `references/evaluation_rubric.md`** for the criteria of each dimension. 2. For each of the 5 dimensions, evaluate the spec mentally and assign a score of 0 to 100, justifying in 1 to 2 sentences: - **Completeness (30%):** are all 9 mandatory sections filled? Do the RFs cover the declared scope? - **Testability (25%):** are the RFs individually verifiable? Do acceptance criteria use Given/When/Then format or equivalent? - **Clarity (20%):** are there vague phrases (intuitive, fast, easy)? Are there contradictions? - **Scope (15%):** are non-goals explicitly declared? Are the boundaries clear? - **Edge cases (10%):** are at least 3 error/boundary cases covered? 3. **Calculate the weighted score:** ``` score = (Completeness * 0.30) + (Testability * 0.25) + (Clarity * 0.20) + (Scope * 0.15) + (Edge Cases * 0.10) ``` 4. **List the gaps** in order of criticality (blockers, important, improvements). 5. **Render the output** in the same format as the script: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TOTAL SCORE: /100 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Breakdown: Completeness: /100 (weight 30%) Testability: /100 (weight 25%) Clarity: /100 (weight 20%) Scope: /100 (weight 15%) Edge Cases: /100 (weight 10%) Critical gaps: - - Suggestions (by impact): 1. 2. ``` The manual-mode result should be equivalent to the script's result for the same spec. --- ## Mode: evaluation of an existing spec If the user invokes `/reversa-spec-sdd` outside the `/reversa-new` pipeline, with an already-written spec for evaluation: 1. Ask for the file path. 2. Run scoring (script or manual). 3. Present the score with detailed analysis by dimension. 4. List gaps in order of criticality. 5. Ask whether you should fix the identified points. This mode does not require `prd.md` and does not enter the pipeline. It is a standalone utility inherited from the original skill. --- ## Reference files | File | When to use | |---|---| | `references/spec_template.md` | Complete template with all sections, use as base for drafting | | `references/evaluation_rubric.md` | Detailed evaluation criteria by dimension | | `references/sdd_guide.md` | Methodology principles and best practices | | `assets/spec_examples.md` | Examples of good vs. bad specs with annotations | | `scripts/spec_scorer.py` | Automatic scoring script, used when Python is available | --- ## Signs of a bad spec (avoid) - Requirements that cannot be tested ("the system must be intuitive") - Missing or vague scope section ("we'll see what makes sense") - Mixing implementation technical design with expected behavior - Contradictory requirements not flagged - No acceptance criteria defined - Error edge cases completely absent ## Signs of a good spec (aim for) - Any developer can implement it without asking questions - Any QA can write tests from it - The non-goals are as clear as the goals - Error cases have defined behavior - Each requirement has a unique traceable ID --- ## Absolute rule Write only to `/sdd/`. Never touch files in the project outside that folder. On overwrite, always ask for `yes/no` confirmation. ## Final output After generating all specs from the PRD, always end with: > Type **CONTINUE** to proceed with `/reversa-forward`, or pause here. Never proceed automatically.