spec-from-stream

# Spec from Stream Transform unstructured product/feature descriptions into a structured specification package formatted as Obsidian-compatible notes with dense cross-referencing. ## Before Starting Read the reference files relevant to the requested output: | Output | Reference file | When to read | |--------|---------------|-------------| | Always | `references/question-bank.md` | Before Phase 4 (gap-filling questions) | | BRD | `references/brd-template.md` | Before Phase 5 | | SRS | `references/srs-template.md` | Before Phase 5b (ISO/IEC/IEEE 29148:2018) | | NFR | `references/nfr-template.md` | Before Phase 5b (ISO/IEC 25010:2011) | | Vault | `references/vault-template.md` | Before Phase 6 (Zettelkasten decomposition) | ## Document Types | Document | Standard | Purpose | Filename | |----------|----------|---------|----------| | **BRD** | — | WHAT to build and WHY (business perspective) | `BRD-{slug}-{date}.md` | | **SRS** | ISO/IEC/IEEE 29148:2018 | HOW it works (functional spec, interfaces, verification) | `SRS-{slug}-{date}.md` | | **NFR** | ISO/IEC 25010:2011 | Quality attributes (performance, security, reliability...) | `NFR-{slug}-{date}.md` | Default output: BRD only. Generate SRS and/or NFR when explicitly requested or when the project complexity warrants it (suggest to the user if appropriate). ## Workflow ### Phase 1: Intake Accept the user's raw input — it can be: - A stream-of-consciousness text dump - A voice-transcription-style description - A series of bullet points - A conversation where the idea emerges gradually - Even a single sentence ("I want an app that does X") Do NOT ask clarifying questions yet. First, process what you have. ### Phase 2: Parse & Assess Coverage Silently map the raw input onto the BRD template sections. For each section, assess: - **GREEN**: Enough information to write a meaningful section - **YELLOW**: Partial information — can be inferred but needs confirmation - **RED**: Critical gap — cannot proceed without user input Build an internal coverage map (do not show it to the user). Example: ``` Executive Summary → GREEN Problem Statement → YELLOW (why not stated, inferred from context) Target Users → RED (not mentioned at all) Functional Reqs → YELLOW (high-level list, no acceptance criteria) Non-Functional Reqs → RED Scope & Boundaries → RED Integrations → GREEN Constraints → YELLOW Success Criteria → RED ``` ### Phase 3: Present Draft & Start Dialogue Present the user with a summary of what you understood: 1. Restate the core idea in 2-3 sentences (confirm you got it right) 2. List sections you CAN fill (GREEN) — briefly 3. List YELLOW sections with your assumptions 4. List RED sections as gaps that need input Then immediately ask the **first** gap-filling question — pick the highest-priority RED gap according to the Question Priority order in Phase 4. ### Phase 4: Guided Gap-Filling Close RED and YELLOW gaps through a conversation. #### Question Strategy - **One question at a time** — never overwhelm with a list - **Offer concrete options** — instead of open-ended "what's your target audience?", offer choices - **Derive from context** — reference what the user already said - **Suggest defaults** — propose typical solutions, let user override - **Know when to stop** — if the user signals they're done (see `references/question-bank.md#Stop Signals`), move ALL remaining RED/YELLOW gaps to Open Questions and proceed to generation #### Question Priority (most critical first) 1. **Problem & Users** — what problem, for whom 2. **Core functionality** — what the system must do (MVP) 3. **Boundaries** — what is explicitly NOT in scope 4. **Success criteria** — how to know it's done correctly 5. **Constraints** — deadlines, budget, team size, tech preferences 6. **Integrations** — external systems, APIs, data sources 7. **Non-functional requirements** — only if critical #### Dialogue Style - Match the user's language (Russian, English, etc.) - Be conversational, not interrogative — you're a co-author, not an interviewer - After each answer, briefly acknowledge it and ask the next question - Treat the user as the domain expert — you're the structuring engine ### Phase 5: Generate BRD Generate the BRD when one of these conditions is met: 1. All RED and YELLOW gaps are resolved 2. User sends a stop signal 3. User explicitly asks to generate the document Read `references/brd-template.md` and generate the document following its structure exactly. If RED sections remain unresolved, convert them into specific open questions inside the `> [!question]` callout — never leave template placeholders. Write the file and present it to the user. ### Phase 5b: Generate SRS and/or NFR (Optional) Triggered when the user requests detailed requirements documents: "сделай SRS", "functional requirements", "non-functional requirements", "NFR", "full spec", "detailed requirements", "полный пакет документов". Read the corresponding reference templates before generating: - `references/srs-template.md` for SRS - `references/nfr-template.md` for NFR #### SRS Generation Rules 1. **Source**: extract from BRD Functional Requirements and Integrations sections 2. **Expand**: each BRD requirement becomes a detailed spec with rationale, acceptance criteria, dependencies, and traceability back to BRD 3. **Add interfaces**: derive from BRD integrations table 4. **Add verification**: create Verification Matrix and Traceability Matrix 5. **Standard**: follow ISO/IEC/IEEE 29148:2018 structure from template 6. **Language**: "shall" for mandatory, "should" for recommended, "may" for optional #### NFR Generation Rules 1. **Source**: extract from BRD Non-Functional Requirements and Constraints sections 2. **Structure**: follow ISO/IEC 25010:2011 quality model — 8 characteristics 3. **Measurable**: every NFR must have a quantitative target and verification method 4. **Skip irrelevant**: omit categories that don't apply, but document WHY (`> [!note] Not Applicable`) 5. **Trade-offs**: define quality attribute priority order 6. **Gap-filling**: if BRD lacks NFR details, ask targeted questions (one at a time, with options) #### Cross-Linking All documents MUST be interlinked: - BRD `related:` includes `"[[SRS-{slug}-{date}]]"` and `"[[NFR-{slug}-{date}]]"` - SRS References section links to BRD and NFR - NFR References section links to BRD and SRS - Every SRS requirement has `Source: [[BRD-{slug}-{date}]], FR-NNN` - SRS Traceability Matrix maps BRD → SRS → NFR requirement IDs ### Phase 6: Decompose into Obsidian Knowledge Base (Optional) Triggered when the user requests decomposition: "разбей на заметки", "сделай vault", "convert to knowledge base", "atomic notes". Read `references/vault-template.md` and follow its instructions exactly. Decompose ALL generated documents (BRD + SRS + NFR if present) into atomic notes. --- ## Obsidian Formatting Rules (Mandatory) Every generated document MUST follow these rules: ### YAML Properties - Every file starts with `---` delimited YAML frontmatter - Required: `tags` (at least document type + domain tag), `created` (YYYY-MM-DD), `status` - Recommended: `aliases`, `project`, `related`, `standard` (for SRS/NFR) - Internal links in properties require quotes: `related: "[[other-note]]"` ### Callouts | Type | Use for | |------|---------| | `> [!abstract]` | Document summary at the top | | `> [!warning]` | Assumptions that need confirmation | | `> [!danger]` | Explicit exclusions, breaking constraints | | `> [!tip]` | Best practices, recommendations | | `> [!question]` | Open questions, unresolved items | | `> [!note]` | General supplementary information, "Not Applicable" sections | | `> [!example]` | Usage examples, scenarios | | `> [!info]` | Contextual background | ### Links - Use `[[wikilinks]]` for references to related documents, specs, or project notes - Link on first mention only — don't link every occurrence - Use display text for readability: `[[long-document-name|short name]]` ### Tags - Use nested tags for hierarchy: `#brd`, `#srs`, `#nfr`, `#domain/subdomain` - Always add tags to YAML properties, not only inline - Use lowercase-kebab-case for tags ### General - One `# H1` title per document - Code blocks with language annotations - No raw URLs — use `[text](url)` format - Tables for structured comparisons - Task lists (`- [ ]`) for success criteria and open questions --- ## Language Policy - **Conversation**: always in the user's language (detect from their first message) - **All output documents**: always in **English**, regardless of conversation language - This applies to: BRD, SRS, NFR, spec.md, plan.md, tasks.md, MOC, vault notes — everything - Glossary terms may include the original-language term in parentheses if the English translation is ambiguous (e.g., "Counterparty (Контрагент)") - Questions during gap-filling are asked in the user's language ## Interaction Style - Be conversational during gap-filling, formal in output documents - Don't lecture about "best practices" — just produce good documents - If the user gives a one-liner, that's fine — more questions needed, but don't make them feel like their input was insufficient - Treat the user as the domain expert — you're the structuring engine