{"id":17568,"plugin_id":"plugins_6a78e83987748191afc0c56e12172fce","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:15.997Z","digest":"b6a7309c2af85090ea2ec205de20e274fec7d21f657deab856ac2489a0733723","against":null,"payload":{"description":"Synthesize conversation and codebase context into an unambiguous, buildable technical specification. Use when requirements and design decisions are settled and need to be formalized into a technical spec — even if the user says \"write a spec for this\". Do NOT use when the core idea is still fuzzy and ungrilled.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":92}],"name":"to-spec","skill_md_contents":"---\nname: to-spec\ndescription: \"Synthesize conversation and codebase context into an unambiguous, buildable technical specification. Use when requirements and design decisions are settled and need to be formalized into a technical spec — even if the user says \\\"write a spec for this\\\". Do NOT use when the core idea is still fuzzy and ungrilled.\"\n---\n\n# To Spec\n\nSynthesize settled conversation context and codebase understanding into an unambiguous, buildable technical specification with minimal test seams and complete user stories.\n\n---\n\n## Core Invariants\n\n1. **Pure Synthesis, Zero Interrogation**: Synthesize strictly from established context and codebase facts; do not interview the user.\n2. **Minimal Seams at the Highest Tier**: Prefer existing high-level test seams; never introduce unnecessary internal mocking seams.\n3. **Exhaustive User Stories**: Generate a comprehensive, numbered list of `As an <actor>, I want <feature>, so that <benefit>` stories covering all user paths.\n4. **Decisions Over Concrete Snippets**: Specify architectural decisions, interfaces, and schema changes without fragile, hardcoded code snippets (unless derived from a validated prototype).\n5. **Strict Out-of-Scope Demarcation**: Explicitly list out-of-scope capabilities to prevent scope creep and unbound work.\n\n---\n\n## Architecture & Map of Content (MOC)\n\n```\n[ Settled Context & ADRs ] ──► [ Codebase Seam Inspection ] ──► [ Spec Document Synthesis ] ──► [ Tracker Publication ]\n```\n\n| Component | Responsibility | Format / Template |\n|---|---|---|\n| **Problem & Solution** | Frame user-centric intent | Problem / Solution statements |\n| **User Stories** | Enumerate all functional paths | Numbered standard user stories |\n| **Implementation Decisions** | Define module boundaries & contracts | Architecture & schema decisions |\n| **Testing Decisions** | Specify external verification seams | Behavior-driven test strategy |\n\n---\n\n## Step-by-Step Procedure (TWI)\n\n### Step 1: Autonomous Codebase & Seam Inspection\n- **Action**: Explore the repository to inspect existing modules, domain glossary terms, and ADRs.\n- **Key Point**: Identify the highest available integration seam to test the feature externally.\n- **Why**: Testing through high-level seams verifies true system behavior while leaving internal implementation details free to refactor.\n\n### Step 2: Formulate Comprehensive User Stories\n- **Action**: Draft an exhaustive, numbered list of user stories capturing all primary and edge-case user interactions.\n- **Key Point**: Follow the strict template: `1. As an <actor>, I want a <feature>, so that <benefit>`.\n- **Why**: Detailed user stories prevent implementers from making ad-hoc product assumptions during coding.\n- **Inline Checklist**:\n  - [ ] Every user story has an explicit actor and tangible benefit\n  - [ ] Edge cases and failure states are covered as distinct stories\n  - [ ] No implementation jargon inside user story statements\n\n### Step 3: Formalize Implementation and Testing Decisions\n- **Action**: Document module boundaries, modified interfaces, database schema changes, and API contracts.\n- **Key Point**: Omit volatile file line numbers or speculative code snippets.\n- **Why**: Fragile code snippets go stale immediately and misdirect downstream implementation agents.\n\n### Step 4: Define Out-of-Scope Boundaries & Publish\n- **Action**: Detail what is explicitly NOT included, apply the `ready-for-agent` triage label, and publish to the configured issue tracker or `.scratch/<feature-slug>/spec.md`.\n- **Key Point**: If the issue tracker is unconfigured, instruct the user to run `/setup-engineering-workflows`.\n- **Why**: Clear negative boundaries prevent scope bloat and keep subsequent ticket decomposition bounded.\n\n---\n\n## Anti-Rationalization Guardrails\n\n| Tempting Rationalization | Binding Rule | Engineering Rationale |\n|---|---|---|\n| *\"I'll ask the user a few more questions before writing the spec.\"* | **No interviewing during to-spec.** | If requirements are still fuzzy, route back to `grill-me`. `to-spec` is pure synthesis. |\n| *\"I will write extensive mock-heavy unit test decisions.\"* | **Test at the highest possible public seam.** | Mock-heavy tests break during refactors and fail to verify actual end-to-end functionality. |\n| *\"Include complete implementation code blocks in the spec.\"* | **Specify interfaces and decisions, not full code.** | Implementation code in specs blinds the developer agent to live codebase nuances. |\n| *\"Skip the out-of-scope section since it seems obvious.\"* | **Mandatory explicit Out-of-Scope section.** | Ambiguity in scope boundaries causes runaway scope creep during implementation. |\n\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}