From e8d68685c1091c73eaf6740b6825466f55779464 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Mon, 15 Dec 2025 18:15:22 -0600 Subject: [PATCH] feat(gsd): add research-phase for niche domain ecosystem discovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add /gsd:research-phase command for comprehensive ecosystem research - Rename FINDINGS.md → DISCOVERY.md for clarity - Rename research-phase.md → discovery-phase.md (shallow "which library") - New research-phase.md for deep "how experts build this" research - Creates RESEARCH.md with stack, patterns, pitfalls, don't-hand-roll - plan-phase loads RESEARCH.md when present 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- commands/gsd/help.md | 19 + commands/gsd/research-phase.md | 90 +++ get-shit-done/references/git-integration.md | 4 +- get-shit-done/references/plan-format.md | 2 +- get-shit-done/references/scope-estimation.md | 6 +- .../{research-prompt.md => discovery.md} | 57 +- get-shit-done/templates/phase-prompt.md | 4 +- get-shit-done/templates/research.md | 529 ++++++++++++++ get-shit-done/workflows/discovery-phase.md | 293 ++++++++ get-shit-done/workflows/plan-phase.md | 72 +- get-shit-done/workflows/research-phase.md | 661 +++++++++++------- 11 files changed, 1416 insertions(+), 321 deletions(-) create mode 100644 commands/gsd/research-phase.md rename get-shit-done/templates/{research-prompt.md => discovery.md} (70%) create mode 100644 get-shit-done/templates/research.md create mode 100644 get-shit-done/workflows/discovery-phase.md diff --git a/commands/gsd/help.md b/commands/gsd/help.md index cb3f94051..aee09a1bf 100644 --- a/commands/gsd/help.md +++ b/commands/gsd/help.md @@ -55,6 +55,16 @@ Gather phase context through adaptive questioning before planning. Usage: `/gsd:discuss-phase 2` +**`/gsd:research-phase `** +Comprehensive ecosystem research for niche/complex domains. + +- Discovers standard stack, architecture patterns, pitfalls +- Creates RESEARCH.md with "how experts build this" knowledge +- Use for 3D, games, audio, shaders, ML, and other specialized domains +- Goes beyond "which library" to ecosystem knowledge + +Usage: `/gsd:research-phase 3` + **`/gsd:list-phase-assumptions `** Surface Claude's assumptions about a phase before planning. @@ -236,6 +246,15 @@ Change anytime by editing `.planning/config.json` /gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md ``` +**Building something in a niche domain (3D, games, audio, shaders):** + +``` +/gsd:new-project +/gsd:research-phase 1 # Learn how experts build this +/gsd:plan-phase 1 # Plan using research findings +/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md +``` + **Resuming work after a break:** ``` diff --git a/commands/gsd/research-phase.md b/commands/gsd/research-phase.md new file mode 100644 index 000000000..afd08bed8 --- /dev/null +++ b/commands/gsd/research-phase.md @@ -0,0 +1,90 @@ +--- +description: Research how to implement a phase before planning +argument-hint: "[phase]" +allowed-tools: + - Read + - Bash + - Glob + - Grep + - Write + - WebFetch + - WebSearch + - mcp__context7__* +--- + + +Comprehensive research on HOW to implement a phase before planning. + +This is for niche/complex domains where Claude's training data is sparse or outdated. Research discovers: +- What libraries exist for this problem +- What architecture patterns experts use +- What the standard stack looks like +- What problems people commonly hit +- What NOT to hand-roll (use existing solutions) + +Output: RESEARCH.md with ecosystem knowledge that informs quality planning. + + + +@~/.claude/get-shit-done/workflows/research-phase.md +@~/.claude/get-shit-done/templates/research.md +@~/.claude/get-shit-done/references/research-pitfalls.md + + + +Phase number: $ARGUMENTS (required) + +**Load project state:** +@.planning/STATE.md + +**Load roadmap:** +@.planning/ROADMAP.md + +**Load phase context if exists:** +Check for `.planning/phases/XX-name/{phase}-CONTEXT.md` - bonus context from discuss-phase. + + + +1. Validate phase number argument (error if missing or invalid) +2. Check if phase exists in roadmap - extract phase description +3. Check if RESEARCH.md already exists (offer to update or use existing) +4. Load CONTEXT.md if it exists (bonus context for research direction) +5. Follow research-phase.md workflow: + - Analyze phase to identify knowledge gaps + - Determine research domains (architecture, ecosystem, patterns, pitfalls) + - Execute comprehensive research via Context7, official docs, WebSearch + - Cross-verify all findings + - Create RESEARCH.md with actionable ecosystem knowledge +6. Offer next steps (plan the phase) + + + +**Use research-phase for:** +- 3D graphics (Three.js, WebGL, procedural generation) +- Game development (physics, collision, AI, procedural content) +- Audio/music (Web Audio API, DSP, synthesis) +- Shaders (GLSL, Metal, ISF) +- ML/AI integration (model serving, inference, pipelines) +- Real-time systems (WebSockets, WebRTC, sync) +- Specialized frameworks with active ecosystems +- Any domain where "how do experts do this" matters + +**Skip research-phase for:** +- Standard web dev (auth, CRUD, REST APIs) +- Well-known patterns (forms, validation, testing) +- Simple integrations (Stripe, SendGrid with clear docs) +- Commodity features Claude handles well + + + +- [ ] Phase validated against roadmap +- [ ] Domain/ecosystem identified from phase description +- [ ] Comprehensive research executed (Context7 + official docs + WebSearch) +- [ ] All WebSearch findings cross-verified with authoritative sources +- [ ] RESEARCH.md created with ecosystem knowledge +- [ ] Standard stack/libraries identified +- [ ] Architecture patterns documented +- [ ] Common pitfalls catalogued +- [ ] What NOT to hand-roll is clear +- [ ] User knows next steps (plan phase) + diff --git a/get-shit-done/references/git-integration.md b/get-shit-done/references/git-integration.md index fe1db8da8..3fd8e21a4 100644 --- a/get-shit-done/references/git-integration.md +++ b/get-shit-done/references/git-integration.md @@ -16,7 +16,7 @@ The git log should read like a changelog of what shipped, not a diary of plannin | BRIEF + ROADMAP created | YES | Project initialization | | PLAN.md created | NO | Intermediate - commit with completion | | RESEARCH.md created | NO | Intermediate | -| FINDINGS.md created | NO | Intermediate | +| DISCOVERY.md created | NO | Intermediate | | **Phase completed** | YES | Actual code shipped | | Handoff created | YES | WIP state preserved | @@ -118,7 +118,7 @@ e]2f4a8 docs: initialize ecommerce-app (5 phases) - PLAN.md creation (wait for phase completion) - RESEARCH.md (intermediate) -- FINDINGS.md (intermediate) +- DISCOVERY.md (intermediate) - Minor planning tweaks - "Fixed typo in roadmap" diff --git a/get-shit-done/references/plan-format.md b/get-shit-done/references/plan-format.md index 01a7d262f..91d058344 100644 --- a/get-shit-done/references/plan-format.md +++ b/get-shit-done/references/plan-format.md @@ -250,7 +250,7 @@ Use @file references to load context for the prompt: @.planning/PROJECT.md # Project vision @.planning/ROADMAP.md # Phase structure -@.planning/phases/02-auth/FINDINGS.md # Research results +@.planning/phases/02-auth/DISCOVERY.md # Discovery results @src/lib/db.ts # Existing database setup @src/types/user.ts # Existing type definitions diff --git a/get-shit-done/references/scope-estimation.md b/get-shit-done/references/scope-estimation.md index 6ea42dfa9..7c088cf8b 100644 --- a/get-shit-done/references/scope-estimation.md +++ b/get-shit-done/references/scope-estimation.md @@ -130,9 +130,9 @@ Total: 16 files, 3 plans → consistent quality - 02-01-PLAN.md: Setup (checkpoint: decision on auth provider) - 02-02-PLAN.md: Implement chosen auth solution -**5. Research + implementation** -- Research produces FINDINGS.md (separate plan) -- Implementation consumes FINDINGS.md (separate plan) +**5. Discovery + implementation** +- Discovery produces DISCOVERY.md (separate plan) +- Implementation consumes DISCOVERY.md (separate plan) - Clear boundary, clean handoff diff --git a/get-shit-done/templates/research-prompt.md b/get-shit-done/templates/discovery.md similarity index 70% rename from get-shit-done/templates/research-prompt.md rename to get-shit-done/templates/discovery.md index 5724bf3dc..b9e2bb641 100644 --- a/get-shit-done/templates/research-prompt.md +++ b/get-shit-done/templates/discovery.md @@ -1,31 +1,39 @@ -# Research Prompt Template +# Discovery Template -For phases requiring research before planning: +Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for library/option decisions. + +**Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase. + +For deep ecosystem research ("how do experts build this"), use `/gsd:research-phase` which produces RESEARCH.md. + +--- + +## File Template ```markdown --- phase: XX-name -type: research -topic: [research-topic] +type: discovery +topic: [discovery-topic] --- -Before beginning research, verify today's date: +Before beginning discovery, verify today's date: !`date +%Y-%m-%d` Use this date when searching for "current" or "latest" information. Example: If today is 2025-11-22, search for "2025" not "2024". - -Research [topic] to inform [phase name] implementation. + +Discover [topic] to inform [phase name] implementation. Purpose: [What decision/implementation this enables] Scope: [Boundaries] -Output: FINDINGS.md with structured recommendations - +Output: DISCOVERY.md with recommendation + - + - [Question to answer] - [Area to investigate] @@ -33,12 +41,12 @@ Output: FINDINGS.md with structured recommendations -- [Out of scope for this research] +- [Out of scope for this discovery] - [Defer to implementation phase] - + - + **Source Priority:** 1. **Context7 MCP** - For library/framework documentation (current, authoritative) @@ -46,7 +54,7 @@ Output: FINDINGS.md with structured recommendations 3. **WebSearch** - For comparisons, trends, community patterns (verify all findings) **Quality Checklist:** -Before completing research, verify: +Before completing discovery, verify: - [ ] All claims have authoritative sources (Context7 or official docs) - [ ] Negative claims ("X is not possible") verified with official documentation - [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone) @@ -59,14 +67,14 @@ Before completing research, verify: - MEDIUM: WebSearch + Context7/official docs confirm - LOW: WebSearch only or training knowledge only (mark for validation) - + -Create `.planning/phases/XX-name/FINDINGS.md`: +Create `.planning/phases/XX-name/DISCOVERY.md`: ```markdown -# [Topic] Research Findings +# [Topic] Discovery ## Summary [2-3 paragraph executive summary - what was researched, what was found, what's recommended] @@ -119,15 +127,20 @@ Create `.planning/phases/XX-name/FINDINGS.md`: -**When to use research prompts:** -- Technology choice unclear -- Best practices needed for unfamiliar domain +**When to use discovery:** +- Technology choice unclear (library A vs B) +- Best practices needed for unfamiliar integration - API/library investigation required -- Architecture decision pending -- Multiple valid approaches exist +- Single decision pending **When NOT to use:** - Established patterns (CRUD, auth with known library) - Implementation details (defer to execution) - Questions answerable from existing project context + +**When to use RESEARCH.md instead:** +- Niche/complex domains (3D, games, audio, shaders) +- Need ecosystem knowledge, not just library choice +- "How do experts build this" questions +- Use `/gsd:research-phase` for these diff --git a/get-shit-done/templates/phase-prompt.md b/get-shit-done/templates/phase-prompt.md index 02150c7e4..63086d453 100644 --- a/get-shit-done/templates/phase-prompt.md +++ b/get-shit-done/templates/phase-prompt.md @@ -32,8 +32,8 @@ Output: [What artifacts will be created] @.planning/PROJECT.md @.planning/ROADMAP.md -[If research exists:] -@.planning/phases/XX-name/FINDINGS.md +[If discovery exists:] +@.planning/phases/XX-name/DISCOVERY.md [Relevant source files:] @src/path/to/relevant.ts diff --git a/get-shit-done/templates/research.md b/get-shit-done/templates/research.md new file mode 100644 index 000000000..3f18ea1f8 --- /dev/null +++ b/get-shit-done/templates/research.md @@ -0,0 +1,529 @@ +# Research Template + +Template for `.planning/phases/XX-name/{phase}-RESEARCH.md` - comprehensive ecosystem research before planning. + +**Purpose:** Document what Claude needs to know to implement a phase well - not just "which library" but "how do experts build this." + +--- + +## File Template + +```markdown +# Phase [X]: [Name] - Research + +**Researched:** [date] +**Domain:** [primary technology/problem domain] +**Confidence:** [HIGH/MEDIUM/LOW] + + +## Summary + +[2-3 paragraph executive summary] +- What was researched +- What the standard approach is +- Key recommendations + +**Primary recommendation:** [one-liner actionable guidance] + + + +## Standard Stack + +The established libraries/tools for this domain: + +### Core +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| [name] | [ver] | [what it does] | [why experts use it] | +| [name] | [ver] | [what it does] | [why experts use it] | + +### Supporting +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| [name] | [ver] | [what it does] | [use case] | +| [name] | [ver] | [what it does] | [use case] | + +### Alternatives Considered +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| [standard] | [alternative] | [when alternative makes sense] | + +**Installation:** +```bash +npm install [packages] +# or +yarn add [packages] +``` + + + +## Architecture Patterns + +### Recommended Project Structure +``` +src/ +├── [folder]/ # [purpose] +├── [folder]/ # [purpose] +└── [folder]/ # [purpose] +``` + +### Pattern 1: [Pattern Name] +**What:** [description] +**When to use:** [conditions] +**Example:** +```typescript +// [code example from Context7/official docs] +``` + +### Pattern 2: [Pattern Name] +**What:** [description] +**When to use:** [conditions] +**Example:** +```typescript +// [code example] +``` + +### Anti-Patterns to Avoid +- **[Anti-pattern]:** [why it's bad, what to do instead] +- **[Anti-pattern]:** [why it's bad, what to do instead] + + + +## Don't Hand-Roll + +Problems that look simple but have existing solutions: + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| [problem] | [what you'd build] | [library] | [edge cases, complexity] | +| [problem] | [what you'd build] | [library] | [edge cases, complexity] | +| [problem] | [what you'd build] | [library] | [edge cases, complexity] | + +**Key insight:** [why custom solutions are worse in this domain] + + + +## Common Pitfalls + +### Pitfall 1: [Name] +**What goes wrong:** [description] +**Why it happens:** [root cause] +**How to avoid:** [prevention strategy] +**Warning signs:** [how to detect early] + +### Pitfall 2: [Name] +**What goes wrong:** [description] +**Why it happens:** [root cause] +**How to avoid:** [prevention strategy] +**Warning signs:** [how to detect early] + +### Pitfall 3: [Name] +**What goes wrong:** [description] +**Why it happens:** [root cause] +**How to avoid:** [prevention strategy] +**Warning signs:** [how to detect early] + + + +## Code Examples + +Verified patterns from official sources: + +### [Common Operation 1] +```typescript +// Source: [Context7/official docs URL] +[code] +``` + +### [Common Operation 2] +```typescript +// Source: [Context7/official docs URL] +[code] +``` + +### [Common Operation 3] +```typescript +// Source: [Context7/official docs URL] +[code] +``` + + + +## State of the Art (2024-2025) + +What's changed recently: + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| [old] | [new] | [date/version] | [what it means for implementation] | + +**New tools/patterns to consider:** +- [Tool/Pattern]: [what it enables, when to use] +- [Tool/Pattern]: [what it enables, when to use] + +**Deprecated/outdated:** +- [Thing]: [why it's outdated, what replaced it] + + + +## Open Questions + +Things that couldn't be fully resolved: + +1. **[Question]** + - What we know: [partial info] + - What's unclear: [the gap] + - Recommendation: [how to handle during planning/execution] + +2. **[Question]** + - What we know: [partial info] + - What's unclear: [the gap] + - Recommendation: [how to handle] + + + +## Sources + +### Primary (HIGH confidence) +- [Context7 library ID] - [topics fetched] +- [Official docs URL] - [what was checked] + +### Secondary (MEDIUM confidence) +- [WebSearch verified with official source] - [finding + verification] + +### Tertiary (LOW confidence - needs validation) +- [WebSearch only] - [finding, marked for validation during implementation] + + + +## Metadata + +**Research scope:** +- Core technology: [what] +- Ecosystem: [libraries explored] +- Patterns: [patterns researched] +- Pitfalls: [areas checked] + +**Confidence breakdown:** +- Standard stack: [HIGH/MEDIUM/LOW] - [reason] +- Architecture: [HIGH/MEDIUM/LOW] - [reason] +- Pitfalls: [HIGH/MEDIUM/LOW] - [reason] +- Code examples: [HIGH/MEDIUM/LOW] - [reason] + +**Research date:** [date] +**Valid until:** [estimate - 30 days for stable tech, 7 days for fast-moving] + + +--- + +*Phase: XX-name* +*Research completed: [date]* +*Ready for planning: [yes/no]* +``` + +--- + +## Good Example + +```markdown +# Phase 3: 3D City Driving - Research + +**Researched:** 2025-01-20 +**Domain:** Three.js 3D web game with driving mechanics +**Confidence:** HIGH + + +## Summary + +Researched the Three.js ecosystem for building a 3D city driving game. The standard approach uses Three.js with React Three Fiber for component architecture, Rapier for physics, and drei for common helpers. + +Key finding: Don't hand-roll physics or collision detection. Rapier (via @react-three/rapier) handles vehicle physics, terrain collision, and city object interactions efficiently. Custom physics code leads to bugs and performance issues. + +**Primary recommendation:** Use R3F + Rapier + drei stack. Start with vehicle controller from drei, add Rapier vehicle physics, build city with instanced meshes for performance. + + + +## Standard Stack + +### Core +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| three | 0.160.0 | 3D rendering | The standard for web 3D | +| @react-three/fiber | 8.15.0 | React renderer for Three.js | Declarative 3D, better DX | +| @react-three/drei | 9.92.0 | Helpers and abstractions | Solves common problems | +| @react-three/rapier | 1.2.1 | Physics engine bindings | Best physics for R3F | + +### Supporting +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| @react-three/postprocessing | 2.16.0 | Visual effects | Bloom, DOF, motion blur | +| leva | 0.9.35 | Debug UI | Tweaking parameters | +| zustand | 4.4.7 | State management | Game state, UI state | +| use-sound | 4.0.1 | Audio | Engine sounds, ambient | + +### Alternatives Considered +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| Rapier | Cannon.js | Cannon simpler but less performant for vehicles | +| R3F | Vanilla Three | Vanilla if no React, but R3F DX is much better | +| drei | Custom helpers | drei is battle-tested, don't reinvent | + +**Installation:** +```bash +npm install three @react-three/fiber @react-three/drei @react-three/rapier zustand +``` + + + +## Architecture Patterns + +### Recommended Project Structure +``` +src/ +├── components/ +│ ├── Vehicle/ # Player car with physics +│ ├── City/ # City generation and buildings +│ ├── Road/ # Road network +│ └── Environment/ # Sky, lighting, fog +├── hooks/ +│ ├── useVehicleControls.ts +│ └── useGameState.ts +├── stores/ +│ └── gameStore.ts # Zustand state +└── utils/ + └── cityGenerator.ts # Procedural generation helpers +``` + +### Pattern 1: Vehicle with Rapier Physics +**What:** Use RigidBody with vehicle-specific settings, not custom physics +**When to use:** Any ground vehicle +**Example:** +```typescript +// Source: @react-three/rapier docs +import { RigidBody, useRapier } from '@react-three/rapier' + +function Vehicle() { + const rigidBody = useRef() + + return ( + + + + + + + ) +} +``` + +### Pattern 2: Instanced Meshes for City +**What:** Use InstancedMesh for repeated objects (buildings, trees, props) +**When to use:** >100 similar objects +**Example:** +```typescript +// Source: drei docs +import { Instances, Instance } from '@react-three/drei' + +function Buildings({ positions }) { + return ( + + + + {positions.map((pos, i) => ( + + ))} + + ) +} +``` + +### Anti-Patterns to Avoid +- **Creating meshes in render loop:** Create once, update transforms only +- **Not using InstancedMesh:** Individual meshes for buildings kills performance +- **Custom physics math:** Rapier handles it better, every time + + + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| Vehicle physics | Custom velocity/acceleration | Rapier RigidBody | Wheel friction, suspension, collisions are complex | +| Collision detection | Raycasting everything | Rapier colliders | Performance, edge cases, tunneling | +| Camera follow | Manual lerp | drei CameraControls or custom with useFrame | Smooth interpolation, bounds | +| City generation | Pure random placement | Grid-based with noise for variation | Random looks wrong, grid is predictable | +| LOD | Manual distance checks | drei | Handles transitions, hysteresis | + +**Key insight:** 3D game development has 40+ years of solved problems. Rapier implements proper physics simulation. drei implements proper 3D helpers. Fighting these leads to bugs that look like "game feel" issues but are actually physics edge cases. + + + +## Common Pitfalls + +### Pitfall 1: Physics Tunneling +**What goes wrong:** Fast objects pass through walls +**Why it happens:** Default physics step too large for velocity +**How to avoid:** Use CCD (Continuous Collision Detection) in Rapier +**Warning signs:** Objects randomly appearing outside buildings + +### Pitfall 2: Performance Death by Draw Calls +**What goes wrong:** Game stutters with many buildings +**Why it happens:** Each mesh = 1 draw call, hundreds of buildings = hundreds of calls +**How to avoid:** InstancedMesh for similar objects, merge static geometry +**Warning signs:** GPU bound, low FPS despite simple scene + +### Pitfall 3: Vehicle "Floaty" Feel +**What goes wrong:** Car doesn't feel grounded +**Why it happens:** Missing proper wheel/suspension simulation +**How to avoid:** Use Rapier vehicle controller or tune mass/damping carefully +**Warning signs:** Car bounces oddly, doesn't grip corners + + + +## Code Examples + +### Basic R3F + Rapier Setup +```typescript +// Source: @react-three/rapier getting started +import { Canvas } from '@react-three/fiber' +import { Physics } from '@react-three/rapier' + +function Game() { + return ( + + + + + + + + ) +} +``` + +### Vehicle Controls Hook +```typescript +// Source: Community pattern, verified with drei docs +import { useFrame } from '@react-three/fiber' +import { useKeyboardControls } from '@react-three/drei' + +function useVehicleControls(rigidBodyRef) { + const [, getKeys] = useKeyboardControls() + + useFrame(() => { + const { forward, back, left, right } = getKeys() + const body = rigidBodyRef.current + if (!body) return + + const impulse = { x: 0, y: 0, z: 0 } + if (forward) impulse.z -= 10 + if (back) impulse.z += 5 + + body.applyImpulse(impulse, true) + + if (left) body.applyTorqueImpulse({ x: 0, y: 2, z: 0 }, true) + if (right) body.applyTorqueImpulse({ x: 0, y: -2, z: 0 }, true) + }) +} +``` + + + +## State of the Art (2024-2025) + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| cannon-es | Rapier | 2023 | Rapier is faster, better maintained | +| vanilla Three.js | React Three Fiber | 2020+ | R3F is now standard for React apps | +| Manual InstancedMesh | drei | 2022 | Simpler API, handles updates | + +**New tools/patterns to consider:** +- **WebGPU:** Coming but not production-ready for games yet (2025) +- **drei Gltf helpers:** for loading screens + +**Deprecated/outdated:** +- **cannon.js (original):** Use cannon-es fork or better, Rapier +- **Manual raycasting for physics:** Just use Rapier colliders + + + +## Sources + +### Primary (HIGH confidence) +- /pmndrs/react-three-fiber - getting started, hooks, performance +- /pmndrs/drei - instances, controls, helpers +- /dimforge/rapier-js - physics setup, vehicle physics + +### Secondary (MEDIUM confidence) +- Three.js discourse "city driving game" threads - verified patterns against docs +- R3F examples repository - verified code works + +### Tertiary (LOW confidence - needs validation) +- None - all findings verified + + + +## Metadata + +**Research scope:** +- Core technology: Three.js + React Three Fiber +- Ecosystem: Rapier, drei, zustand +- Patterns: Vehicle physics, instancing, city generation +- Pitfalls: Performance, physics, feel + +**Confidence breakdown:** +- Standard stack: HIGH - verified with Context7, widely used +- Architecture: HIGH - from official examples +- Pitfalls: HIGH - documented in discourse, verified in docs +- Code examples: HIGH - from Context7/official sources + +**Research date:** 2025-01-20 +**Valid until:** 2025-02-20 (30 days - R3F ecosystem stable) + + +--- + +*Phase: 03-city-driving* +*Research completed: 2025-01-20* +*Ready for planning: yes* +``` + +--- + +## Guidelines + +**When to create:** +- Before planning phases in niche/complex domains +- When Claude's training data is likely stale or sparse +- When "how do experts do this" matters more than "which library" + +**Structure:** +- Use XML tags for section markers (matches GSD templates) +- Seven core sections: summary, standard_stack, architecture_patterns, dont_hand_roll, common_pitfalls, code_examples, sources +- All sections required (drives comprehensive research) + +**Content quality:** +- Standard stack: Specific versions, not just names +- Architecture: Include actual code examples from authoritative sources +- Don't hand-roll: Be explicit about what problems to NOT solve yourself +- Pitfalls: Include warning signs, not just "don't do this" +- Sources: Mark confidence levels honestly + +**Integration with planning:** +- RESEARCH.md loaded as @context reference in PLAN.md +- Standard stack informs library choices +- Don't hand-roll prevents custom solutions +- Pitfalls inform verification criteria +- Code examples can be referenced in task actions + +**After creation:** +- File lives in phase directory: `.planning/phases/XX-name/{phase}-RESEARCH.md` +- Referenced during planning workflow +- plan-phase loads it automatically when present diff --git a/get-shit-done/workflows/discovery-phase.md b/get-shit-done/workflows/discovery-phase.md new file mode 100644 index 000000000..5fcb2a821 --- /dev/null +++ b/get-shit-done/workflows/discovery-phase.md @@ -0,0 +1,293 @@ + +Execute discovery at the appropriate depth level. +Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation. + +Called from plan-phase.md's mandatory_discovery step with a depth parameter. + +NOTE: For comprehensive ecosystem research ("how do experts build this"), use /gsd:research-phase instead, which produces RESEARCH.md. + + + +**This workflow supports three depth levels:** + +| Level | Name | Time | Output | When | +| ----- | ------------ | --------- | -------------------------------------------- | ----------------------------------------- | +| 1 | Quick Verify | 2-5 min | No file, proceed with verified knowledge | Single library, confirming current syntax | +| 2 | Standard | 15-30 min | DISCOVERY.md | Choosing between options, new integration | +| 3 | Deep Dive | 1+ hour | Detailed DISCOVERY.md with validation gates | Architectural decisions, novel problems | + +**Depth is determined by plan-phase.md before routing here.** + + + +**MANDATORY: Context7 BEFORE WebSearch** + +Claude's training data is 6-18 months stale. Always verify. + +1. **Context7 MCP FIRST** - Current docs, no hallucination +2. **Official docs** - When Context7 lacks coverage +3. **WebSearch LAST** - For comparisons and trends only + +See ~/.claude/get-shit-done/templates/discovery.md `` for full protocol. + + + + + +Check the depth parameter passed from plan-phase.md: +- `depth=verify` → Level 1 (Quick Verification) +- `depth=standard` → Level 2 (Standard Discovery) +- `depth=deep` → Level 3 (Deep Dive) + +Route to appropriate level workflow below. + + + +**Level 1: Quick Verification (2-5 minutes)** + +For: Single known library, confirming syntax/version still correct. + +**Process:** + +1. Resolve library in Context7: + + ``` + mcp__context7__resolve-library-id with libraryName: "[library]" + ``` + +2. Fetch relevant docs: + + ``` + mcp__context7__get-library-docs with: + - context7CompatibleLibraryID: [from step 1] + - topic: [specific concern] + ``` + +3. Verify: + + - Current version matches expectations + - API syntax unchanged + - No breaking changes in recent versions + +4. **If verified:** Return to plan-phase.md with confirmation. No DISCOVERY.md needed. + +5. **If concerns found:** Escalate to Level 2. + +**Output:** Verbal confirmation to proceed, or escalation to Level 2. + + + +**Level 2: Standard Discovery (15-30 minutes)** + +For: Choosing between options, new external integration. + +**Process:** + +1. **Identify what to discover:** + + - What options exist? + - What are the key comparison criteria? + - What's our specific use case? + +2. **Context7 for each option:** + + ``` + For each library/framework: + - mcp__context7__resolve-library-id + - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts) + ``` + +3. **Official docs** for anything Context7 lacks. + +4. **WebSearch** for comparisons: + + - "[option A] vs [option B] {current_year}" + - "[option] known issues" + - "[option] with [our stack]" + +5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs. + +6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to avoid common research gaps. + +7. **Create DISCOVERY.md** using ~/.claude/get-shit-done/templates/discovery.md structure: + + - Summary with recommendation + - Key findings per option + - Code examples from Context7 + - Confidence level (should be MEDIUM-HIGH for Level 2) + +8. Return to plan-phase.md. + +**Output:** `.planning/phases/XX-name/DISCOVERY.md` + + + +**Level 3: Deep Dive (1+ hour)** + +For: Architectural decisions, novel problems, high-risk choices. + +**Process:** + +1. **Scope the discovery** using ~/.claude/get-shit-done/templates/discovery.md: + + - Define clear scope + - Define include/exclude boundaries + - List specific questions to answer + +2. **Exhaustive Context7 research:** + + - All relevant libraries + - Related patterns and concepts + - Multiple topics per library if needed + +3. **Official documentation deep read:** + + - Architecture guides + - Best practices sections + - Migration/upgrade guides + - Known limitations + +4. **WebSearch for ecosystem context:** + + - How others solved similar problems + - Production experiences + - Gotchas and anti-patterns + - Recent changes/announcements + +5. **Cross-verify ALL findings:** + + - Every WebSearch claim → verify with authoritative source + - Mark what's verified vs assumed + - Flag contradictions + +6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps. + +7. **Create comprehensive DISCOVERY.md:** + + - Full structure from ~/.claude/get-shit-done/templates/discovery.md + - Quality report with source attribution + - Confidence by finding + - If LOW confidence on any critical finding → add validation checkpoints + +8. **Confidence gate:** If overall confidence is LOW, present options before proceeding. + +9. Return to plan-phase.md. + +**Output:** `.planning/phases/XX-name/DISCOVERY.md` (comprehensive) + + + +**For Level 2-3:** Define what we need to learn. + +Ask: What do we need to learn before we can plan this phase? + +- Technology choices? +- Best practices? +- API patterns? +- Architecture approach? + + + +Use ~/.claude/get-shit-done/templates/discovery.md. + +Include: + +- Clear discovery objective +- Scoped include/exclude lists +- Source preferences (official docs, Context7, current year) +- Output structure for DISCOVERY.md + + + +Run the discovery: +- Use web search for current info +- Use Context7 MCP for library docs +- Prefer current year sources +- Structure findings per template + + + +Write `.planning/phases/XX-name/DISCOVERY.md`: +- Summary with recommendation +- Key findings with sources +- Code examples if applicable +- Metadata (confidence, dependencies, open questions, assumptions) + + + +After creating DISCOVERY.md, check confidence level. + +If confidence is LOW: +Use AskUserQuestion: + +- header: "Low Confidence" +- question: "Discovery confidence is LOW: [reason]. How would you like to proceed?" +- options: + - "Dig deeper" - Do more research before planning + - "Proceed anyway" - Accept uncertainty, plan with caveats + - "Pause" - I need to think about this + +If confidence is MEDIUM: +Inline: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?" + +If confidence is HIGH: +Proceed directly, just note: "Discovery complete (high confidence)." + + + +If DISCOVERY.md has open_questions: + +Present them inline: +"Open questions from discovery: + +- [Question 1] +- [Question 2] + +These may affect implementation. Acknowledge and proceed? (yes / address first)" + +If "address first": Gather user input on questions, update discovery. + + + +``` +Discovery complete: .planning/phases/XX-name/DISCOVERY.md +Recommendation: [one-liner] +Confidence: [level] + +What's next? + +1. Discuss phase context (/gsd:discuss-phase [current-phase]) +2. Create phase plan (/gsd:plan-phase [current-phase]) +3. Refine discovery (dig deeper) +4. Review discovery + +``` + +NOTE: DISCOVERY.md is NOT committed separately. It will be committed with phase completion. + + + + + +**Level 1 (Quick Verify):** +- Context7 consulted for library/topic +- Current state verified or concerns escalated +- Verbal confirmation to proceed (no files) + +**Level 2 (Standard):** +- Context7 consulted for all options +- WebSearch findings cross-verified +- DISCOVERY.md created with recommendation +- Confidence level MEDIUM or higher +- Ready to inform PLAN.md creation + +**Level 3 (Deep Dive):** +- Discovery scope defined +- Context7 exhaustively consulted +- All WebSearch findings verified against authoritative sources +- DISCOVERY.md created with comprehensive analysis +- Quality report with source attribution +- If LOW confidence findings → validation checkpoints defined +- Confidence gate passed +- Ready to inform PLAN.md creation + diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index a1cb89b81..a0e0f94f0 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -142,7 +142,7 @@ fi When creating decimal phases, mark them as "(INSERTED)" in roadmap entries. -Read any existing PLAN.md or FINDINGS.md in the phase directory. +Read any existing PLAN.md or DISCOVERY.md in the phase directory. @@ -184,11 +184,11 @@ cat package.json 2>/dev/null | grep -A5 '"dependencies"' → If ALL work follows established codebase patterns: SKIP discovery, proceed to planning → If ANY external dependency, new library, or API integration: Continue to Level 1+ ↓ -Does fresh FINDINGS.md exist? +Does fresh DISCOVERY.md exist? ───────────────────────────────────── ```bash -ls .planning/phases/XX-name/FINDINGS.md 2>/dev/null +ls .planning/phases/XX-name/DISCOVERY.md 2>/dev/null ``` If exists, check freshness: @@ -197,7 +197,7 @@ If exists, check freshness: - Fast-moving APIs (Stripe, OpenAI, etc.): Valid for 7 days - Check file date vs today -→ If fresh FINDINGS.md exists covering this phase's topics: SKIP discovery, use existing +→ If fresh DISCOVERY.md exists covering this phase's topics: SKIP discovery, use existing → If missing or stale: Continue to determine depth ↓ Determine Discovery Depth @@ -215,7 +215,7 @@ Action: 1. Context7: mcp**context7**resolve-library-id → mcp**context7**get-library-docs 2. Verify current version/API matches expectations -3. No FINDINGS.md needed - proceed with confirmed knowledge +3. No DISCOVERY.md needed - proceed with confirmed knowledge **LEVEL 2 - Standard Research (15-30 min):** Use when: @@ -226,9 +226,9 @@ Use when: Action: -1. Route to workflows/research-phase.md with depth=standard -2. Produces FINDINGS.md with recommendation -3. Return here after FINDINGS.md created +1. Route to workflows/discovery-phase.md with depth=standard +2. Produces DISCOVERY.md with recommendation +3. Return here after DISCOVERY.md created **LEVEL 3 - Deep Dive (1+ hour):** Use when: @@ -240,10 +240,12 @@ Use when: Action: -1. Route to workflows/research-phase.md with depth=deep -2. Full research with cross-verification -3. FINDINGS.md with detailed rationale and validation checkpoints -4. Return here after FINDINGS.md created +1. Route to workflows/discovery-phase.md with depth=deep +2. Full discovery with cross-verification +3. DISCOVERY.md with detailed rationale and validation checkpoints +4. Return here after DISCOVERY.md created + +**NOTE:** For niche/complex domains (3D, games, audio, shaders, ML), consider using `/gsd:research-phase` BEFORE plan-phase. This produces comprehensive RESEARCH.md with ecosystem knowledge that goes beyond "which library" to "how do experts build this." ``` @@ -268,7 +270,7 @@ Action: **Discovery can be skipped (Level 0) ONLY when ALL true:** □ Pattern already exists in codebase (grep confirms) □ No new external dependencies -□ Fresh FINDINGS.md exists (if external deps involved) +□ Fresh DISCOVERY.md exists (if external deps involved) □ Pure internal refactoring or feature extension □ Using established project conventions only @@ -294,7 +296,7 @@ Discovery assessment: - Roadmap flag: [Likely / Unlikely] ([reason from roadmap]) - Roadmap topics: [topics if flagged, or N/A] - New external dependencies: [yes/no - list them] -- Existing FINDINGS.md: [yes (date) / no] +- Existing DISCOVERY.md: [yes (date) / no] - Codebase patterns exist: [yes/no] Discovery depth: [Level 0 (skip) / Level 1 (verify) / Level 2 (standard) / Level 3 (deep)] @@ -380,18 +382,38 @@ For this specific phase, understand: - What's the phase goal? (from roadmap) - What exists already? (scan codebase if mid-project) - What dependencies are met? (previous phases complete?) -- Any research findings? (FINDINGS.md) -- Any phase context? ({phase}-CONTEXT.md) +- Any ecosystem research? (RESEARCH.md from /gsd:research-phase) +- Any discovery findings? (DISCOVERY.md from mandatory discovery) +- Any phase context? ({phase}-CONTEXT.md from /gsd:discuss-phase) ```bash # If mid-project, understand current state ls -la src/ 2>/dev/null cat package.json 2>/dev/null | head -20 +# Check for comprehensive ecosystem research (created by /gsd:research-phase) +cat .planning/phases/XX-name/${PHASE}-RESEARCH.md 2>/dev/null + # Check for phase-specific context (created by /gsd:discuss-phase) cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null ``` +**If {phase}-RESEARCH.md exists:** +This file contains comprehensive ecosystem research for niche/complex domains. It captures: +- Standard stack (libraries, versions, why they're standard) +- Architecture patterns (how experts structure this type of project) +- Don't hand-roll list (problems with existing solutions - use libraries instead) +- Common pitfalls (mistakes to avoid) +- Code examples (verified patterns from authoritative sources) + +**You MUST use this research to inform your planning:** + +- `` → use these libraries, don't pick alternatives without reason +- `` → follow these patterns in task structure +- `` → NEVER create custom solutions for listed problems +- `` → inform verification criteria, add warnings to task actions +- `` → reference in task actions when applicable + **If {phase}-CONTEXT.md exists:** This file contains the user's input gathered through pre-planning questions. It captures their intent, preferences, constraints, and decisions BEFORE you plan. @@ -405,8 +427,9 @@ This file contains the user's input gathered through pre-planning questions. It - `` → resolve during task breakdown or flag as checkpoints - `` → user clarifications that override assumptions -**If {phase}-CONTEXT.md does NOT exist:** -Suggest running `/gsd:discuss-phase {phase}` first to gather context, OR proceed with roadmap description only (less informed planning). +**If neither RESEARCH.md nor CONTEXT.md exist:** +For niche domains (3D, games, audio, shaders, etc.), suggest `/gsd:research-phase {phase}` first. +For simpler domains, suggest `/gsd:discuss-phase {phase}` or proceed with roadmap description only. @@ -646,8 +669,11 @@ Output: [What artifacts will be created by this plan] @.planning/ROADMAP.md @.planning/STATE.md -[If research done:] -@.planning/phases/XX-name/FINDINGS.md +[If comprehensive ecosystem research exists (from /gsd:research-phase):] +@.planning/phases/XX-name/{phase}-RESEARCH.md + +[If discovery done (from mandatory discovery):] +@.planning/phases/XX-name/DISCOVERY.md [If phase context exists (from /gsd:discuss-phase):] @.planning/phases/XX-name/{phase}-CONTEXT.md @@ -777,18 +803,20 @@ Tasks are instructions for Claude, not Jira tickets. Phase planning is complete when: - [ ] STATE.md read and project history absorbed - [ ] **Mandatory discovery completed** (Level 0-3 as appropriate) -- [ ] If Level 2-3: FINDINGS.md exists with current context +- [ ] If Level 2-3: DISCOVERY.md exists with current context - [ ] If Level 1: Quick verification performed via Context7 +- [ ] If RESEARCH.md exists: ecosystem knowledge incorporated into plan - [ ] Prior decisions, issues, and concerns synthesized - [ ] One or more PLAN files exist with XML structure ({phase}-{plan}-PLAN.md) - [ ] Each plan has: Objective, context, tasks, verification, success criteria, output -- [ ] @context references included (including STATE.md, FINDINGS.md if exists, relevant prior summaries) +- [ ] @context references included (including STATE.md, RESEARCH.md if exists, DISCOVERY.md if exists, relevant prior summaries) - [ ] Prior decisions documented in context section - [ ] Deferred issues being addressed are noted - [ ] Each plan has 2-3 tasks (scoped to ~50% context) - [ ] Each task has: Type, Files (if auto), Action, Verify, Done - [ ] Checkpoints identified and properly structured - [ ] Tasks are specific enough for Claude to execute +- [ ] If RESEARCH.md exists: "don't hand-roll" items are NOT being custom-built - [ ] If multiple plans: logical split by subsystem/dependency/complexity - [ ] User knows next steps diff --git a/get-shit-done/workflows/research-phase.md b/get-shit-done/workflows/research-phase.md index feac6e8e2..14d5cc83c 100644 --- a/get-shit-done/workflows/research-phase.md +++ b/get-shit-done/workflows/research-phase.md @@ -1,293 +1,416 @@ -Execute discovery/research at the appropriate depth level. -Produces FINDINGS.md (for Level 2-3) that informs PLAN.md creation. +Comprehensive research on HOW to implement a phase before planning. -Called from plan-phase.md's mandatory_discovery step with a depth parameter. +Triggered by /gsd:research-phase command when the domain is niche, complex, or Claude's training is likely stale. + +Produces RESEARCH.md with ecosystem knowledge that informs quality planning - not just "which library" but "how do experts build this." - -**This workflow supports three depth levels:** + +**This workflow is for domains where Claude fails without research:** +- 3D graphics (Three.js, Babylon.js, procedural generation, level design) +- Game development (physics engines, collision, AI, ECS patterns) +- Audio/music (Web Audio, DSP, synthesis, MIDI) +- Shaders (GLSL, Metal, ISF, compute shaders) +- ML/AI integration (model serving, inference, vector DBs) +- Real-time systems (WebSockets, WebRTC, CRDT sync) +- Specialized frameworks with active ecosystems Claude may not know -| Level | Name | Time | Output | When | -| ----- | ------------ | --------- | ------------------------------------------ | ----------------------------------------- | -| 1 | Quick Verify | 2-5 min | No file, proceed with verified knowledge | Single library, confirming current syntax | -| 2 | Standard | 15-30 min | FINDINGS.md | Choosing between options, new integration | -| 3 | Deep Dive | 1+ hour | Detailed FINDINGS.md with validation gates | Architectural decisions, novel problems | +**Skip this for commodity domains:** +- Standard auth (JWT, OAuth) +- CRUD APIs +- Forms and validation +- Well-documented integrations (Stripe, SendGrid) + -**Depth is determined by plan-phase.md before routing here.** - + +The current "mandatory discovery" in plan-phase asks: "Which library should I use?" - -**MANDATORY: Context7 BEFORE WebSearch** +This workflow asks: "What do I not know that I don't know?" -Claude's training data is 6-18 months stale. Always verify. - -1. **Context7 MCP FIRST** - Current docs, no hallucination -2. **Official docs** - When Context7 lacks coverage -3. **WebSearch LAST** - For comparisons and trends only - -See ~/.claude/get-shit-done/templates/research-prompt.md `` for full protocol. - +For niche domains, the question isn't library selection - it's: +- What's the established architecture pattern? +- What libraries form the standard stack? +- What problems do people commonly hit? +- What's SOTA vs what Claude thinks is SOTA? +- What should NOT be hand-rolled? + - -Check the depth parameter passed from plan-phase.md: -- `depth=verify` → Level 1 (Quick Verification) -- `depth=standard` → Level 2 (Standard Research) -- `depth=deep` → Level 3 (Deep Dive) + +Phase number: $ARGUMENTS (required) -Route to appropriate level workflow below. - +Validate phase exists in roadmap: - -**Level 1: Quick Verification (2-5 minutes)** - -For: Single known library, confirming syntax/version still correct. - -**Process:** - -1. Resolve library in Context7: - - ``` - mcp__context7__resolve-library-id with libraryName: "[library]" - ``` - -2. Fetch relevant docs: - - ``` - mcp__context7__get-library-docs with: - - context7CompatibleLibraryID: [from step 1] - - topic: [specific concern] - ``` - -3. Verify: - - - Current version matches expectations - - API syntax unchanged - - No breaking changes in recent versions - -4. **If verified:** Return to plan-phase.md with confirmation. No FINDINGS.md needed. - -5. **If concerns found:** Escalate to Level 2. - -**Output:** Verbal confirmation to proceed, or escalation to Level 2. - - - -**Level 2: Standard Research (15-30 minutes)** - -For: Choosing between options, new external integration. - -**Process:** - -1. **Identify what to research:** - - - What options exist? - - What are the key comparison criteria? - - What's our specific use case? - -2. **Context7 for each option:** - - ``` - For each library/framework: - - mcp__context7__resolve-library-id - - mcp__context7__get-library-docs (mode: "code" for API, "info" for concepts) - ``` - -3. **Official docs** for anything Context7 lacks. - -4. **WebSearch** for comparisons: - - - "[option A] vs [option B] {current_year}" - - "[option] known issues" - - "[option] with [our stack]" - -5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs. - -6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to avoid common research gaps. - -7. **Create FINDINGS.md** using ~/.claude/get-shit-done/templates/research-prompt.md structure: - - - Summary with recommendation - - Key findings per option - - Code examples from Context7 - - Confidence level (should be MEDIUM-HIGH for Level 2) - -8. Return to plan-phase.md. - -**Output:** `.planning/phases/XX-name/FINDINGS.md` - - - -**Level 3: Deep Dive (1+ hour)** - -For: Architectural decisions, novel problems, high-risk choices. - -**Process:** - -1. **Scope the research** using ~/.claude/get-shit-done/templates/research-prompt.md: - - - Create RESEARCH.md with clear scope - - Define include/exclude boundaries - - List specific questions to answer - -2. **Exhaustive Context7 research:** - - - All relevant libraries - - Related patterns and concepts - - Multiple topics per library if needed - -3. **Official documentation deep read:** - - - Architecture guides - - Best practices sections - - Migration/upgrade guides - - Known limitations - -4. **WebSearch for ecosystem context:** - - - How others solved similar problems - - Production experiences - - Gotchas and anti-patterns - - Recent changes/announcements - -5. **Cross-verify ALL findings:** - - - Every WebSearch claim → verify with authoritative source - - Mark what's verified vs assumed - - Flag contradictions - -6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps. - -7. **Create comprehensive FINDINGS.md:** - - - Full structure from ~/.claude/get-shit-done/templates/research-prompt.md - - Quality report with source attribution - - Confidence by finding - - If LOW confidence on any critical finding → add validation checkpoints - -8. **Confidence gate:** If overall confidence is LOW, present options before proceeding. - -9. Return to plan-phase.md. - -**Output:** `.planning/phases/XX-name/FINDINGS.md` (comprehensive) - - - -**For Level 2-3:** Define what we need to learn. - -Ask: What do we need to learn before we can plan this phase? - -- Technology choices? -- Best practices? -- API patterns? -- Architecture approach? - - - -Use ~/.claude/get-shit-done/templates/research-prompt.md. -Write to `.planning/phases/XX-name/RESEARCH.md` - -Include: - -- Clear research objective -- Scoped include/exclude lists -- Source preferences (official docs, Context7, current year) -- Output structure for FINDINGS.md - - - -Run the research prompt: -- Use web search for current info -- Use Context7 MCP for library docs -- Prefer current year sources -- Structure findings per template - - - -Write `.planning/phases/XX-name/FINDINGS.md`: -- Summary with recommendation -- Key findings with sources -- Code examples if applicable -- Metadata (confidence, dependencies, open questions, assumptions) - - - -After creating FINDINGS.md, check confidence level. - -If confidence is LOW: -Use AskUserQuestion: - -- header: "Low Confidence" -- question: "Research confidence is LOW: [reason]. How would you like to proceed?" -- options: - - "Dig deeper" - Do more research before planning - - "Proceed anyway" - Accept uncertainty, plan with caveats - - "Pause" - I need to think about this - -If confidence is MEDIUM: -Inline: "Research complete (medium confidence). [brief reason]. Proceed to planning?" - -If confidence is HIGH: -Proceed directly, just note: "Research complete (high confidence)." - - - -If FINDINGS.md has open_questions: - -Present them inline: -"Open questions from research: - -- [Question 1] -- [Question 2] - -These may affect implementation. Acknowledge and proceed? (yes / address first)" - -If "address first": Gather user input on questions, update findings. - - - +```bash +if [ -f .planning/ROADMAP.md ]; then + grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md +fi ``` -Research complete: .planning/phases/XX-name/FINDINGS.md -Recommendation: [one-liner] -Confidence: [level] + +**If phase not found:** +``` +Error: Phase ${PHASE} not found in roadmap. + +Use /gsd:progress to see available phases. +``` +Exit workflow. + +**If phase found:** +Extract: +- Phase number +- Phase name +- Phase description +- Any "Research: Likely" flags + +Continue to check_existing. + + + +Check if RESEARCH.md already exists for this phase: + +```bash +ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null +ls .planning/phases/${PHASE}-*/${PHASE}-RESEARCH.md 2>/dev/null +``` + +**If exists:** +``` +Phase ${PHASE} already has research: [path to RESEARCH.md] What's next? - -1. Discuss phase context (/gsd:discuss-phase [current-phase]) -2. Create phase plan (/gsd:plan-phase [current-phase]) -3. Refine research (dig deeper) -4. Review findings - +1. Update research - Refresh with new findings +2. View existing - Show me the current research +3. Skip - Use existing research as-is ``` -NOTE: FINDINGS.md is NOT committed separately. It will be committed with phase completion. +Wait for user response. + +If "Update research": Load existing RESEARCH.md, proceed to research with update mindset +If "View existing": Read and display RESEARCH.md, then offer update/skip +If "Skip": Exit workflow + +**If doesn't exist:** +Continue to load_context. + + + +Load available context to inform research direction: + +**1. Project context:** +```bash +cat .planning/PROJECT.md 2>/dev/null | head -50 +``` + +**2. Phase context (if exists from /gsd:discuss-phase):** +```bash +cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null +``` + +If CONTEXT.md exists, use it to understand: +- User's specific goals for this phase +- Constraints mentioned +- Any preferences stated + +**3. Prior phase decisions:** +```bash +cat .planning/STATE.md 2>/dev/null | grep -A20 "## Accumulated Decisions" +``` + +These may constrain technology choices. + +Present what was found: +``` +Research context for Phase ${PHASE}: ${PHASE_NAME} + +Roadmap description: ${PHASE_DESCRIPTION} + +[If CONTEXT.md exists:] +Phase context available - will incorporate user preferences. + +[If prior decisions exist:] +Prior decisions to respect: [list relevant ones] + +Proceeding with ecosystem research... +``` + + + +Analyze the phase description to identify what needs researching. + +**Ask: "What knowledge do I need to actually implement this well?"** + +Categories to consider: + +**1. Core Technology:** +- What's the primary technology/framework? +- What version is current? (Claude's training may be stale) +- What's the standard setup/toolchain? + +**2. Ecosystem/Stack:** +- What libraries do experts pair with this? +- What's the "blessed" stack for this problem domain? +- What helper libraries exist that I might not know about? + +**3. Architecture Patterns:** +- How do experts structure this type of project? +- What design patterns apply? +- What's the recommended project organization? + +**4. Common Pitfalls:** +- What do beginners get wrong? +- What are the "gotchas" in this domain? +- What mistakes lead to rewrites? + +**5. What NOT to Hand-Roll:** +- What existing solutions should be used instead of custom code? +- What problems look simple but have nasty edge cases? +- What libraries solve problems I don't know I have? + +**6. Current State of the Art:** +- What's changed recently in this ecosystem? +- What approaches are now considered outdated? +- What new tools/patterns have emerged? + +Present research scope: +``` +Research domains identified: + +1. Core: [e.g., "Three.js for 3D web graphics"] +2. Ecosystem: [e.g., "Physics engine, asset loading, controls"] +3. Patterns: [e.g., "Scene graph architecture, game loop patterns"] +4. Pitfalls: [e.g., "Performance, memory, mobile compatibility"] +5. Don't hand-roll: [e.g., "Physics, collision detection, procedural generation"] +6. SOTA check: [e.g., "WebGPU vs WebGL, drei ecosystem"] + +Proceeding with comprehensive research... +``` + + + +Execute research systematically for each domain identified. + +**CRITICAL: Source hierarchy - Context7 BEFORE WebSearch** + +Claude's training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact. + + + +**For each domain, in order:** + +**1. Context7 First (authoritative, current):** +``` +For core technology: +- mcp__context7__resolve-library-id with libraryName: "[main technology]" +- mcp__context7__get-library-docs with topic: "getting started" +- mcp__context7__get-library-docs with topic: "[specific concern]" + +For ecosystem libraries: +- Resolve and fetch docs for each major library +- Focus on integration patterns, not just API reference +``` + +**2. Official Documentation:** +- Use WebFetch for official docs not in Context7 +- Check for "ecosystem" or "community" pages +- Look for "awesome-{technology}" lists +- Check GitHub trending/stars for the domain + +**3. WebSearch for Ecosystem Discovery:** +``` +Ecosystem discovery queries (use {current_year}): +- "[technology] best practices {current_year}" +- "[technology] recommended libraries {current_year}" +- "[technology] common mistakes" +- "[technology] vs [alternative] {current_year}" +- "how to build [type of thing] with [technology]" +- "[technology] performance optimization" +- "[technology] project structure" + +For niche domains: +- "[technology] tutorials {current_year}" +- "[technology] examples github" +- "[technology] showcase" +``` + +**4. Cross-Verification (MANDATORY):** +Every WebSearch finding MUST be verified: +- Check Context7 or official docs to confirm +- Mark confidence level (HIGH if verified, MEDIUM if partially verified, LOW if WebSearch only) +- Flag contradictions between sources + + + + +Execute research queries and document findings as you go: + +**Core Technology Findings:** +- Current version: [from Context7] +- Key changes since [Claude's training]: [from docs/WebSearch] +- Setup approach: [verified pattern] + +**Ecosystem Stack:** +- [Library 1]: [what it does, why it's standard, version] +- [Library 2]: [what it does, why it's standard, version] +- [Library 3]: [what it does, why it's standard, version] + +**Architecture Patterns:** +- [Pattern 1]: [what it is, when to use] +- [Pattern 2]: [what it is, when to use] +- Project structure: [recommended organization] + +**Common Pitfalls:** +- [Pitfall 1]: [what goes wrong, how to avoid] +- [Pitfall 2]: [what goes wrong, how to avoid] +- [Pitfall 3]: [what goes wrong, how to avoid] + +**Don't Hand-Roll:** +- [Problem]: Use [library] instead because [reason] +- [Problem]: Use [library] instead because [reason] + +**SOTA Updates:** +- [Old approach]: Now superseded by [new approach] +- [New tool]: [what it enables] + + + + + +Before creating RESEARCH.md, run through research-pitfalls.md checklist: + +**From ~/.claude/get-shit-done/references/research-pitfalls.md:** + +- [ ] All enumerated items investigated (not just some) +- [ ] Negative claims verified with official docs +- [ ] Multiple sources cross-referenced for critical claims +- [ ] URLs provided for authoritative sources +- [ ] Publication dates checked (prefer recent/current) +- [ ] Tool/environment-specific variations documented +- [ ] Confidence levels assigned honestly +- [ ] Assumptions distinguished from verified facts +- [ ] "What might I have missed?" review completed + +**Additional checks for ecosystem research:** +- [ ] Checked for libraries Claude might not know about +- [ ] Verified version numbers are current +- [ ] Confirmed patterns still recommended (not deprecated) +- [ ] Looked for "don't do this" warnings in docs +- [ ] Checked for breaking changes in recent versions + + + +Create RESEARCH.md using accumulated findings. + +**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-RESEARCH.md` + +**If phase directory doesn't exist:** +Create it: `.planning/phases/${PHASE}-${SLUG}/` + +Use template from ~/.claude/get-shit-done/templates/research.md + +Populate sections with verified findings from research execution. + +**Critical content requirements:** + +**1. Standard Stack section:** +- List specific libraries with versions +- Explain what each does and why it's standard +- Note any alternatives and when to use them + +**2. Architecture Patterns section:** +- Document recommended patterns with code examples if available +- Include project structure recommendations +- Note what patterns to avoid + +**3. Don't Hand-Roll section:** +- Be explicit about what problems have existing solutions +- Explain why custom solutions are worse +- List the libraries to use instead + +**4. Common Pitfalls section:** +- Specific mistakes with explanations +- How to avoid each +- Warning signs to watch for + +**5. Code Examples section:** +- Include verified code patterns from Context7/official docs +- Show the "right way" to do common operations +- Note any gotchas in the examples + +Write file. + + + +Present RESEARCH.md summary to user: + +``` +Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-RESEARCH.md + +## Research Summary + +**Domain:** [what was researched] + +**Standard Stack:** +- [Library 1] - [brief what/why] +- [Library 2] - [brief what/why] +- [Library 3] - [brief what/why] + +**Key Patterns:** +- [Pattern 1] +- [Pattern 2] + +**Don't Hand-Roll:** +- [Thing 1] - use [library] instead +- [Thing 2] - use [library] instead + +**Top Pitfalls:** +- [Pitfall 1] +- [Pitfall 2] + +**Confidence:** [HIGH/MEDIUM/LOW] - [brief reason] + +What's next? +1. Plan this phase (/gsd:plan-phase ${PHASE}) - RESEARCH.md will be loaded automatically +2. Dig deeper - Research specific areas more thoroughly +3. Review full RESEARCH.md +4. Done for now +``` -**Level 1 (Quick Verify):** -- Context7 consulted for library/topic -- Current state verified or concerns escalated -- Verbal confirmation to proceed (no files) - -**Level 2 (Standard):** -- Context7 consulted for all options -- WebSearch findings cross-verified -- FINDINGS.md created with recommendation -- Confidence level MEDIUM or higher -- Ready to inform PLAN.md creation - -**Level 3 (Deep Dive):** -- RESEARCH.md exists with clear scope -- Context7 exhaustively consulted -- All WebSearch findings verified against authoritative sources -- FINDINGS.md created with comprehensive analysis -- Quality report with source attribution -- If LOW confidence findings → validation checkpoints defined -- Confidence gate passed -- Ready to inform PLAN.md creation +- [ ] Phase validated against roadmap +- [ ] Research domains identified from phase description +- [ ] Context7 consulted for all relevant libraries +- [ ] Official docs consulted where Context7 lacks coverage +- [ ] WebSearch used for ecosystem discovery +- [ ] All WebSearch findings cross-verified +- [ ] Quality checklist completed +- [ ] RESEARCH.md created with comprehensive ecosystem knowledge +- [ ] Standard stack documented with versions +- [ ] Architecture patterns documented +- [ ] "Don't hand-roll" list is clear and actionable +- [ ] Common pitfalls catalogued +- [ ] Confidence levels assigned honestly +- [ ] User knows next steps (plan phase) -``` + + +When /gsd:plan-phase runs after research: + +1. plan-phase detects RESEARCH.md exists in phase directory +2. RESEARCH.md loaded as @context reference +3. "Standard stack" informs library choices in tasks +4. "Don't hand-roll" prevents custom solutions where libraries exist +5. "Common pitfalls" inform verification criteria +6. "Architecture patterns" inform task structure +7. "Code examples" can be referenced in task actions + +This produces higher quality plans because Claude knows: +- What tools experts use +- What patterns to follow +- What mistakes to avoid +- What NOT to build from scratch +