qualia-framework 3.2.1 → 3.3.1

package/templates/requirements.md

@@ -0,0 +1,69 @@
+# Requirements: {Project Name}
+
+**Defined:** {date}
+**Core Value:** {from PROJECT.md — the one thing that must work}
+
+## v1 Requirements
+
+Initial release scope. Each maps to one roadmap phase.
+
+### {Category 1}
+
+- [ ] **{CAT}-01**: {user-centric, testable, atomic capability}
+- [ ] **{CAT}-02**: {capability}
+- [ ] **{CAT}-03**: {capability}
+
+### {Category 2}
+
+- [ ] **{CAT}-01**: {capability}
+- [ ] **{CAT}-02**: {capability}
+
+## v2 Requirements
+
+Acknowledged but deferred to a future release. Not in current roadmap.
+
+### {Category}
+
+- **{CAT}-01**: {capability}
+- **{CAT}-02**: {capability}
+
+## Out of Scope
+
+Explicit exclusions with reasoning. Prevents scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| {feature} | {why excluded} |
+
+## Traceability
+
+Which phases cover which requirements. Populated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| {CAT}-01 | Phase {N} | Pending |
+
+**Coverage:**
+- v1 requirements: {X} total
+- Mapped to phases: {Y}
+- Unmapped: {Z}
+
+---
+
+## Requirement Quality Rules
+
+1. **ID format:** `{CATEGORY}-{NUMBER}` — `AUTH-01`, `CONT-02`, `SOCIAL-03`
+2. **User-centric:** "User can X" — not "System does Y"
+3. **Atomic:** One capability per requirement — not "User can login and manage profile"
+4. **Testable:** "User can reset password via email link" — not "handle password reset"
+5. **Independent:** Minimal dependencies on other requirements
+
+## Status Values
+
+- **Pending** — not started
+- **In Progress** — phase is active
+- **Complete** — requirement verified
+- **Blocked** — waiting on external factor
+
+---
+*Last updated: {date}*

package/templates/research-project/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture Research
+
+**Domain:** {domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Standard Architecture
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| {name} | {what it owns} | {how it's usually built} |
+
+### Data Flow
+
+```
+[User Action]
+    ↓
+[Component] → [Handler] → [Service] → [Data Store]
+    ↓              ↓           ↓            ↓
+[Response] ← [Transform] ← [Query] ← [Database]
+```
+
+### Key Flows
+
+1. **{flow name}:** {how data moves}
+2. **{flow name}:** {how data moves}
+
+## Recommended Project Structure
+
+```
+src/
+├── {folder}/           # {purpose}
+├── {folder}/           # {purpose}
+└── {folder}/           # {purpose}
+```
+
+**Structure rationale:**
+- **{folder}/:** {why organized this way}
+
+## Suggested Build Order
+
+Phases should follow this dependency order:
+
+1. **{component}** — foundation, no dependencies
+2. **{component}** — depends on 1
+3. **{component}** — depends on 1, 2
+
+## Anti-Patterns
+
+### {Name}
+
+**What people do:** {the mistake}
+**Why it's wrong:** {the problem}
+**Do this instead:** {correct approach}
+
+## Integration Points
+
+| Service | Integration Pattern | Notes |
+|---------|---------------------|-------|
+| {service} | {how to connect} | {gotchas} |
+
+## Sources
+
+- {architecture references}
+- {official documentation}
+
+---
+*Architecture research for: {domain}*

package/templates/research-project/FEATURES.md

@@ -0,0 +1,60 @@
+# 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} |
+
+### 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 | {notes} |
+
+### Anti-Features (Seem Good, Aren't)
+
+Features that seem good but create problems — often requested, rarely right.
+
+| Feature | Why Requested | Why Problematic | Alternative |
+|---------|---------------|-----------------|-------------|
+| {feature} | {surface appeal} | {actual problems} | {better approach} |
+
+## MVP Recommendation
+
+### Launch With (v1)
+
+- {feature} — {why essential}
+- {feature} — {why essential}
+
+### Add After Validation (v1.x)
+
+- {feature} — {trigger}
+
+### Defer (v2+)
+
+- {feature} — {why defer}
+
+## Feature Dependencies
+
+- **{Feature A}** requires **{Feature B}** — {why}
+- **{Feature C}** enhances **{Feature A}** — {how}
+
+## Sources
+
+- {competitor products analyzed}
+- {user research referenced}
+- {industry standards}
+
+---
+*Feature research for: {domain}*

package/templates/research-project/PITFALLS.md

@@ -0,0 +1,73 @@
+# Pitfalls Research
+
+**Domain:** {domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Critical Pitfalls
+
+### {Pitfall Name}
+
+**What goes wrong:** {the failure mode}
+**Why it happens:** {root cause}
+**How to avoid:** {specific prevention strategy}
+**Warning signs:** {how to detect early}
+**Phase to address:** Phase {N}
+
+---
+
+### {Pitfall Name}
+
+**What goes wrong:** {failure mode}
+**Why it happens:** {root cause}
+**How to avoid:** {prevention}
+**Warning signs:** {detection}
+**Phase to address:** Phase {N}
+
+---
+
+## 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"} |
+
+## 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} |
+
+## Security Mistakes
+
+Domain-specific security issues beyond general web security.
+
+| Mistake | Risk | Prevention |
+|---------|------|------------|
+| {mistake} | {what could happen} | {how to avoid} |
+
+## "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}
+
+## Pitfall-to-Phase Mapping
+
+| Pitfall | Prevention Phase | Verification |
+|---------|------------------|--------------|
+| {pitfall} | Phase {X} | {how to verify prevention} |
+
+## Sources
+
+- {post-mortems referenced}
+- {community discussions}
+- {official "gotchas" documentation}
+
+---
+*Pitfalls research for: {domain}*

package/templates/research-project/STACK.md

@@ -0,0 +1,51 @@
+# 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} |
+
+### Supporting Libraries
+
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| {name} | {version} | {what it does} | {specific use case} |
+
+## Installation
+
+```bash
+npm install {core packages}
+npm install -D {dev dependencies}
+```
+
+## Alternatives Considered
+
+| Recommended | Alternative | When to Use Alternative |
+|-------------|-------------|-------------------------|
+| {our choice} | {other option} | {conditions} |
+
+## What NOT to Use
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| {technology} | {specific problem} | {recommended alternative} |
+
+## Version Compatibility
+
+Known compatibility constraints between the recommended packages.
+
+## Sources
+
+- {Context7 library ID} — {topics fetched}
+- {Official docs URL} — {what was verified}
+
+---
+*Stack research for: {domain}*

package/templates/research-project/SUMMARY.md

@@ -0,0 +1,86 @@
+# Research Summary
+
+**Project:** {name}
+**Domain:** {inferred domain type}
+**Researched:** {date}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Executive Summary
+
+{2-3 paragraph overview — what type of product this is, recommended approach, key risks}
+
+## Key Findings
+
+### Recommended Stack
+
+**Core:**
+- {tech}: {purpose} — {why}
+- {tech}: {purpose} — {why}
+
+### Table Stakes Features
+
+- {feature} — users expect this
+- {feature} — users expect this
+
+### Differentiators
+
+- {feature}
+- {feature}
+
+### Critical Pitfalls
+
+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}
+**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}
+
+### Phase Ordering Rationale
+
+- {why this order based on dependencies}
+- {why this grouping based on architecture patterns}
+
+### Research Flags
+
+Phases likely needing deeper research during `/qualia-plan`:
+- **Phase {X}:** {reason}
+
+## 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
+
+{Areas where research was inconclusive — handle during planning}
+
+- {gap}: {handling}
+
+## Sources
+
+**Primary (HIGH confidence):**
+- {Context7 library ID} — {topics}
+
+**Secondary (MEDIUM confidence):**
+- {source} — {finding}
+
+---
+*Ready for roadmap: yes*

package/templates/roadmap.md

@@ -0,0 +1,71 @@
+# Roadmap: {Project Name}
+
+**Created:** {date}
+**Total phases:** {N}
+**v1 requirements:** {X} covered
+
+## Phases
+
+| # | Phase | Goal | Requirements | Status |
+|---|-------|------|--------------|--------|
+| 1 | {name} | {one-sentence goal} | {REQ-IDs} | ready |
+| 2 | {name} | {goal} | {REQ-IDs} | — |
+| 3 | {name} | {goal} | {REQ-IDs} | — |
+
+## Phase Details
+
+### Phase 1: {Name}
+
+**Goal:** {what must be TRUE when this phase is done}
+
+**Requirements covered:**
+- {REQ-ID}: {description}
+- {REQ-ID}: {description}
+
+**Success criteria** (observable user behaviors):
+1. {user can do X}
+2. {user can do Y}
+3. {user can do Z}
+
+**Depends on:** none (or: Phase {N})
+
+---
+
+### Phase 2: {Name}
+
+**Goal:** {goal}
+
+**Requirements covered:**
+- {REQ-ID}: {description}
+
+**Success criteria:**
+1. {criterion}
+2. {criterion}
+
+**Depends on:** Phase 1
+
+---
+
+{... continue for all phases ...}
+
+## Coverage Verification
+
+All v1 requirements must map to exactly one phase. Unmapped requirements = roadmap gap.
+
+| Requirement | Phase | Covered? |
+|-------------|-------|----------|
+| {REQ-ID} | Phase {N} | ✓ |
+
+**Coverage:** {X}/{Y} v1 requirements mapped ({100% expected})
+
+---
+
+## Rules
+
+1. **Feature phases only.** No "review" / "deploy" / "handoff" phases — those are driven by `/qualia-polish` → `/qualia-ship` → `/qualia-handoff` after all feature phases verify.
+2. **Each requirement maps to exactly one phase.** If a requirement spans phases, it's too big — split it.
+3. **Phases are independently verifiable.** A phase completes when its success criteria are observable in a running app.
+4. **Order by dependency, not priority.** Phase 2 should depend on Phase 1's outputs.
+
+---
+*Last updated: {date}*