Spec From Stream

---
name: spec-from-stream
description: >
  Transforms a user's stream-of-consciousness description of a product idea, feature, or system
  into a structured specification package: BRD, SRS (ISO/IEC/IEEE 29148), NFR (ISO/IEC 25010),
  formatted as Obsidian notes. Can decompose documents into a Zettelkasten knowledge base.
  The agent uses the stream as a starting point, fills in what it can, then asks guided
  questions one at a time to close gaps. Works in any language the user writes in.
when_to_use: >
  "I have an idea", "I want to build", "let me describe what I need", "turn this into a spec",
  "write requirements for this", "make a BRD from this", "SRS", "functional requirements",
  "non-functional requirements", "NFR", "decompose into notes", "make a vault", "knowledge base",
  or a messy description the user wants organized into actionable requirements.
---

# 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