feat: add research-project command for pre-roadmap ecosystem research
Adds /gsd:research-project to research domain ecosystem before creating roadmap. Spawns parallel agents to investigate stack, features, architecture, and pitfalls. New files: - commands/gsd/research-project.md - get-shit-done/workflows/research-project.md - get-shit-done/templates/research-project/ (5 templates) Modified: - new-project.md: offers research vs direct roadmap options - create-roadmap.md: loads research if exists - workflows/create-roadmap.md: uses research to inform phases Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -24,6 +24,7 @@ Roadmaps define what work happens in what order. Run after /gsd:new-project.
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json
|
||||
@.planning/research/SUMMARY.md (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
@@ -303,7 +303,15 @@ Project initialized:
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**[Project Name]** — create roadmap
|
||||
Choose your path:
|
||||
|
||||
**Option A: Research first** (recommended for new domains)
|
||||
Research the ecosystem before creating roadmap. Discovers standard stacks, expected features, architecture patterns, and common pitfalls.
|
||||
|
||||
`/gsd:research-project`
|
||||
|
||||
**Option B: Create roadmap directly** (for familiar domains)
|
||||
Skip research if you know this domain well or have a clear spec.
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
|
||||
134
commands/gsd/research-project.md
Normal file
134
commands/gsd/research-project.md
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
name: gsd:research-project
|
||||
description: Research domain ecosystem before creating roadmap
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- Grep
|
||||
- Task
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
- mcp__context7__*
|
||||
---
|
||||
|
||||
<objective>
|
||||
Comprehensive domain research before roadmap creation.
|
||||
|
||||
Answers the questions that inform quality roadmaps:
|
||||
- What's the standard stack for this type of product?
|
||||
- What features do users expect?
|
||||
- How are these systems typically structured?
|
||||
- What do projects in this domain commonly get wrong?
|
||||
|
||||
Run after `/gsd:new-project`, before `/gsd:create-roadmap`.
|
||||
|
||||
Output: `.planning/research/` folder with ecosystem knowledge.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/research-project.md
|
||||
@~/.claude/get-shit-done/templates/research-project/SUMMARY.md
|
||||
@~/.claude/get-shit-done/templates/research-project/STACK.md
|
||||
@~/.claude/get-shit-done/templates/research-project/FEATURES.md
|
||||
@~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
|
||||
@~/.claude/get-shit-done/templates/research-project/PITFALLS.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
```bash
|
||||
# Verify project exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Check if roadmap already exists
|
||||
[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md already exists. Research is typically done before roadmap creation."
|
||||
|
||||
# Check if research already exists
|
||||
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
**If RESEARCH_EXISTS:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Research exists"
|
||||
- question: "Research folder already exists. What would you like to do?"
|
||||
- options:
|
||||
- "View existing" — Show current research summary
|
||||
- "Replace" — Run fresh research (will overwrite)
|
||||
- "Cancel" — Keep existing research
|
||||
|
||||
If "View existing": Read and display `.planning/research/SUMMARY.md`, then exit
|
||||
If "Cancel": Exit
|
||||
If "Replace": Continue with workflow
|
||||
</step>
|
||||
|
||||
<step name="execute_research">
|
||||
Follow the research-project.md workflow:
|
||||
- Analyze PROJECT.md to determine domain
|
||||
- Identify research questions based on domain
|
||||
- Spawn parallel research agents
|
||||
- Aggregate results into `.planning/research/`
|
||||
- Create SUMMARY.md with roadmap implications
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
```
|
||||
Research complete:
|
||||
|
||||
- Summary: .planning/research/SUMMARY.md
|
||||
- Stack: .planning/research/STACK.md
|
||||
- Features: .planning/research/FEATURES.md
|
||||
- Architecture: .planning/research/ARCHITECTURE.md
|
||||
- Pitfalls: .planning/research/PITFALLS.md
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Create roadmap** — informed by research
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<when_to_use>
|
||||
**Use research-project for:**
|
||||
- Greenfield projects in established domains (community, e-commerce, SaaS)
|
||||
- When "what features should exist" is partially unknown
|
||||
- Complex integrations requiring ecosystem knowledge
|
||||
- Domains where best practices matter (auth, payments, real-time)
|
||||
- Any project where you'd Google "how to build a [X]" before starting
|
||||
|
||||
**Skip research-project for:**
|
||||
- Well-defined specs ("build exactly this API")
|
||||
- Simple tools/utilities with clear scope
|
||||
- Adding features to existing codebases (use research-phase instead)
|
||||
- Domains you've built in many times before
|
||||
</when_to_use>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] Domain identified from project description
|
||||
- [ ] Research questions determined and approved
|
||||
- [ ] Parallel research agents spawned
|
||||
- [ ] All research documents created in .planning/research/
|
||||
- [ ] SUMMARY.md includes roadmap implications
|
||||
- [ ] Research committed to git
|
||||
- [ ] User knows next step (create-roadmap)
|
||||
</success_criteria>
|
||||
204
get-shit-done/templates/research-project/ARCHITECTURE.md
Normal file
204
get-shit-done/templates/research-project/ARCHITECTURE.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Architecture Research Template
|
||||
|
||||
Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
|
||||
|
||||
<template>
|
||||
|
||||
```markdown
|
||||
# Architecture Research
|
||||
|
||||
**Domain:** [domain type]
|
||||
**Researched:** [date]
|
||||
**Confidence:** [HIGH/MEDIUM/LOW]
|
||||
|
||||
## Standard Architecture
|
||||
|
||||
### System Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ [Layer Name] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ [Comp] │ │ [Comp] │ │ [Comp] │ │ [Comp] │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
│ │ │ │ │ │
|
||||
├───────┴────────────┴────────────┴────────────┴──────────────┤
|
||||
│ [Layer Name] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ [Component] │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ [Layer Name] │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ [Store] │ │ [Store] │ │ [Store] │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Component Responsibilities
|
||||
|
||||
| Component | Responsibility | Typical Implementation |
|
||||
|-----------|----------------|------------------------|
|
||||
| [name] | [what it owns] | [how it's usually built] |
|
||||
| [name] | [what it owns] | [how it's usually built] |
|
||||
| [name] | [what it owns] | [how it's usually built] |
|
||||
|
||||
## Recommended Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── [folder]/ # [purpose]
|
||||
│ ├── [subfolder]/ # [purpose]
|
||||
│ └── [file].ts # [purpose]
|
||||
├── [folder]/ # [purpose]
|
||||
│ ├── [subfolder]/ # [purpose]
|
||||
│ └── [file].ts # [purpose]
|
||||
├── [folder]/ # [purpose]
|
||||
└── [folder]/ # [purpose]
|
||||
```
|
||||
|
||||
### Structure Rationale
|
||||
|
||||
- **[folder]/:** [why organized this way]
|
||||
- **[folder]/:** [why organized this way]
|
||||
|
||||
## Architectural Patterns
|
||||
|
||||
### Pattern 1: [Pattern Name]
|
||||
|
||||
**What:** [description]
|
||||
**When to use:** [conditions]
|
||||
**Trade-offs:** [pros and cons]
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// [Brief code example showing the pattern]
|
||||
```
|
||||
|
||||
### Pattern 2: [Pattern Name]
|
||||
|
||||
**What:** [description]
|
||||
**When to use:** [conditions]
|
||||
**Trade-offs:** [pros and cons]
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// [Brief code example showing the pattern]
|
||||
```
|
||||
|
||||
### Pattern 3: [Pattern Name]
|
||||
|
||||
**What:** [description]
|
||||
**When to use:** [conditions]
|
||||
**Trade-offs:** [pros and cons]
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Request Flow
|
||||
|
||||
```
|
||||
[User Action]
|
||||
↓
|
||||
[Component] → [Handler] → [Service] → [Data Store]
|
||||
↓ ↓ ↓ ↓
|
||||
[Response] ← [Transform] ← [Query] ← [Database]
|
||||
```
|
||||
|
||||
### State Management
|
||||
|
||||
```
|
||||
[State Store]
|
||||
↓ (subscribe)
|
||||
[Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]
|
||||
```
|
||||
|
||||
### Key Data Flows
|
||||
|
||||
1. **[Flow name]:** [description of how data moves]
|
||||
2. **[Flow name]:** [description of how data moves]
|
||||
|
||||
## Scaling Considerations
|
||||
|
||||
| Scale | Architecture Adjustments |
|
||||
|-------|--------------------------|
|
||||
| 0-1k users | [approach — usually monolith is fine] |
|
||||
| 1k-100k users | [approach — what to optimize first] |
|
||||
| 100k+ users | [approach — when to consider splitting] |
|
||||
|
||||
### Scaling Priorities
|
||||
|
||||
1. **First bottleneck:** [what breaks first, how to fix]
|
||||
2. **Second bottleneck:** [what breaks next, how to fix]
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Anti-Pattern 1: [Name]
|
||||
|
||||
**What people do:** [the mistake]
|
||||
**Why it's wrong:** [the problem it causes]
|
||||
**Do this instead:** [the correct approach]
|
||||
|
||||
### Anti-Pattern 2: [Name]
|
||||
|
||||
**What people do:** [the mistake]
|
||||
**Why it's wrong:** [the problem it causes]
|
||||
**Do this instead:** [the correct approach]
|
||||
|
||||
## Integration Points
|
||||
|
||||
### External Services
|
||||
|
||||
| Service | Integration Pattern | Notes |
|
||||
|---------|---------------------|-------|
|
||||
| [service] | [how to connect] | [gotchas] |
|
||||
| [service] | [how to connect] | [gotchas] |
|
||||
|
||||
### Internal Boundaries
|
||||
|
||||
| Boundary | Communication | Notes |
|
||||
|----------|---------------|-------|
|
||||
| [module A ↔ module B] | [API/events/direct] | [considerations] |
|
||||
|
||||
## Sources
|
||||
|
||||
- [Architecture references]
|
||||
- [Official documentation]
|
||||
- [Case studies]
|
||||
|
||||
---
|
||||
*Architecture research for: [domain]*
|
||||
*Researched: [date]*
|
||||
```
|
||||
|
||||
</template>
|
||||
|
||||
<guidelines>
|
||||
|
||||
**System Overview:**
|
||||
- Use ASCII diagrams for clarity
|
||||
- Show major components and their relationships
|
||||
- Don't over-detail — this is conceptual, not implementation
|
||||
|
||||
**Project Structure:**
|
||||
- Be specific about folder organization
|
||||
- Explain the rationale for grouping
|
||||
- Match conventions of the chosen stack
|
||||
|
||||
**Patterns:**
|
||||
- Include code examples where helpful
|
||||
- Explain trade-offs honestly
|
||||
- Note when patterns are overkill for small projects
|
||||
|
||||
**Scaling Considerations:**
|
||||
- Be realistic — most projects don't need to scale to millions
|
||||
- Focus on "what breaks first" not theoretical limits
|
||||
- Avoid premature optimization recommendations
|
||||
|
||||
**Anti-Patterns:**
|
||||
- Specific to this domain
|
||||
- Include what to do instead
|
||||
- Helps prevent common mistakes during implementation
|
||||
|
||||
</guidelines>
|
||||
147
get-shit-done/templates/research-project/FEATURES.md
Normal file
147
get-shit-done/templates/research-project/FEATURES.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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>
|
||||
200
get-shit-done/templates/research-project/PITFALLS.md
Normal file
200
get-shit-done/templates/research-project/PITFALLS.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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>
|
||||
120
get-shit-done/templates/research-project/STACK.md
Normal file
120
get-shit-done/templates/research-project/STACK.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 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>
|
||||
170
get-shit-done/templates/research-project/SUMMARY.md
Normal file
170
get-shit-done/templates/research-project/SUMMARY.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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 create-roadmap workflow
|
||||
- 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 create-roadmap:**
|
||||
- This file is loaded as @context in create-roadmap
|
||||
- Phase suggestions here become starting point for roadmap
|
||||
- Research flags inform detect_research_needs step
|
||||
|
||||
</guidelines>
|
||||
@@ -9,7 +9,8 @@ that delivers value. The roadmap provides structure, not detailed tasks.
|
||||
1. ~/.claude/get-shit-done/templates/roadmap.md
|
||||
2. ~/.claude/get-shit-done/templates/state.md
|
||||
3. Read `.planning/PROJECT.md` if it exists
|
||||
</required_reading>
|
||||
4. Read `.planning/research/SUMMARY.md` if it exists
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
@@ -27,6 +28,39 @@ If proceeding without brief, gather quick context:
|
||||
- What's the rough scope?
|
||||
</step>
|
||||
|
||||
<step name="load_research">
|
||||
Check for project research:
|
||||
|
||||
```bash
|
||||
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
|
||||
```
|
||||
|
||||
**If RESEARCH_EXISTS:**
|
||||
|
||||
Read `.planning/research/SUMMARY.md` and extract:
|
||||
- Suggested phase structure from "Implications for Roadmap" section
|
||||
- Research flags for each suggested phase
|
||||
- Key findings that inform phase ordering
|
||||
|
||||
```
|
||||
Research found. Using findings to inform roadmap:
|
||||
|
||||
Suggested phases from research:
|
||||
1. [Phase from research] — [rationale]
|
||||
2. [Phase from research] — [rationale]
|
||||
3. [Phase from research] — [rationale]
|
||||
|
||||
Research confidence: [HIGH/MEDIUM/LOW]
|
||||
|
||||
Proceeding with research-informed phase identification...
|
||||
```
|
||||
|
||||
**If NO_RESEARCH:**
|
||||
|
||||
Continue without research context. Phase identification will rely on PROJECT.md and domain expertise only.
|
||||
|
||||
**Note:** Research is optional. Roadmap can be created without it, but research-informed roadmaps tend to have better phase structure and fewer surprises.
|
||||
</step>
|
||||
|
||||
<step name="detect_domain">
|
||||
Scan for available domain expertise:
|
||||
@@ -83,6 +117,15 @@ Select (comma-separate for multiple):
|
||||
<step name="identify_phases">
|
||||
Derive phases from the actual work needed.
|
||||
|
||||
**If research exists (.planning/research/SUMMARY.md):**
|
||||
- Start with suggested phases from research
|
||||
- Validate against PROJECT.md requirements
|
||||
- Adjust based on domain expertise (if any)
|
||||
- Research already identified dependencies and pitfalls — use them
|
||||
|
||||
**If no research:**
|
||||
- Derive phases from PROJECT.md and domain expertise only
|
||||
|
||||
**Check depth setting:**
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null | grep depth
|
||||
|
||||
315
get-shit-done/workflows/research-project.md
Normal file
315
get-shit-done/workflows/research-project.md
Normal file
@@ -0,0 +1,315 @@
|
||||
<purpose>
|
||||
Comprehensive domain research before roadmap creation.
|
||||
|
||||
Answers the questions that inform quality roadmaps:
|
||||
- What's the standard stack for this type of product?
|
||||
- What features do users expect?
|
||||
- How are these systems typically structured?
|
||||
- What do projects in this domain commonly get wrong?
|
||||
|
||||
This research shapes the roadmap. Without it, phases are guesses based on intuition.
|
||||
With it, phases reflect how experts actually build these systems.
|
||||
</purpose>
|
||||
|
||||
<when_to_use>
|
||||
**Use for:**
|
||||
- Greenfield projects in established domains
|
||||
- When "what features should exist" is partially unknown
|
||||
- Complex integrations requiring ecosystem knowledge
|
||||
- Any project where you'd research before starting
|
||||
|
||||
**Skip for:**
|
||||
- Well-defined specs with clear scope
|
||||
- Simple utilities
|
||||
- Brownfield features (use research-phase instead)
|
||||
</when_to_use>
|
||||
|
||||
<required_reading>
|
||||
**Read these files NOW:**
|
||||
|
||||
1. ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
|
||||
2. ~/.claude/get-shit-done/templates/research-project/STACK.md
|
||||
3. ~/.claude/get-shit-done/templates/research-project/FEATURES.md
|
||||
4. ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
|
||||
5. ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
|
||||
6. .planning/PROJECT.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="analyze_project">
|
||||
Read PROJECT.md and extract:
|
||||
|
||||
1. **Domain**: What type of product is this?
|
||||
- Community platform, e-commerce, SaaS tool, developer tool, mobile app, game, etc.
|
||||
|
||||
2. **Stated stack**: Did user specify technologies?
|
||||
- If yes: research how to use that stack for this domain
|
||||
- If no: research what stack is standard for this domain
|
||||
|
||||
3. **Core value**: What's the one thing that must work?
|
||||
|
||||
4. **Requirements**: What did user explicitly request?
|
||||
|
||||
5. **Constraints**: Any limitations on choices?
|
||||
|
||||
Present analysis:
|
||||
```
|
||||
Domain analysis:
|
||||
|
||||
- Type: [inferred domain]
|
||||
- Stack: [stated or "to be determined"]
|
||||
- Core: [core value from PROJECT.md]
|
||||
- Key requirements: [list]
|
||||
|
||||
Does this look right? (yes / adjust)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="determine_research_questions">
|
||||
Based on domain, generate 4 research questions:
|
||||
|
||||
| Dimension | Question Template |
|
||||
|-----------|-------------------|
|
||||
| Stack | "What's the standard 2025 stack for building [domain]?" |
|
||||
| Features | "What features do [domain] products have? What's table stakes vs. differentiating?" |
|
||||
| Architecture | "How are [domain] systems typically structured? What are the major components?" |
|
||||
| Pitfalls | "What do [domain] projects commonly get wrong? What are the critical mistakes?" |
|
||||
|
||||
**Customize questions based on project specifics:**
|
||||
|
||||
- If stack is stated: "How do you build [domain] with [stack]? What supporting libraries?"
|
||||
- If specific features mentioned: "How do experts implement [feature] in [domain]?"
|
||||
- If constraints exist: "What's the best approach for [domain] given [constraint]?"
|
||||
|
||||
Present questions for approval:
|
||||
```
|
||||
Research questions:
|
||||
|
||||
1. Stack: [question]
|
||||
2. Features: [question]
|
||||
3. Architecture: [question]
|
||||
4. Pitfalls: [question]
|
||||
|
||||
Proceed with these questions? (yes / adjust)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="spawn_research_agents">
|
||||
Spawn 4 parallel Task agents using subagent_type: "general-purpose".
|
||||
|
||||
**Agent prompt template:**
|
||||
|
||||
```
|
||||
Research question: [question]
|
||||
|
||||
Domain: [domain from analyze_project]
|
||||
Project context: [summary from PROJECT.md]
|
||||
|
||||
Instructions:
|
||||
1. Use Context7 to find relevant library documentation
|
||||
2. Use WebSearch to find current best practices (2024-2025)
|
||||
3. Cross-verify all WebSearch findings with authoritative sources
|
||||
4. Focus on actionable recommendations, not theoretical overview
|
||||
|
||||
Output format:
|
||||
- Direct answer to the question
|
||||
- Specific recommendations with rationale
|
||||
- Code examples where relevant
|
||||
- Sources with confidence levels (HIGH/MEDIUM/LOW)
|
||||
|
||||
Constraints:
|
||||
- Prefer official docs and Context7 over blog posts
|
||||
- Mark anything unverified as LOW confidence
|
||||
- Be specific: versions, library names, patterns
|
||||
```
|
||||
|
||||
**Spawn all 4 agents in parallel:**
|
||||
|
||||
```
|
||||
Spawning research agents:
|
||||
|
||||
1. Stack research → [running]
|
||||
2. Features research → [running]
|
||||
3. Architecture research → [running]
|
||||
4. Pitfalls research → [running]
|
||||
|
||||
This may take 2-3 minutes...
|
||||
```
|
||||
|
||||
Wait for all agents to complete.
|
||||
</step>
|
||||
|
||||
<step name="aggregate_results">
|
||||
Create `.planning/research/` directory:
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
**For each research dimension, create document using templates:**
|
||||
|
||||
1. **STACK.md** — From stack agent results
|
||||
- Use template from templates/research-project/STACK.md
|
||||
- Populate with agent findings
|
||||
- Include version numbers and rationale
|
||||
|
||||
2. **FEATURES.md** — From features agent results
|
||||
- Use template from templates/research-project/FEATURES.md
|
||||
- Categorize as table stakes / differentiators / anti-features
|
||||
- Note complexity and dependencies
|
||||
|
||||
3. **ARCHITECTURE.md** — From architecture agent results
|
||||
- Use template from templates/research-project/ARCHITECTURE.md
|
||||
- Include system diagrams (ASCII)
|
||||
- Document component responsibilities
|
||||
|
||||
4. **PITFALLS.md** — From pitfalls agent results
|
||||
- Use template from templates/research-project/PITFALLS.md
|
||||
- Include warning signs and prevention
|
||||
- Note which phase should address each pitfall
|
||||
|
||||
5. **SUMMARY.md** — Synthesize all results
|
||||
- Use template from templates/research-project/SUMMARY.md
|
||||
- Executive summary of all findings
|
||||
- **Critical: Include "Implications for Roadmap" section**
|
||||
- Suggest phase structure based on research
|
||||
</step>
|
||||
|
||||
<step name="roadmap_implications">
|
||||
In SUMMARY.md, include explicit roadmap guidance:
|
||||
|
||||
```markdown
|
||||
## Implications for Roadmap
|
||||
|
||||
Based on research, suggested phase structure:
|
||||
|
||||
1. **[Phase name]** — [rationale from research]
|
||||
- Addresses: [features from FEATURES.md]
|
||||
- Avoids: [pitfall from PITFALLS.md]
|
||||
|
||||
2. **[Phase name]** — [rationale from research]
|
||||
- Implements: [architecture component from ARCHITECTURE.md]
|
||||
- Uses: [stack element from STACK.md]
|
||||
|
||||
3. **[Phase name]** — [rationale from research]
|
||||
...
|
||||
|
||||
**Phase ordering rationale:**
|
||||
- [Why this order based on dependencies discovered]
|
||||
- [Why this grouping based on architecture patterns]
|
||||
|
||||
**Research flags for phases:**
|
||||
- Phase [X]: Likely needs deeper research (reason)
|
||||
- Phase [Y]: Standard patterns, unlikely to need research
|
||||
```
|
||||
|
||||
This section directly feeds into create-roadmap.
|
||||
</step>
|
||||
|
||||
<step name="confidence_assessment">
|
||||
Add confidence section to SUMMARY.md:
|
||||
|
||||
```markdown
|
||||
## Confidence Assessment
|
||||
|
||||
| Area | Confidence | Notes |
|
||||
|------|------------|-------|
|
||||
| Stack | [HIGH/MEDIUM/LOW] | [reason - e.g., "verified with Context7"] |
|
||||
| Features | [HIGH/MEDIUM/LOW] | [reason - e.g., "based on competitor analysis"] |
|
||||
| Architecture | [HIGH/MEDIUM/LOW] | [reason - e.g., "standard patterns, well-documented"] |
|
||||
| Pitfalls | [HIGH/MEDIUM/LOW] | [reason - e.g., "from post-mortems and community"] |
|
||||
|
||||
**Overall confidence:** [HIGH/MEDIUM/LOW]
|
||||
|
||||
**Gaps to address during planning:**
|
||||
- [Any areas where research was inconclusive]
|
||||
- [Topics that need phase-specific research later]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
Commit research:
|
||||
|
||||
```bash
|
||||
git add .planning/research/
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: research [domain] ecosystem
|
||||
|
||||
Researched stack, features, architecture, and pitfalls for [project name].
|
||||
|
||||
Key findings:
|
||||
- Stack: [one-liner]
|
||||
- Architecture: [one-liner]
|
||||
- Critical pitfall: [one-liner]
|
||||
|
||||
Ready for roadmap creation.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="present_results">
|
||||
```
|
||||
Research complete:
|
||||
|
||||
## Files Created
|
||||
|
||||
- .planning/research/SUMMARY.md — Executive summary + roadmap implications
|
||||
- .planning/research/STACK.md — Recommended technologies
|
||||
- .planning/research/FEATURES.md — Feature landscape
|
||||
- .planning/research/ARCHITECTURE.md — System structure patterns
|
||||
- .planning/research/PITFALLS.md — Common mistakes to avoid
|
||||
|
||||
## Key Findings
|
||||
|
||||
**Stack:** [one-liner from STACK.md]
|
||||
**Architecture:** [one-liner from ARCHITECTURE.md]
|
||||
**Critical pitfall:** [most important from PITFALLS.md]
|
||||
|
||||
## Suggested Phases
|
||||
|
||||
[List from SUMMARY.md Implications for Roadmap section]
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Create roadmap** — using research findings
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<research_quality>
|
||||
**Good research answers:**
|
||||
- What specific libraries/versions to use (not just "use React")
|
||||
- What features users expect (not just "add features")
|
||||
- How components connect (not just "it has a backend")
|
||||
- What specific mistakes to avoid (not just "be careful")
|
||||
|
||||
**Research is ready when:**
|
||||
- Each document has specific, actionable content
|
||||
- Sources are cited with confidence levels
|
||||
- Roadmap implications are explicit
|
||||
- A developer could start planning immediately
|
||||
</research_quality>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md analyzed, domain identified
|
||||
- [ ] Research questions customized and approved
|
||||
- [ ] 4 parallel agents spawned and completed
|
||||
- [ ] STACK.md created with specific recommendations
|
||||
- [ ] FEATURES.md created with prioritized features
|
||||
- [ ] ARCHITECTURE.md created with system structure
|
||||
- [ ] PITFALLS.md created with prevention strategies
|
||||
- [ ] SUMMARY.md created with roadmap implications
|
||||
- [ ] Confidence assessment included
|
||||
- [ ] Research committed to git
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user