@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/notion-spec-to-implementation/reference/spec-parsing.md

@@ -0,0 +1,383 @@
+# Specification Parsing
+
+## Finding the Specification
+
+Before parsing, locate the spec page:
+
+```
+1. Search for spec:
+   Notion:notion-search
+   query: "[Feature Name] spec" or "[Feature Name] specification"
+   
+2. Handle results:
+   - If found → use page URL/ID
+   - If multiple → ask user which one
+   - If not found → ask user for URL/ID
+
+Example:
+Notion:notion-search
+query: "User Profile API spec"
+query_type: "internal"
+```
+
+## Reading Specifications
+
+After finding the spec, fetch it with `Notion:notion-fetch`:
+
+1. Read the full content
+2. Identify key sections
+3. Extract structured information
+4. Note ambiguities or gaps
+
+```
+Notion:notion-fetch
+id: "spec-page-id-from-search"
+```
+
+## Common Spec Structures
+
+### Requirements-Based Spec
+
+```
+# Feature Spec
+## Overview
+[Feature description]
+
+## Requirements
+### Functional
+- REQ-1: [Requirement]
+- REQ-2: [Requirement]
+
+### Non-Functional
+- PERF-1: [Performance requirement]
+- SEC-1: [Security requirement]
+
+## Acceptance Criteria
+- AC-1: [Criterion]
+- AC-2: [Criterion]
+```
+
+Extract:
+- List of functional requirements
+- List of non-functional requirements
+- List of acceptance criteria
+
+### User Story Based Spec
+
+```
+# Feature Spec
+## User Stories
+### As a [user type]
+I want [goal]
+So that [benefit]
+
+**Acceptance Criteria**:
+- [Criterion]
+- [Criterion]
+```
+
+Extract:
+- User personas
+- Goals/capabilities needed
+- Acceptance criteria per story
+
+### Technical Design Doc
+
+```
+# Technical Design
+## Problem Statement
+[Problem description]
+
+## Proposed Solution
+[Solution approach]
+
+## Architecture
+[Architecture details]
+
+## Implementation Plan
+[Implementation approach]
+```
+
+Extract:
+- Problem being solved
+- Proposed solution approach
+- Architectural decisions
+- Implementation guidance
+
+### Product Requirements Document (PRD)
+
+```
+# PRD: [Feature]
+## Goals
+[Business goals]
+
+## User Needs
+[User problems being solved]
+
+## Features
+[Feature list]
+
+## Success Metrics
+[How to measure success]
+```
+
+Extract:
+- Business goals
+- User needs
+- Feature list
+- Success metrics
+
+## Extraction Strategies
+
+### Requirement Identification
+
+Look for:
+- "Must", "Should", "Will" statements
+- Numbered requirements (REQ-1, etc.)
+- User stories (As a... I want...)
+- Acceptance criteria sections
+- Feature lists
+
+### Categorization
+
+Group requirements by:
+
+**Functional**: What the system does
+- User capabilities
+- System behaviors
+- Data operations
+
+**Non-Functional**: How the system performs
+- Performance targets
+- Security requirements
+- Scalability needs
+- Availability requirements
+- Compliance requirements
+
+**Constraints**: Limitations
+- Technical constraints
+- Business constraints
+- Timeline constraints
+
+### Priority Extraction
+
+Identify priority indicators:
+- "Critical", "Must have", "P0"
+- "Important", "Should have", "P1"
+- "Nice to have", "Could have", "P2"
+- "Future", "Won't have", "P3"
+
+Map to implementation phases based on priority.
+
+## Handling Ambiguity
+
+### Unclear Requirements
+
+When requirement is ambiguous:
+
+```markdown
+## Clarifications Needed
+
+### [Requirement ID/Description]
+**Current text**: "[Ambiguous requirement]"
+**Question**: [What needs clarification]
+**Impact**: [Why this matters for implementation]
+**Assumed for now**: [Working assumption if any]
+```
+
+Create clarification task or add comment to spec.
+
+### Missing Information
+
+When critical info is missing:
+
+```markdown
+## Missing Information
+
+- **[Topic]**: Spec doesn't specify [what's missing]
+- **Impact**: Blocks [affected tasks]
+- **Action**: Need to [how to resolve]
+```
+
+### Conflicting Requirements
+
+When requirements conflict:
+
+```markdown
+## Conflicting Requirements
+
+**Conflict**: REQ-1 says [X] but REQ-5 says [Y]
+**Impact**: [Implementation impact]
+**Resolution needed**: [Decision needed]
+```
+
+## Acceptance Criteria Parsing
+
+### Explicit Criteria
+
+Direct acceptance criteria:
+
+```
+## Acceptance Criteria
+- User can log in with email and password
+- System sends confirmation email
+- Session expires after 24 hours
+```
+
+Convert to checklist:
+- [ ] User can log in with email and password
+- [ ] System sends confirmation email
+- [ ] Session expires after 24 hours
+
+### Implicit Criteria
+
+Derive from requirements:
+
+```
+Requirement: "Users can upload files up to 100MB"
+
+Implied acceptance criteria:
+- [ ] Files up to 100MB upload successfully
+- [ ] Files over 100MB are rejected with error message
+- [ ] Progress indicator shows during upload
+- [ ] Upload can be cancelled
+```
+
+### Testable Criteria
+
+Ensure criteria are testable:
+
+❌ **Not testable**: "System is fast"
+✓ **Testable**: "Page loads in < 2 seconds"
+
+❌ **Not testable**: "Users like the interface"
+✓ **Testable**: "90% of test users complete task successfully"
+
+## Technical Detail Extraction
+
+### Architecture Information
+
+Extract:
+- System components
+- Data models
+- APIs/interfaces
+- Integration points
+- Technology choices
+
+### Design Decisions
+
+Note:
+- Technology selections
+- Architecture patterns
+- Trade-offs made
+- Rationale provided
+
+### Implementation Guidance
+
+Look for:
+- Suggested approach
+- Code examples
+- Library recommendations
+- Best practices mentioned
+
+## Dependency Identification
+
+### External Dependencies
+
+From spec, identify:
+- Third-party services required
+- External APIs needed
+- Infrastructure requirements
+- Tool/library dependencies
+
+### Internal Dependencies
+
+Identify:
+- Other features needed first
+- Shared components required
+- Team dependencies
+- Data dependencies
+
+### Timeline Dependencies
+
+Note:
+- Hard deadlines
+- Milestone dependencies
+- Sequencing requirements
+
+## Scope Extraction
+
+### In Scope
+
+What's explicitly included:
+- Features to build
+- Use cases to support
+- Users/personas to serve
+
+### Out of Scope
+
+What's explicitly excluded:
+- Features deferred
+- Use cases not supported
+- Edge cases not handled
+
+### Assumptions
+
+What's assumed:
+- Environment assumptions
+- User assumptions
+- System state assumptions
+
+## Risk Identification
+
+Extract risk information:
+
+### Technical Risks
+- Unproven technology
+- Complex integration
+- Performance concerns
+- Scalability unknowns
+
+### Business Risks
+- Market timing
+- Resource availability
+- Dependency on others
+
+### Mitigation Strategies
+
+Note any mitigation approaches mentioned in spec.
+
+## Spec Quality Assessment
+
+Evaluate spec completeness:
+
+✓ **Good spec**:
+- Clear requirements
+- Explicit acceptance criteria
+- Priorities defined
+- Risks identified
+- Technical approach outlined
+
+⚠️ **Incomplete spec**:
+- Vague requirements
+- Missing acceptance criteria
+- Unclear priorities
+- No risk analysis
+- Technical details absent
+
+Document gaps and create clarification tasks.
+
+## Parsing Checklist
+
+Before creating implementation plan:
+
+☐ All functional requirements identified
+☐ Non-functional requirements noted
+☐ Acceptance criteria extracted
+☐ Dependencies identified
+☐ Risks noted
+☐ Ambiguities documented
+☐ Technical approach understood
+☐ Scope is clear
+☐ Priorities are defined
+

package/skills/notion-spec-to-implementation/reference/standard-implementation-plan.md

@@ -0,0 +1,146 @@
+# Standard Implementation Plan Template
+
+Use this template for most feature implementations.
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Overview
+[1-2 sentence feature description and business value]
+
+## Linked Specification
+<mention-page url="...">Original Specification</mention-page>
+
+## Requirements Summary
+
+### Functional Requirements
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+### Non-Functional Requirements
+- **Performance**: [Targets]
+- **Security**: [Requirements]
+- **Scalability**: [Needs]
+
+### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Technical Approach
+
+### Architecture
+[High-level architectural decisions]
+
+### Technology Stack
+- Backend: [Technologies]
+- Frontend: [Technologies]
+- Infrastructure: [Technologies]
+
+### Key Design Decisions
+1. **[Decision]**: [Rationale]
+2. **[Decision]**: [Rationale]
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1)
+**Goal**: Set up core infrastructure
+
+**Tasks**:
+- [ ] <mention-page url="...">Database schema design</mention-page>
+- [ ] <mention-page url="...">API scaffolding</mention-page>
+- [ ] <mention-page url="...">Authentication setup</mention-page>
+
+**Deliverables**: Working API skeleton
+**Estimated effort**: 3 days
+
+### Phase 2: Core Features (Week 2-3)
+**Goal**: Implement main functionality
+
+**Tasks**:
+- [ ] <mention-page url="...">Feature A implementation</mention-page>
+- [ ] <mention-page url="...">Feature B implementation</mention-page>
+
+**Deliverables**: Core features working
+**Estimated effort**: 1 week
+
+### Phase 3: Integration & Polish (Week 4)
+**Goal**: Complete integration and refinement
+
+**Tasks**:
+- [ ] <mention-page url="...">Frontend integration</mention-page>
+- [ ] <mention-page url="...">Testing & QA</mention-page>
+
+**Deliverables**: Production-ready feature
+**Estimated effort**: 1 week
+
+## Dependencies
+
+### External Dependencies
+- [Dependency 1]: [Status]
+- [Dependency 2]: [Status]
+
+### Internal Dependencies
+- [Team/component dependency]
+
+### Blockers
+- [Known blocker] or None currently
+
+## Risks & Mitigation
+
+### Risk 1: [Description]
+- **Probability**: High/Medium/Low
+- **Impact**: High/Medium/Low
+- **Mitigation**: [Strategy]
+
+### Risk 2: [Description]
+- **Probability**: High/Medium/Low
+- **Impact**: High/Medium/Low
+- **Mitigation**: [Strategy]
+
+## Timeline
+
+| Milestone | Target Date | Status |
+|-----------|-------------|--------|
+| Phase 1 Complete | [Date] | ⏳ Planned |
+| Phase 2 Complete | [Date] | ⏳ Planned |
+| Phase 3 Complete | [Date] | ⏳ Planned |
+| Launch | [Date] | ⏳ Planned |
+
+## Success Criteria
+
+### Technical Success
+- [ ] All acceptance criteria met
+- [ ] Performance targets achieved
+- [ ] Security requirements satisfied
+- [ ] Test coverage > 80%
+
+### Business Success
+- [ ] [Business metric 1]
+- [ ] [Business metric 2]
+
+## Resources
+
+### Documentation
+- <mention-page url="...">Design Doc</mention-page>
+- <mention-page url="...">API Spec</mention-page>
+
+### Related Work
+- <mention-page url="...">Related Feature</mention-page>
+
+## Progress Tracking
+
+[This section updated regularly]
+
+### Phase Status
+- Phase 1: ⏳ Not Started
+- Phase 2: ⏳ Not Started
+- Phase 3: ⏳ Not Started
+
+**Overall Progress**: 0% complete
+
+### Latest Update: [Date]
+[Brief status update]
+```
+

package/skills/notion-spec-to-implementation/reference/task-creation-template.md

@@ -0,0 +1,34 @@
+# Task Creation Template
+
+When creating tasks from spec.
+
+```markdown
+# [Task Name]
+
+## Context
+Part of implementation for <mention-page url="...">Feature Spec</mention-page>
+
+Implementation plan: <mention-page url="...">Implementation Plan</mention-page>
+
+## Description
+[What needs to be done]
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+## Technical Details
+[Technical approach or notes]
+
+## Dependencies
+- Blocked by: [Task] or None
+- Blocks: [Task] or None
+
+## Resources
+- [Link to design]
+- [Link to related code]
+
+## Progress
+[To be updated during implementation]
+```
+