golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(14-03): deprecate workflows/research-project.md

Browse Source 
- Workflow consolidated into gsd-researcher agent
- Points to agents/gsd-researcher.md as new location
- Kept file for git history traceability
This commit is contained in:
Lex Christopherson
2026-01-15 17:03:54 -06:00
parent 982faf16f8
commit fc67d2cd16
1 changed files with 14 additions and 417 deletions
Download Patch File Download Diff File Expand all files Collapse all files

431
get-shit-done/workflows/research-project.md
View File

@@ -1,426 +1,23 @@
<purpose>
Comprehensive domain research before roadmap creation.
# Research Project Workflow
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?
## DEPRECATED
This research shapes the roadmap. Without it, phases are guesses based on intuition.
With it, phases reflect how experts actually build these systems.
</purpose>
**This workflow has been consolidated into the gsd-researcher agent.**
<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
The research methodology for project research now lives in:
- `agents/gsd-researcher.md`
**Skip for:**
- Well-defined specs with clear scope
- Simple utilities
- Brownfield features (use research-phase instead)
</when_to_use>
The `/gsd:research-project` command spawns 4 parallel gsd-researcher agents:
- Stack agent -> .planning/research/STACK.md
- Features agent -> .planning/research/FEATURES.md
- Architecture agent -> .planning/research/ARCHITECTURE.md
- Pitfalls agent -> .planning/research/PITFALLS.md
<required_reading>
**Read these files NOW:**
The orchestrator synthesizes SUMMARY.md after all agents complete.
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. **Milestone context**: Is this a subsequent milestone?
- Check for "Current Milestone" section → this is v1.1+, not greenfield
- Check for "Validated" requirements → these are DONE, don't research them
- Focus on "Current Milestone target features" and "Active" requirements
5. **Requirements to research**:
- **If greenfield (no Validated):** Research all Active requirements
- **If subsequent milestone:** Research ONLY Current Milestone target features
6. **Constraints**: Any limitations on choices?
**For subsequent milestones, present:**
```
Milestone research context:
- Project: [name]
- Current milestone: v[X.Y] [Name]
- Already built (Validated): [count] requirements
- Researching (this milestone): [list target features]
This research focuses on the NEW features for v[X.Y], not the existing system.
Does this look right? (yes / adjust)
```
**For greenfield, present:**
```
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">
Generate research questions based on context:
**For greenfield (v1.0):**
| 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?" |
**For subsequent milestones (v1.1+):**
| Dimension | Question Template |
|-----------|-------------------|
| Stack | "What libraries/tools are needed to add [target features] to an existing [domain] app?" |
| Features | "How do [target features] typically work in [domain]? What's expected behavior?" |
| Architecture | "How do [target features] integrate with existing [domain] architecture?" |
| Pitfalls | "What are common mistakes when adding [target features] to [domain]?" |
**Customize questions based on project specifics:**
- If stack is stated: "How do you build [feature] 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 [feature] 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="setup_directory">
Create `.planning/research/` directory before spawning agents:
```bash
mkdir -p .planning/research
```
</step>
<step name="spawn_research_agents">
Spawn 4 parallel Task agents using subagent_type: "general-purpose".
**Each agent writes its own file directly.** This enables parallel writes and keeps the orchestrator lean.
**Agent prompts (spawn all 4 in parallel):**
**1. Stack Agent:**
```
Research: [stack question from determine_research_questions]
Domain: [domain]
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 findings with authoritative sources
4. Focus on actionable recommendations
When complete, write your findings to: .planning/research/STACK.md
Use this template structure:
- Read ~/.claude/get-shit-done/templates/research-project/STACK.md for format
- Include specific version numbers and rationale
- Cite sources with confidence levels (HIGH/MEDIUM/LOW)
- Be specific: versions, library names, exact patterns
Constraints:
- Prefer official docs and Context7 over blog posts
- Mark anything unverified as LOW confidence
```
**2. Features Agent:**
```
Research: [features question from determine_research_questions]
Domain: [domain]
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 findings with authoritative sources
4. Focus on what users actually expect
When complete, write your findings to: .planning/research/FEATURES.md
Use this template structure:
- Read ~/.claude/get-shit-done/templates/research-project/FEATURES.md for format
- Categorize as table stakes / differentiators / anti-features
- Note complexity and dependencies between features
- Cite sources with confidence levels (HIGH/MEDIUM/LOW)
Constraints:
- Prefer official docs and Context7 over blog posts
- Mark anything unverified as LOW confidence
```
**3. Architecture Agent:**
```
Research: [architecture question from determine_research_questions]
Domain: [domain]
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 findings with authoritative sources
4. Focus on how systems are actually structured
When complete, write your findings to: .planning/research/ARCHITECTURE.md
Use this template structure:
- Read ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md for format
- Include system diagrams (ASCII)
- Document component responsibilities and boundaries
- Cite sources with confidence levels (HIGH/MEDIUM/LOW)
Constraints:
- Prefer official docs and Context7 over blog posts
- Mark anything unverified as LOW confidence
```
**4. Pitfalls Agent:**
```
Research: [pitfalls question from determine_research_questions]
Domain: [domain]
Project context: [summary from PROJECT.md]
Instructions:
1. Use WebSearch to find post-mortems and failure cases
2. Look for community discussions about common mistakes
3. Find what experienced developers warn against
4. Focus on preventable mistakes, not edge cases
When complete, write your findings to: .planning/research/PITFALLS.md
Use this template structure:
- Read ~/.claude/get-shit-done/templates/research-project/PITFALLS.md for format
- Include warning signs and prevention strategies
- Note which phase should address each pitfall
- Cite sources with confidence levels (HIGH/MEDIUM/LOW)
Constraints:
- Prefer post-mortems and experienced developers over generic advice
- Mark anything unverified as LOW confidence
```
**Spawn all 4 agents in parallel:**
```
Spawning research agents (each writes its own file):
1. Stack research → .planning/research/STACK.md
2. Features research → .planning/research/FEATURES.md
3. Architecture research → .planning/research/ARCHITECTURE.md
4. Pitfalls research → .planning/research/PITFALLS.md
This may take 2-3 minutes...
```
Wait for all agents to complete.
</step>
<step name="write_summary">
After all agents complete, read their outputs and synthesize SUMMARY.md:
```bash
# Verify all files exist
ls .planning/research/
```
Read each file:
- .planning/research/STACK.md
- .planning/research/FEATURES.md
- .planning/research/ARCHITECTURE.md
- .planning/research/PITFALLS.md
Write `.planning/research/SUMMARY.md` using template from `templates/research-project/SUMMARY.md`:
- Executive summary synthesizing all findings
- **Critical: Include "Implications for Roadmap" section**
- Suggest phase structure based on research
- Cross-reference findings across all documents
</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]
**Migration:** No action needed - the command handles this automatically.
---
## ▶ Next Up
**Define requirements** — scope your v1 from research findings
`/gsd:define-requirements`
<sub>`/clear` first → fresh context window</sub>
**Flow:** research-project → **define-requirements** → create-roadmap
---
```
</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
- [ ] .planning/research/ directory created
- [ ] 4 parallel agents spawned (each writes its own file)
- [ ] STACK.md written by stack agent
- [ ] FEATURES.md written by features agent
- [ ] ARCHITECTURE.md written by architecture agent
- [ ] PITFALLS.md written by pitfalls agent
- [ ] All agent files verified to exist
- [ ] SUMMARY.md written by orchestrator (synthesizes all)
- [ ] Confidence assessment included in SUMMARY.md
- [ ] Research committed to git
</success_criteria>
*Deprecated: 2026-01-15*
*Replaced by: agents/gsd-researcher.md*