specdacular 0.2.1 → 0.2.2

package/specdacular/templates/features/RESEARCH.md

@@ -0,0 +1,183 @@
+# Research: {feature-name}
+
+**Researched:** {YYYY-MM-DD}
+**Feature type:** {what kind of feature}
+**Confidence:** {HIGH/MEDIUM/LOW}
+
+## Summary
+
+{2-3 paragraphs synthesizing all research findings}
+
+- What's the recommended approach?
+- What makes this feature fit well with the existing codebase?
+- What are the key risks and how to mitigate them?
+
+**Key recommendation:** {One-liner actionable guidance for the planner}
+
+---
+
+## Codebase Integration
+
+How this feature fits with existing code.
+
+### Import Dependencies
+
+| Module | Provides | Path |
+|--------|----------|------|
+| {module} | {what it provides} | `{path}` |
+
+### Patterns to Follow
+
+**{Pattern name}**
+Follow pattern in `{existing file path}`:
+- {Key aspect 1}
+- {Key aspect 2}
+
+```typescript
+// Example from {path}
+{code snippet showing pattern}
+```
+
+### File Structure
+
+Where new files should go:
+
+```
+src/
+├── {path}/           # {purpose}
+│   ├── {file}.ts     # {what it does}
+│   └── {file}.tsx    # {what it does}
+└── {existing}/       # Modify: {what change}
+```
+
+### Reusable Code
+
+**Types:**
+- `@{path}` — {what types}
+
+**Utilities:**
+- `@{path}` — {what utilities}
+
+**Components:**
+- `@{path}` — {what components}
+
+### Integration Points
+
+| Connect To | Via | Purpose |
+|------------|-----|---------|
+| {system} | {how} | {why} |
+
+---
+
+## Implementation Approach
+
+Standard patterns and libraries for this feature type.
+
+### Standard Stack
+
+| Library | Version | Purpose | Confidence |
+|---------|---------|---------|------------|
+| {lib} | {ver}+ | {purpose} | {HIGH/MEDIUM} |
+
+### Architecture Pattern
+
+**Pattern:** {name}
+**Why:** {rationale for this codebase}
+
+```
+{diagram or structure}
+```
+
+### Code Patterns
+
+**{Pattern name}**
+```typescript
+// Source: {Context7 library ID / docs URL}
+{verified code example}
+```
+
+**{Pattern name}**
+```typescript
+// Source: {Context7 library ID / docs URL}
+{verified code example}
+```
+
+### Don't Hand-Roll
+
+| Problem | Use Instead | Why |
+|---------|-------------|-----|
+| {problem} | {library/utility} | {edge cases it handles} |
+
+---
+
+## Pitfalls
+
+What commonly goes wrong and how to prevent it.
+
+### Critical
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Why it happens: {root cause}
+- Prevention: {specific steps}
+- Detection: {warning signs during implementation}
+
+### Moderate
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {specific steps}
+
+### Task-Specific Warnings
+
+| When Implementing | Watch Out For | Prevention |
+|-------------------|---------------|------------|
+| {task/file} | {pitfall} | {how to avoid} |
+
+---
+
+## Confidence Assessment
+
+| Area | Level | Reason |
+|------|-------|--------|
+| Codebase integration | {level} | {why - e.g., "patterns clear from existing code"} |
+| Implementation approach | {level} | {why - e.g., "verified with Context7"} |
+| Pitfalls | {level} | {why - e.g., "multiple sources agree"} |
+
+---
+
+## Open Questions
+
+Things that couldn't be fully resolved during research:
+
+1. **{Question}**
+   - What we know: {partial info}
+   - What's unclear: {the gap}
+   - Recommendation: {how planner should handle}
+
+---
+
+## Sources
+
+### Codebase (from Explore)
+- `{path}` — {what was learned}
+
+### Verified External (HIGH confidence)
+- Context7: {library IDs and queries}
+- Official docs: {URLs}
+
+### Community (MEDIUM confidence)
+- {Verified WebSearch findings with URLs}
+
+### For Awareness Only (LOW confidence)
+- {Unverified findings - not used in recommendations}
+
+---
+
+## Decisions Made
+
+Decisions recorded in DECISIONS.md during this research:
+
+| Decision | Rationale |
+|----------|-----------|
+| DEC-XXX: {title} | {brief rationale} |

package/specdacular/templates/features/ROADMAP.md

@@ -1,19 +1,21 @@
-# Roadmap: {Feature Name}
+# Roadmap: {feature-name}
 
 ## Overview
 
 | Metric | Value |
 |--------|-------|
 | Total Phases | {N} |
-| v1 Requirements | {N} |
-| v2 Requirements | {N} |
+| Total Plans | {N} |
 | Current Phase | 1 |
+| Status | Not Started |
+
+---
 
 ## Phases
 
-- [ ] **Phase 1: {Name}** - {Brief description}
-- [ ] **Phase 2: {Name}** - {Brief description}
-- [ ] **Phase 3: {Name}** - {Brief description}
+- [ ] **Phase 1: {Name}** — {One-liner description}
+- [ ] **Phase 2: {Name}** — {One-liner description}
+- [ ] **Phase 3: {Name}** — {One-liner description}
 
 ---
 
@@ -21,18 +23,25 @@
 
 ### Phase 1: {Name}
 
-**Goal:** {What this phase achieves - the outcome, not the tasks}
+**Goal:** {What this phase achieves — the outcome, not the tasks}
+
+**Creates:**
+- `{path/to/file}` — {Purpose}
+- `{path/to/file}` — {Purpose}
+
+**Modifies:**
+- `{path/to/file}` — {What change}
 
-**Requirements:**
-- {FEAT}-UI-01
-- {FEAT}-API-01
+**Plans:**
+1. `plans/phase-01/01-PLAN.md` — {Plan summary}
+2. `plans/phase-01/02-PLAN.md` — {Plan summary}
 
 **Success Criteria:**
 1. {Observable behavior that proves the phase is complete}
-2. {Observable behavior that proves the phase is complete}
-3. {Observable behavior that proves the phase is complete}
+2. {Observable behavior}
+3. {Observable behavior}
 
-**Dependencies:** {What must exist before this phase can start}
+**Dependencies:** None (first phase)
 
 ---
 
@@ -40,9 +49,14 @@
 
 **Goal:** {What this phase achieves}
 
-**Requirements:**
-- {FEAT}-UI-02
-- {FEAT}-DATA-01
+**Creates:**
+- `{path/to/file}` — {Purpose}
+
+**Modifies:**
+- `{path/to/file}` — {What change}
+
+**Plans:**
+1. `plans/phase-02/01-PLAN.md` — {Plan summary}
 
 **Success Criteria:**
 1. {Observable behavior}
@@ -56,8 +70,11 @@
 
 **Goal:** {What this phase achieves}
 
-**Requirements:**
-- {FEAT}-INT-01
+**Creates:**
+- `{path/to/file}` — {Purpose}
+
+**Plans:**
+1. `plans/phase-03/01-PLAN.md` — {Plan summary}
 
 **Success Criteria:**
 1. {Observable behavior}
@@ -67,16 +84,32 @@
 
 ---
 
-## v2 Phases (Future)
+## Execution Order
+
+The recommended execution order respects dependencies:
+
+```
+Phase 1: {Name}
+├── 01-PLAN.md: {summary}
+└── 02-PLAN.md: {summary}
+    ↓
+Phase 2: {Name}
+└── 01-PLAN.md: {summary}
+    ↓
+Phase 3: {Name}
+└── 01-PLAN.md: {summary}
+```
 
-{Phases for v2 requirements, planned but not scheduled.}
+---
+
+## Key Decisions Affecting Roadmap
 
-### Future: {Name}
+| Decision | Impact on Phases |
+|----------|------------------|
+| DEC-XXX: {title} | {How it affects phase ordering or content} |
 
-**Goal:** {What this phase would achieve}
+---
 
-**Requirements:**
-- {FEAT}-UI-03
-- {FEAT}-API-02
+## Notes
 
-**Trigger:** {When to revisit this phase}
+{Space for notes about the roadmap — why phases are ordered this way, alternatives considered, etc.}

package/specdacular/templates/features/STATE.md

@@ -1,54 +1,83 @@
-# State: {Feature Name}
+# State: {feature-name}
 
 ## Current Position
 
-**Phase:** 1 - {Phase Name}
-**Status:** Not Started
-**Last Updated:** {Date}
+**Stage:** {discussion | research | planning | execution}
+**Last Updated:** {YYYY-MM-DD}
 
-## Progress Summary
+---
+
+## Stage Progress
+
+### Discussion
+- [x] Initial discussion complete
+- [ ] Gray areas identified
+- [ ] All gray areas resolved
+
+### Research
+- [ ] Research conducted
+- [ ] Findings documented in RESEARCH.md
+
+### Planning
+- [ ] Phases derived
+- [ ] Plans created
+
+### Execution
+- [ ] Phase 1 complete
+- [ ] Phase 2 complete
+
+---
 
-### Completed
-{Nothing yet}
+## Discussion Sessions
 
-### In Progress
-{Nothing yet}
+| Date | Focus | Outcome |
+|------|-------|---------|
+| {YYYY-MM-DD} | Initial discussion | FEATURE.md created |
 
-### Blocked
-{Nothing yet}
+---
 
-## Accumulated Decisions
+## Documents Status
 
-{Decisions made during planning and implementation. Add new decisions as they're made.}
+| Document | Status | Last Updated |
+|----------|--------|--------------|
+| FEATURE.md | Created | {date} |
+| CONTEXT.md | Created | {date} |
+| DECISIONS.md | {N} decisions | {date} |
+| RESEARCH.md | Not started | — |
+| ROADMAP.md | Not started | — |
+| plans/ | Not started | — |
 
-| Date | Decision | Context | Impact |
-|------|----------|---------|--------|
-| {Date} | {What was decided} | {Why it came up} | {How it affects implementation} |
+---
 
-## Session History
+## Decision Count
 
-| Date | Activity | Outcome |
-|------|----------|---------|
-| {Date} | Feature initialized | Created planning documents |
+- **Active:** {N}
+- **Superseded:** {N}
+- **Total:** {N}
 
-## Phase Progress
+---
 
-### Phase 1: {Name}
+## Next Steps
 
-**Status:** Not Started
+{What the user should do next based on current state.}
+
+**Options:**
+- `/specd:discuss-feature {feature-name}` — Continue refining understanding
+- `/specd:research-feature {feature-name}` — Research implementation approach
+- `/specd:plan-feature {feature-name}` — Create executable plans (when ready)
+
+---
 
-**Requirements Progress:**
-- [ ] {FEAT}-UI-01: Not started
-- [ ] {FEAT}-API-01: Not started
+## Session Notes
 
-**Notes:**
-{Implementation notes, blockers, discoveries}
+{Space for notes during sessions. Cleared or archived as appropriate.}
 
 ---
 
 ## Quick Reference
 
 - **Feature:** `.specd/features/{feature-name}/FEATURE.md`
-- **Requirements:** `.specd/features/{feature-name}/REQUIREMENTS.md`
+- **Context:** `.specd/features/{feature-name}/CONTEXT.md`
+- **Decisions:** `.specd/features/{feature-name}/DECISIONS.md`
+- **Research:** `.specd/features/{feature-name}/RESEARCH.md`
 - **Roadmap:** `.specd/features/{feature-name}/ROADMAP.md`
-- **Config:** `.specd/features/{feature-name}/config.json`