Initial vibecoded proof of concept

specs/002-notex-is-a/spec.md

@@ -0,0 +1,123 @@
+# Feature Specification: Relational Document System for Neovim
+
+**Feature Branch**: `002-notex-is-a`
+**Created**: 2025-10-03
+**Status**: Draft
+**Input**: User description: "Notex is a relational database plugin that mimics notion databases. This should define a custom query syntax. When mousing over the custom syntax, this should open virtual buffer that shows an editable view into the database. This database should summarize properties of markdown documents that are defined in a yaml header. This project should leverage sqlite database to improve performance"
+
+## Execution Flow (main)
+```
+1. Parse user description from Input
+   → If empty: ERROR "No feature description provided"
+2. Extract key concepts from description
+   → Identify: actors, actions, data, constraints
+3. For each unclear aspect:
+   → Mark with [NEEDS CLARIFICATION: specific question]
+4. Fill User Scenarios & Testing section
+   → If no clear user flow: ERROR "Cannot determine user scenarios"
+5. Generate Functional Requirements
+   → Each requirement must be testable
+   → Mark ambiguous requirements
+6. Identify Key Entities (if data involved)
+7. Run Review Checklist
+   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
+   → If implementation details found: ERROR "Remove tech details"
+8. Return: SUCCESS (spec ready for planning)
+```
+
+---
+
+## ⚡ Quick Guidelines
+- ✅ Focus on WHAT users need and WHY
+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
+- 👥 Written for business stakeholders, not developers
+
+### Section Requirements
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+When creating this spec from a user prompt:
+1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
+2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
+3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+4. **Common underspecified areas**:
+   - User types and permissions
+   - Data retention/deletion policies
+   - Performance targets and scale
+   - Error handling behaviors
+   - Integration requirements
+   - Security/compliance needs
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### Primary User Story
+As a Neovim user, I want to work with my markdown documents as if they were entries in a relational database similar to Notion, so that I can query, filter, and view my documents based on their properties without leaving my editor.
+
+### Acceptance Scenarios
+1. **Given** I have markdown documents with YAML headers, **When** I write a custom query syntax in my buffer, **Then** hovering over it should display a virtual buffer with the query results
+2. **Given** I'm viewing query results in a virtual buffer, **When** I modify the data, **Then** the changes should be reflected in the underlying markdown documents
+3. **Given** I have multiple markdown documents, **When** I execute a query, **Then** the system should return results based on the YAML header properties
+4. **Given** I define a custom query, **When** I save the query, **Then** I should be able to reuse it later
+
+### Edge Cases
+- What happens when markdown documents have malformed or missing YAML headers?
+- How does system handle queries that return no results?
+- What happens when multiple documents have conflicting property definitions?
+- How does system handle very large document collections?
+- What happens when the virtual buffer is edited while the underlying files are changed externally?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+- **FR-001**: System MUST parse YAML headers from markdown documents to extract document properties
+- **FR-002**: System MUST provide a custom query syntax for filtering and organizing documents
+- **FR-003**: Users MUST be able to hover over query syntax to see results in a virtual buffer
+- **FR-004**: Query results MUST be editable and changes must propagate back to source documents
+- **FR-005**: System MUST maintain a performant index of document properties for fast querying
+- **FR-006**: Users MUST be able to save and reuse common queries
+- **FR-007**: System MUST support filtering documents by any property defined in YAML headers
+- **FR-008**: Virtual buffer views MUST support sorting and grouping of query results
+
+### Key Entities
+- **Document**: Represents a markdown file with YAML header properties and content
+- **Query**: Defines filtering criteria and display options for documents
+- **Property**: Individual key-value pairs extracted from YAML headers
+- **View**: Virtual buffer representation of query results
+- **Schema**: Defines the structure and types of properties across documents
+
+---
+
+## Review & Acceptance Checklist
+*GATE: Automated checks run during main() execution*
+
+### Content Quality
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+### Requirement Completeness
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+---
+
+## Execution Status
+*Updated by main() during processing*
+
+- [x] User description parsed
+- [x] Key concepts extracted
+- [x] Ambiguities marked
+- [x] User scenarios defined
+- [x] Requirements generated
+- [x] Entities identified
+- [x] Review checklist passed
+
+---