qualia-framework 2.6.0 → 3.2.0

package/framework/qualia-framework/templates/research-project/FEATURES.md

@@ -1,147 +0,0 @@
-# Features Research Template
-
-Template for `.planning/research/FEATURES.md` — feature landscape for the project domain.
-
-<template>
-
-```markdown
-# Feature Research
-
-**Domain:** [domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Feature Landscape
-
-### Table Stakes (Users Expect These)
-
-Features users assume exist. Missing these = product feels incomplete.
-
-| Feature | Why Expected | Complexity | Notes |
-|---------|--------------|------------|-------|
-| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [user expectation] | LOW/MEDIUM/HIGH | [implementation notes] |
-
-### Differentiators (Competitive Advantage)
-
-Features that set the product apart. Not required, but valuable.
-
-| Feature | Value Proposition | Complexity | Notes |
-|---------|-------------------|------------|-------|
-| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
-| [feature] | [why it matters] | LOW/MEDIUM/HIGH | [implementation notes] |
-
-### Anti-Features (Commonly Requested, Often Problematic)
-
-Features that seem good but create problems.
-
-| Feature | Why Requested | Why Problematic | Alternative |
-|---------|---------------|-----------------|-------------|
-| [feature] | [surface appeal] | [actual problems] | [better approach] |
-| [feature] | [surface appeal] | [actual problems] | [better approach] |
-
-## Feature Dependencies
-
-```
-[Feature A]
-    └──requires──> [Feature B]
-                       └──requires──> [Feature C]
-
-[Feature D] ──enhances──> [Feature A]
-
-[Feature E] ──conflicts──> [Feature F]
-```
-
-### Dependency Notes
-
-- **[Feature A] requires [Feature B]:** [why the dependency exists]
-- **[Feature D] enhances [Feature A]:** [how they work together]
-- **[Feature E] conflicts with [Feature F]:** [why they're incompatible]
-
-## MVP Definition
-
-### Launch With (v1)
-
-Minimum viable product — what's needed to validate the concept.
-
-- [ ] [Feature] — [why essential]
-- [ ] [Feature] — [why essential]
-- [ ] [Feature] — [why essential]
-
-### Add After Validation (v1.x)
-
-Features to add once core is working.
-
-- [ ] [Feature] — [trigger for adding]
-- [ ] [Feature] — [trigger for adding]
-
-### Future Consideration (v2+)
-
-Features to defer until product-market fit is established.
-
-- [ ] [Feature] — [why defer]
-- [ ] [Feature] — [why defer]
-
-## Feature Prioritization Matrix
-
-| Feature | User Value | Implementation Cost | Priority |
-|---------|------------|---------------------|----------|
-| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
-| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
-| [feature] | HIGH/MEDIUM/LOW | HIGH/MEDIUM/LOW | P1/P2/P3 |
-
-**Priority key:**
-- P1: Must have for launch
-- P2: Should have, add when possible
-- P3: Nice to have, future consideration
-
-## Competitor Feature Analysis
-
-| Feature | Competitor A | Competitor B | Our Approach |
-|---------|--------------|--------------|--------------|
-| [feature] | [how they do it] | [how they do it] | [our plan] |
-| [feature] | [how they do it] | [how they do it] | [our plan] |
-
-## Sources
-
-- [Competitor products analyzed]
-- [User research or feedback sources]
-- [Industry standards referenced]
-
----
-*Feature research for: [domain]*
-*Researched: [date]*
-```
-
-</template>
-
-<guidelines>
-
-**Table Stakes:**
-- These are non-negotiable for launch
-- Users don't give credit for having them, but penalize for missing them
-- Example: A community platform without user profiles is broken
-
-**Differentiators:**
-- These are where you compete
-- Should align with the Core Value from PROJECT.md
-- Don't try to differentiate on everything
-
-**Anti-Features:**
-- Prevent scope creep by documenting what seems good but isn't
-- Include the alternative approach
-- Example: "Real-time everything" often creates complexity without value
-
-**Feature Dependencies:**
-- Critical for roadmap phase ordering
-- If A requires B, B must be in an earlier phase
-- Conflicts inform what NOT to combine in same phase
-
-**MVP Definition:**
-- Be ruthless about what's truly minimum
-- "Nice to have" is not MVP
-- Launch with less, validate, then expand
-
-</guidelines>

package/framework/qualia-framework/templates/research-project/PITFALLS.md

@@ -1,200 +0,0 @@
-# Pitfalls Research Template
-
-Template for `.planning/research/PITFALLS.md` — common mistakes to avoid in the project domain.
-
-<template>
-
-```markdown
-# Pitfalls Research
-
-**Domain:** [domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Critical Pitfalls
-
-### Pitfall 1: [Name]
-
-**What goes wrong:**
-[Description of the failure mode]
-
-**Why it happens:**
-[Root cause — why developers make this mistake]
-
-**How to avoid:**
-[Specific prevention strategy]
-
-**Warning signs:**
-[How to detect this early before it becomes a problem]
-
-**Phase to address:**
-[Which roadmap phase should prevent this]
-
----
-
-### Pitfall 2: [Name]
-
-**What goes wrong:**
-[Description of the failure mode]
-
-**Why it happens:**
-[Root cause — why developers make this mistake]
-
-**How to avoid:**
-[Specific prevention strategy]
-
-**Warning signs:**
-[How to detect this early before it becomes a problem]
-
-**Phase to address:**
-[Which roadmap phase should prevent this]
-
----
-
-### Pitfall 3: [Name]
-
-**What goes wrong:**
-[Description of the failure mode]
-
-**Why it happens:**
-[Root cause — why developers make this mistake]
-
-**How to avoid:**
-[Specific prevention strategy]
-
-**Warning signs:**
-[How to detect this early before it becomes a problem]
-
-**Phase to address:**
-[Which roadmap phase should prevent this]
-
----
-
-[Continue for all critical pitfalls...]
-
-## Technical Debt Patterns
-
-Shortcuts that seem reasonable but create long-term problems.
-
-| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
-|----------|-------------------|----------------|-----------------|
-| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
-| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
-| [shortcut] | [benefit] | [cost] | [conditions, or "never"] |
-
-## Integration Gotchas
-
-Common mistakes when connecting to external services.
-
-| Integration | Common Mistake | Correct Approach |
-|-------------|----------------|------------------|
-| [service] | [what people do wrong] | [what to do instead] |
-| [service] | [what people do wrong] | [what to do instead] |
-| [service] | [what people do wrong] | [what to do instead] |
-
-## Performance Traps
-
-Patterns that work at small scale but fail as usage grows.
-
-| Trap | Symptoms | Prevention | When It Breaks |
-|------|----------|------------|----------------|
-| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
-| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
-| [trap] | [how you notice] | [how to avoid] | [scale threshold] |
-
-## Security Mistakes
-
-Domain-specific security issues beyond general web security.
-
-| Mistake | Risk | Prevention |
-|---------|------|------------|
-| [mistake] | [what could happen] | [how to avoid] |
-| [mistake] | [what could happen] | [how to avoid] |
-| [mistake] | [what could happen] | [how to avoid] |
-
-## UX Pitfalls
-
-Common user experience mistakes in this domain.
-
-| Pitfall | User Impact | Better Approach |
-|---------|-------------|-----------------|
-| [pitfall] | [how users suffer] | [what to do instead] |
-| [pitfall] | [how users suffer] | [what to do instead] |
-| [pitfall] | [how users suffer] | [what to do instead] |
-
-## "Looks Done But Isn't" Checklist
-
-Things that appear complete but are missing critical pieces.
-
-- [ ] **[Feature]:** Often missing [thing] — verify [check]
-- [ ] **[Feature]:** Often missing [thing] — verify [check]
-- [ ] **[Feature]:** Often missing [thing] — verify [check]
-- [ ] **[Feature]:** Often missing [thing] — verify [check]
-
-## Recovery Strategies
-
-When pitfalls occur despite prevention, how to recover.
-
-| Pitfall | Recovery Cost | Recovery Steps |
-|---------|---------------|----------------|
-| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
-| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
-| [pitfall] | LOW/MEDIUM/HIGH | [what to do] |
-
-## Pitfall-to-Phase Mapping
-
-How roadmap phases should address these pitfalls.
-
-| Pitfall | Prevention Phase | Verification |
-|---------|------------------|--------------|
-| [pitfall] | Phase [X] | [how to verify prevention worked] |
-| [pitfall] | Phase [X] | [how to verify prevention worked] |
-| [pitfall] | Phase [X] | [how to verify prevention worked] |
-
-## Sources
-
-- [Post-mortems referenced]
-- [Community discussions]
-- [Official "gotchas" documentation]
-- [Personal experience / known issues]
-
----
-*Pitfalls research for: [domain]*
-*Researched: [date]*
-```
-
-</template>
-
-<guidelines>
-
-**Critical Pitfalls:**
-- Focus on domain-specific issues, not generic mistakes
-- Include warning signs — early detection prevents disasters
-- Link to specific phases — makes pitfalls actionable
-
-**Technical Debt:**
-- Be realistic — some shortcuts are acceptable
-- Note when shortcuts are "never acceptable" vs. "only in MVP"
-- Include the long-term cost to inform tradeoff decisions
-
-**Performance Traps:**
-- Include scale thresholds ("breaks at 10k users")
-- Focus on what's relevant for this project's expected scale
-- Don't over-engineer for hypothetical scale
-
-**Security Mistakes:**
-- Beyond OWASP basics — domain-specific issues
-- Example: Community platforms have different security concerns than e-commerce
-- Include risk level to prioritize
-
-**"Looks Done But Isn't":**
-- Checklist format for verification during execution
-- Common in demos vs. production
-- Prevents "it works on my machine" issues
-
-**Pitfall-to-Phase Mapping:**
-- Critical for roadmap creation
-- Each pitfall should map to a phase that prevents it
-- Informs phase ordering and success criteria
-
-</guidelines>

package/framework/qualia-framework/templates/research-project/STACK.md

@@ -1,120 +0,0 @@
-# Stack Research Template
-
-Template for `.planning/research/STACK.md` — recommended technologies for the project domain.
-
-<template>
-
-```markdown
-# Stack Research
-
-**Domain:** [domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Recommended Stack
-
-### Core Technologies
-
-| Technology | Version | Purpose | Why Recommended |
-|------------|---------|---------|-----------------|
-| [name] | [version] | [what it does] | [why experts use it for this domain] |
-| [name] | [version] | [what it does] | [why experts use it for this domain] |
-| [name] | [version] | [what it does] | [why experts use it for this domain] |
-
-### Supporting Libraries
-
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| [name] | [version] | [what it does] | [specific use case] |
-| [name] | [version] | [what it does] | [specific use case] |
-| [name] | [version] | [what it does] | [specific use case] |
-
-### Development Tools
-
-| Tool | Purpose | Notes |
-|------|---------|-------|
-| [name] | [what it does] | [configuration tips] |
-| [name] | [what it does] | [configuration tips] |
-
-## Installation
-
-```bash
-# Core
-npm install [packages]
-
-# Supporting
-npm install [packages]
-
-# Dev dependencies
-npm install -D [packages]
-```
-
-## Alternatives Considered
-
-| Recommended | Alternative | When to Use Alternative |
-|-------------|-------------|-------------------------|
-| [our choice] | [other option] | [conditions where alternative is better] |
-| [our choice] | [other option] | [conditions where alternative is better] |
-
-## What NOT to Use
-
-| Avoid | Why | Use Instead |
-|-------|-----|-------------|
-| [technology] | [specific problem] | [recommended alternative] |
-| [technology] | [specific problem] | [recommended alternative] |
-
-## Stack Patterns by Variant
-
-**If [condition]:**
-- Use [variation]
-- Because [reason]
-
-**If [condition]:**
-- Use [variation]
-- Because [reason]
-
-## Version Compatibility
-
-| Package A | Compatible With | Notes |
-|-----------|-----------------|-------|
-| [package@version] | [package@version] | [compatibility notes] |
-
-## Sources
-
-- [Context7 library ID] — [topics fetched]
-- [Official docs URL] — [what was verified]
-- [Other source] — [confidence level]
-
----
-*Stack research for: [domain]*
-*Researched: [date]*
-```
-
-</template>
-
-<guidelines>
-
-**Core Technologies:**
-- Include specific version numbers
-- Explain why this is the standard choice, not just what it does
-- Focus on technologies that affect architecture decisions
-
-**Supporting Libraries:**
-- Include libraries commonly needed for this domain
-- Note when each is needed (not all projects need all libraries)
-
-**Alternatives:**
-- Don't just dismiss alternatives
-- Explain when alternatives make sense
-- Helps user make informed decisions if they disagree
-
-**What NOT to Use:**
-- Actively warn against outdated or problematic choices
-- Explain the specific problem, not just "it's old"
-- Provide the recommended alternative
-
-**Version Compatibility:**
-- Note any known compatibility issues
-- Critical for avoiding debugging time later
-
-</guidelines>

package/framework/qualia-framework/templates/research-project/SUMMARY.md

@@ -1,170 +0,0 @@
-# Research Summary Template
-
-Template for `.planning/research/SUMMARY.md` — executive summary of project research with roadmap implications.
-
-<template>
-
-```markdown
-# Project Research Summary
-
-**Project:** [name from PROJECT.md]
-**Domain:** [inferred domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Executive Summary
-
-[2-3 paragraph overview of research findings]
-
-- What type of product this is and how experts build it
-- The recommended approach based on research
-- Key risks and how to mitigate them
-
-## Key Findings
-
-### Recommended Stack
-
-[Summary from STACK.md — 1-2 paragraphs]
-
-**Core technologies:**
-- [Technology]: [purpose] — [why recommended]
-- [Technology]: [purpose] — [why recommended]
-- [Technology]: [purpose] — [why recommended]
-
-### Expected Features
-
-[Summary from FEATURES.md]
-
-**Must have (table stakes):**
-- [Feature] — users expect this
-- [Feature] — users expect this
-
-**Should have (competitive):**
-- [Feature] — differentiator
-- [Feature] — differentiator
-
-**Defer (v2+):**
-- [Feature] — not essential for launch
-
-### Architecture Approach
-
-[Summary from ARCHITECTURE.md — 1 paragraph]
-
-**Major components:**
-1. [Component] — [responsibility]
-2. [Component] — [responsibility]
-3. [Component] — [responsibility]
-
-### Critical Pitfalls
-
-[Top 3-5 from PITFALLS.md]
-
-1. **[Pitfall]** — [how to avoid]
-2. **[Pitfall]** — [how to avoid]
-3. **[Pitfall]** — [how to avoid]
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure:
-
-### Phase 1: [Name]
-**Rationale:** [why this comes first based on research]
-**Delivers:** [what this phase produces]
-**Addresses:** [features from FEATURES.md]
-**Avoids:** [pitfall from PITFALLS.md]
-
-### Phase 2: [Name]
-**Rationale:** [why this order]
-**Delivers:** [what this phase produces]
-**Uses:** [stack elements from STACK.md]
-**Implements:** [architecture component]
-
-### Phase 3: [Name]
-**Rationale:** [why this order]
-**Delivers:** [what this phase produces]
-
-[Continue for suggested phases...]
-
-### Phase Ordering Rationale
-
-- [Why this order based on dependencies discovered]
-- [Why this grouping based on architecture patterns]
-- [How this avoids pitfalls from research]
-
-### Research Flags
-
-Phases likely needing deeper research during planning:
-- **Phase [X]:** [reason — e.g., "complex integration, needs API research"]
-- **Phase [Y]:** [reason — e.g., "niche domain, sparse documentation"]
-
-Phases with standard patterns (skip research-phase):
-- **Phase [X]:** [reason — e.g., "well-documented, established patterns"]
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [HIGH/MEDIUM/LOW] | [reason] |
-| Features | [HIGH/MEDIUM/LOW] | [reason] |
-| Architecture | [HIGH/MEDIUM/LOW] | [reason] |
-| Pitfalls | [HIGH/MEDIUM/LOW] | [reason] |
-
-**Overall confidence:** [HIGH/MEDIUM/LOW]
-
-### Gaps to Address
-
-[Any areas where research was inconclusive or needs validation during implementation]
-
-- [Gap]: [how to handle during planning/execution]
-- [Gap]: [how to handle during planning/execution]
-
-## Sources
-
-### Primary (HIGH confidence)
-- [Context7 library ID] — [topics]
-- [Official docs URL] — [what was checked]
-
-### Secondary (MEDIUM confidence)
-- [Source] — [finding]
-
-### Tertiary (LOW confidence)
-- [Source] — [finding, needs validation]
-
----
-*Research completed: [date]*
-*Ready for roadmap: yes*
-```
-
-</template>
-
-<guidelines>
-
-**Executive Summary:**
-- Write for someone who will only read this section
-- Include the key recommendation and main risk
-- 2-3 paragraphs maximum
-
-**Key Findings:**
-- Summarize, don't duplicate full documents
-- Link to detailed docs (STACK.md, FEATURES.md, etc.)
-- Focus on what matters for roadmap decisions
-
-**Implications for Roadmap:**
-- This is the most important section
-- Directly informs roadmap creation
-- Be explicit about phase suggestions and rationale
-- Include research flags for each suggested phase
-
-**Confidence Assessment:**
-- Be honest about uncertainty
-- Note gaps that need resolution during planning
-- HIGH = verified with official sources
-- MEDIUM = community consensus, multiple sources agree
-- LOW = single source or inference
-
-**Integration with roadmap creation:**
-- This file is loaded as context during roadmap creation
-- Phase suggestions here become starting point for roadmap
-- Research flags inform phase planning
-
-</guidelines>