gsd-opencode 1.3.31

package/get-shit-done/references/questioning.md

@@ -0,0 +1,162 @@
+<questioning_guide>
+The initialization phase is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate.
+</philosophy>
+
+<critical_rule>
+**ALL questions MUST use AskUserQuestion.**
+
+Never ask questions inline as plain text. Every exploration question uses the AskUserQuestion tool with thoughtful options that help the user articulate their vision.
+
+This applies to:
+- Opening questions ("What do you want to build?")
+- Follow-up questions ("You mentioned X — what would that look like?")
+- Sharpening questions ("What's essential vs nice-to-have?")
+- Boundary questions ("What's out of scope?")
+- Decision gates ("Ready to proceed?")
+
+The AskUserQuestion format helps users think by presenting concrete options to react to, rather than facing a blank text field.
+</critical_rule>
+
+<conversation_arc>
+**1. Open**
+
+Use AskUserQuestion:
+- header: "Vision"
+- question: "What do you want to build?"
+- options: Contextual starting points if available, otherwise broad categories + "Let me describe it"
+
+Let them respond. Then follow up based on what they said.
+
+**2. Follow the thread**
+
+Whatever they said — dig into it. What excited them? What problem sparked this?
+
+Use AskUserQuestion with options that probe what they mentioned:
+- header: "[Topic they mentioned]"
+- question: "You mentioned [X] — what would that actually look like?"
+- options: 2-3 interpretations of what they might mean + "Something else"
+
+**3. Sharpen the core**
+
+Help them distinguish the essential from the nice-to-have.
+
+Use AskUserQuestion:
+- header: "Core"
+- question: "If you could only nail one thing, what would it be?"
+- options: Key features/aspects they've mentioned + "All equally important" + "Something else"
+
+**4. Find the boundaries**
+
+What is this NOT? Explicit exclusions prevent scope creep later.
+
+Use AskUserQuestion:
+- header: "Scope"
+- question: "What's explicitly NOT in v1?"
+- options: Things that might be tempting to include + "Nothing specific" + "Let me list them"
+
+**5. Ground in reality**
+
+Only ask about constraints that actually exist. Don't invent concerns.
+
+Use AskUserQuestion:
+- header: "Constraints"
+- question: "Any hard constraints?"
+- options: Common constraint types relevant to context + "None" + "Yes, let me explain"
+</conversation_arc>
+
+<good_vs_bad>
+**BAD — Inline text questions:**
+- Asking "What is your target audience?" as plain text
+- Free-form "Tell me more about X" without options
+- Any question that leaves the user staring at a blank input
+
+**GOOD — AskUserQuestion with options:**
+- header: "Audience"
+- question: "Who is this for?"
+- options: ["Just me", "My team", "Public users", "Let me describe"]
+
+**BAD — Corporate speak:**
+- "What are your success criteria?"
+- "What's your budget?"
+- "Have you done X before?" (irrelevant — Claude builds)
+
+**GOOD — Concrete options that help them think:**
+- header: "Done"
+- question: "How will you know this is working?"
+- options: ["I'm using it daily", "Specific metric improves", "Replaces current workflow", "Let me describe"]
+
+**BAD — Checklist walking:**
+- Ask about audience → ask about constraints → ask about tech stack (regardless of what user said)
+
+**GOOD — Following threads with targeted options:**
+- User mentions frustration → AskUserQuestion with specific frustration interpretations as options → their selection reveals the core value prop
+</good_vs_bad>
+
+<probing_techniques>
+When answers are vague, don't accept them. Probe with AskUserQuestion:
+
+**"Make it good"** →
+- header: "Good"
+- question: "What does 'good' mean here?"
+- options: ["Fast", "Beautiful", "Simple", "Reliable", "Let me describe"]
+
+**"Users"** →
+- header: "Users"
+- question: "Which users?"
+- options: ["Just me", "My team", "Specific type of person", "Let me describe"]
+
+**"It should be easy to use"** →
+- header: "Easy"
+- question: "Easy how?"
+- options: ["Fewer clicks", "No learning curve", "Works on mobile", "Let me describe"]
+
+Specifics are everything. Vague in = vague out.
+</probing_techniques>
+
+<coverage_check>
+By the end of questioning, you should understand:
+
+- [ ] What they're building (the thing)
+- [ ] Why it needs to exist (the motivation)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (measurable outcome)
+- [ ] What's NOT in scope (boundaries)
+- [ ] Any real constraints (tech, timeline, compatibility)
+- [ ] What exists already (greenfield vs brownfield)
+
+If gaps remain, weave questions naturally into the conversation. Don't suddenly switch to checklist mode.
+</coverage_check>
+
+<decision_gate>
+When you feel you understand the vision, use AskUserQuestion:
+
+- header: "Ready?"
+- question: "Ready to create PROJECT.md, or explore more?"
+- options (ALL THREE REQUIRED):
+  - "Create PROJECT.md" - Finalize and continue
+  - "Ask more questions" - I'll dig into areas we haven't covered
+  - "Let me add context" - You have more to share
+
+If "Ask more questions" → identify gaps from coverage check → ask naturally → return to gate.
+
+Loop until "Create PROJECT.md" selected.
+</decision_gate>
+
+<anti_patterns>
+- **Interrogation** - Firing questions without building on answers
+- **Checklist walking** - Going through domains regardless of conversation flow
+- **Corporate speak** - "What are your success criteria?" "Who are your stakeholders?"
+- **Rushing** - Minimizing questions to get to "the work"
+- **Assuming** - Filling gaps with assumptions instead of asking
+- **User skills** - NEVER ask about user's technical experience. Claude builds — user's skills are irrelevant.
+- **Premature constraints** - Asking about tech stack before understanding the idea
+- **Shallow acceptance** - Taking vague answers without probing for specifics
+</anti_patterns>
+</questioning_guide>

package/get-shit-done/references/research-pitfalls.md

@@ -0,0 +1,215 @@
+<research_pitfalls>
+
+<purpose>
+This document catalogs research mistakes discovered in production use, providing specific patterns to avoid and verification strategies to prevent recurrence.
+</purpose>
+
+<known_pitfalls>
+
+<pitfall_config_scope>
+**What**: Assuming global configuration means no project-scoping exists
+**Example**: Concluding "MCP servers are configured GLOBALLY only" while missing project-scoped `.mcp.json`
+**Why it happens**: Not explicitly checking all known configuration patterns
+**Prevention**:
+```xml
+<verification_checklist>
+**CRITICAL**: Verify ALL configuration scopes:
+□ User/global scope - System-wide configuration
+□ Project scope - Project-level configuration files
+□ Local scope - Project-specific user overrides
+□ Workspace scope - IDE/tool workspace settings
+□ Environment scope - Environment variables
+</verification_checklist>
+```
+</pitfall_config_scope>
+
+<pitfall_search_vagueness>
+**What**: Asking researchers to "search for documentation" without specifying where
+**Example**: "Research MCP documentation" → finds outdated community blog instead of official docs
+**Why it happens**: Vague research instructions don't specify exact sources
+**Prevention**:
+```xml
+<sources>
+Official sources (use WebFetch):
+- https://exact-url-to-official-docs
+- https://exact-url-to-api-reference
+
+Search queries (use WebSearch):
+- "specific search query {current_year}"
+- "another specific query {current_year}"
+</sources>
+```
+</pitfall_search_vagueness>
+
+<pitfall_deprecated_features>
+**What**: Finding archived/old documentation and concluding feature doesn't exist
+**Example**: Finding 2022 docs saying "feature not supported" when current version added it
+**Why it happens**: Not checking multiple sources or recent updates
+**Prevention**:
+```xml
+<verification_checklist>
+□ Check current official documentation
+□ Review changelog/release notes for recent updates
+□ Verify version numbers and publication dates
+□ Cross-reference multiple authoritative sources
+</verification_checklist>
+```
+</pitfall_deprecated_features>
+
+<pitfall_tool_variations>
+**What**: Conflating capabilities across different tools/environments
+**Example**: "Claude Desktop supports X" ≠ "Claude Code supports X"
+**Why it happens**: Not explicitly checking each environment separately
+**Prevention**:
+```xml
+<verification_checklist>
+□ Claude Desktop capabilities
+□ Claude Code capabilities
+□ VS Code extension capabilities
+□ API/SDK capabilities
+Document which environment supports which features
+</verification_checklist>
+```
+</pitfall_tool_variations>
+
+<pitfall_negative_claims>
+**What**: Making definitive "X is not possible" statements without official source verification
+**Example**: "Folder-scoped MCP configuration is not supported" (missing `.mcp.json`)
+**Why it happens**: Drawing conclusions from absence of evidence rather than evidence of absence
+**Prevention**:
+```xml
+<critical_claims_audit>
+For any "X is not possible" or "Y is the only way" statement:
+- [ ] Is this verified by official documentation stating it explicitly?
+- [ ] Have I checked for recent updates that might change this?
+- [ ] Have I verified all possible approaches/mechanisms?
+- [ ] Am I confusing "I didn't find it" with "it doesn't exist"?
+</critical_claims_audit>
+```
+</pitfall_negative_claims>
+
+<pitfall_missing_enumeration>
+**What**: Investigating open-ended scope without enumerating known possibilities first
+**Example**: "Research configuration options" instead of listing specific options to verify
+**Why it happens**: Not creating explicit checklist of items to investigate
+**Prevention**:
+```xml
+<verification_checklist>
+Enumerate ALL known options FIRST:
+□ Option 1: [specific item]
+□ Option 2: [specific item]
+□ Option 3: [specific item]
+□ Check for additional unlisted options
+
+For each option above, document:
+- Existence (confirmed/not found/unclear)
+- Official source URL
+- Current status (active/deprecated/beta)
+</verification_checklist>
+```
+</pitfall_missing_enumeration>
+
+<pitfall_single_source>
+**What**: Relying on a single source for critical claims
+**Example**: Using only Stack Overflow answer from 2021 for current best practices
+**Why it happens**: Not cross-referencing multiple authoritative sources
+**Prevention**:
+```xml
+<source_verification>
+For critical claims, require multiple sources:
+- [ ] Official documentation (primary)
+- [ ] Release notes/changelog (for currency)
+- [ ] Additional authoritative source (for verification)
+- [ ] Contradiction check (ensure sources agree)
+</source_verification>
+```
+</pitfall_single_source>
+
+<pitfall_assumed_completeness>
+**What**: Assuming search results are complete and authoritative
+**Example**: First Google result is outdated but assumed current
+**Why it happens**: Not verifying publication dates and source authority
+**Prevention**:
+```xml
+<source_verification>
+For each source consulted:
+- [ ] Publication/update date verified (prefer recent/current)
+- [ ] Source authority confirmed (official docs, not blogs)
+- [ ] Version relevance checked (matches current version)
+- [ ] Multiple search queries tried (not just one)
+</source_verification>
+```
+</pitfall_assumed_completeness>
+</known_pitfalls>
+
+<red_flags>
+
+<red_flag_zero_not_found>
+**Warning**: Every investigation succeeds perfectly
+**Problem**: Real research encounters dead ends, ambiguity, and unknowns
+**Action**: Expect honest reporting of limitations, contradictions, and gaps
+</red_flag_zero_not_found>
+
+<red_flag_no_confidence>
+**Warning**: All findings presented as equally certain
+**Problem**: Can't distinguish verified facts from educated guesses
+**Action**: Require confidence levels (High/Medium/Low) for key findings
+</red_flag_no_confidence>
+
+<red_flag_missing_urls>
+**Warning**: "According to documentation..." without specific URL
+**Problem**: Can't verify claims or check for updates
+**Action**: Require actual URLs for all official documentation claims
+</red_flag_missing_urls>
+
+<red_flag_no_evidence>
+**Warning**: "X cannot do Y" or "Z is the only way" without citation
+**Problem**: Strong claims require strong evidence
+**Action**: Flag for verification against official sources
+</red_flag_no_evidence>
+
+<red_flag_incomplete_enum>
+**Warning**: Verification checklist lists 4 items, output covers 2
+**Problem**: Systematic gaps in coverage
+**Action**: Ensure all enumerated items addressed or marked "not found"
+</red_flag_incomplete_enum>
+</red_flags>
+
+<continuous_improvement>
+
+When research gaps occur:
+
+1. **Document the gap**
+   - What was missed or incorrect?
+   - What was the actual correct information?
+   - What was the impact?
+
+2. **Root cause analysis**
+   - Why wasn't it caught?
+   - Which verification step would have prevented it?
+   - What pattern does this reveal?
+
+3. **Update this document**
+   - Add new pitfall entry
+   - Update relevant checklists
+   - Share lesson learned
+</continuous_improvement>
+
+<quick_reference>
+
+Before submitting research, verify:
+
+- [ ] All enumerated items investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources cross-referenced for critical claims
+- [ ] URLs provided for all official documentation
+- [ ] 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
+
+**Living Document**: Update after each significant research gap
+**Lessons From**: MCP configuration research gap (missed `.mcp.json`)
+</quick_reference>
+</research_pitfalls>

package/get-shit-done/references/scope-estimation.md

@@ -0,0 +1,172 @@
+<scope_estimation>
+Plans must maintain consistent quality from first task to last. This requires understanding quality degradation and splitting aggressively.
+
+<quality_insight>
+Claude degrades when it *perceives* context pressure and enters "completion mode."
+
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, comprehensive |
+| 30-50% | GOOD | Confident, solid work |
+| 50-70% | DEGRADING | Efficiency mode begins |
+| 70%+ | POOR | Rushed, minimal |
+
+**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: "I'll complete the remaining tasks more concisely" = quality crash.
+
+**The rule:** Stop BEFORE quality degrades, not at context limit.
+</quality_insight>
+
+<context_target>
+**Plans should complete within ~50% of context usage.**
+
+Why 50% not 80%?
+- No context anxiety possible
+- Quality maintained start to finish
+- Room for unexpected complexity
+- If you target 80%, you've already spent 40% in degradation mode
+</context_target>
+
+<task_rule>
+**Each plan: 2-3 tasks maximum. Stay under 50% context.**
+
+| Task Complexity | Tasks/Plan | Context/Task | Total |
+|-----------------|------------|--------------|-------|
+| Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
+| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
+| Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
+
+**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
+</task_rule>
+
+<tdd_plans>
+**TDD features get their own plans. Target ~40% context.**
+
+TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This is fundamentally heavier than linear task execution.
+
+| TDD Feature Complexity | Context Usage |
+|------------------------|---------------|
+| Simple utility function | ~25-30% |
+| Business logic with edge cases | ~35-40% |
+| Complex algorithm | ~40-50% |
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD.
+
+**Why TDD plans are separate:**
+- TDD consumes 40-50% context for a single feature
+- Dedicated plans ensure full quality throughout RED-GREEN-REFACTOR
+- Each TDD feature gets fresh context, peak quality
+
+See `~/.config/opencode/get-shit-done/references/tdd.md` for TDD plan structure.
+</tdd_plans>
+
+<split_signals>
+
+<always_split>
+- **More than 3 tasks** - Even if tasks seem small
+- **Multiple subsystems** - DB + API + UI = separate plans
+- **Any task with >5 file modifications** - Split by file groups
+- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
+- **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
+</always_split>
+
+<consider_splitting>
+- Estimated >5 files modified total
+- Complex domains (auth, payments, data modeling)
+- Any uncertainty about approach
+- Natural semantic boundaries (Setup -> Core -> Features)
+</consider_splitting>
+</split_signals>
+
+<splitting_strategies>
+**By subsystem:** Auth → 01: DB models, 02: API routes, 03: Protected routes, 04: UI components
+
+**By dependency:** Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration
+
+**By complexity:** Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization
+
+**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
+</splitting_strategies>
+
+<anti_patterns>
+**Bad - Comprehensive plan:**
+```
+Plan: "Complete Authentication System"
+Tasks: 8 (models, migrations, API, JWT, middleware, hashing, login form, register form)
+Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
+```
+
+**Good - Atomic plans:**
+```
+Plan 1: "Auth Database Models" (2 tasks)
+Plan 2: "Auth API Core" (3 tasks)
+Plan 3: "Auth API Protection" (2 tasks)
+Plan 4: "Auth UI Components" (2 tasks)
+Each: 30-40% context, peak quality, atomic commits (2-3 task commits + 1 metadata commit)
+```
+</anti_patterns>
+
+<estimating_context>
+| Files Modified | Context Impact |
+|----------------|----------------|
+| 0-3 files | ~10-15% (small) |
+| 4-6 files | ~20-30% (medium) |
+| 7+ files | ~40%+ (large - split) |
+
+| Complexity | Context/Task |
+|------------|--------------|
+| Simple CRUD | ~15% |
+| Business logic | ~25% |
+| Complex algorithms | ~40% |
+| Domain modeling | ~35% |
+
+**2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
+**3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
+</estimating_context>
+
+<depth_calibration>
+**Depth controls compression tolerance, not artificial inflation.**
+
+| Depth | Typical Phases | Typical Plans/Phase | Tasks/Plan |
+|-------|----------------|---------------------|------------|
+| Quick | 3-5 | 1-3 | 2-3 |
+| Standard | 5-8 | 3-5 | 2-3 |
+| Comprehensive | 8-12 | 5-10 | 2-3 |
+
+Tasks/plan is CONSTANT at 2-3. The 50% context rule applies universally.
+
+**Key principle:** Derive from actual work. Depth determines how aggressively you combine things, not a target to hit.
+
+- Comprehensive auth = 8 plans (because auth genuinely has 8 concerns)
+- Comprehensive "add favicon" = 1 plan (because that's all it is)
+
+Don't pad small work to hit a number. Don't compress complex work to look efficient.
+
+**Comprehensive depth example:**
+Auth system at comprehensive depth = 8 plans (not 3 big ones):
+- 01: DB models (2 tasks)
+- 02: Password hashing (2 tasks)
+- 03: JWT generation (2 tasks)
+- 04: JWT validation middleware (2 tasks)
+- 05: Login endpoint (2 tasks)
+- 06: Register endpoint (2 tasks)
+- 07: Protected route patterns (2 tasks)
+- 08: Auth UI components (3 tasks)
+
+Each plan: fresh context, peak quality. More plans = more thoroughness, same quality per plan.
+</depth_calibration>
+
+<summary>
+**2-3 tasks, 50% context target:**
+- All tasks: Peak quality
+- Git: Atomic per-task commits (each task = 1 commit, plan = 1 metadata commit)
+- Autonomous plans: Subagent execution (fresh context)
+
+**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
+
+**The rule:** If in doubt, split. Quality over consolidation. Always.
+
+**Depth rule:** Depth increases plan COUNT, never plan SIZE.
+
+**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit). More granular history = better observability for Claude.
+</summary>
+</scope_estimation>