get-shit-done-cc 1.0.0

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,451 @@
+<scope_estimation>
+Plans must maintain consistent quality from first task to last. This requires understanding the **quality degradation curve** and splitting aggressively to stay in the peak quality zone.
+
+<quality_degradation_curve>
+
+**Critical insight:** Claude doesn't degrade at arbitrary percentages - it degrades when it *perceives* context pressure and enters "completion mode."
+
+```
+Context Usage  │  Quality Level   │  Claude's Mental State
+─────────────────────────────────────────────────────────
+0-30%          │  ████████ PEAK   │  "I can be thorough and comprehensive"
+               │                  │  No anxiety, full detail, best work
+
+30-50%         │  ██████ GOOD     │  "Still have room, maintaining quality"
+               │                  │  Engaged, confident, solid work
+
+50-70%         │  ███ DEGRADING   │  "Getting tight, need to be efficient"
+               │                  │  Efficiency mode, compression begins
+
+70%+           │  █ POOR          │  "Running out, must finish quickly"
+               │                  │  Self-lobotomization, rushed, minimal
+```
+
+**The 40-50% inflection point:**
+
+This is where quality breaks. Claude sees context mounting and thinks "I'd better conserve now or I won't finish." Result: The classic mid-execution statement "I'll complete the remaining tasks more concisely" = quality crash.
+
+**The fundamental rule:** Stop BEFORE quality degrades, not at context limit.
+</quality_degradation_curve>
+
+<context_target>
+
+**Plans should complete within ~50% of context usage.**
+
+Why 50% not 80%?
+- Huge safety buffer
+- No context anxiety possible
+- Quality maintained from start to finish
+- Room for unexpected complexity
+- Space for iteration and fixes
+
+**If you target 80%, you're planning for failure.** By the time you hit 80%, you've already spent 40% in degradation mode.
+</context_target>
+
+<task_rule>
+
+**Each plan should contain 2-3 tasks maximum. Context usage matters more than task count.**
+
+**The real measure: Stay under 50% context usage.**
+
+Task count is a proxy for context. Adjust based on task complexity:
+
+**Simple tasks (CRUD, config, basic features):**
+- 3 tasks is fine
+- Each burns ~10-15% context
+- Total: ~30-45% → Safe
+
+**Complex tasks (auth, payments, architecture, integrations):**
+- Stick to 2 tasks
+- Each burns ~20-30% context
+- Total: ~40-50% → At limit
+
+**Very complex tasks (migrations, major refactors, novel patterns):**
+- Consider 1-2 tasks only
+- Each can burn 30-40% context
+- Splitting to 1 task/plan is valid for high complexity
+
+**Context estimation by task type:**
+
+**Task 1 (0-15% context for simple, 0-30% for complex):**
+- Fresh context
+- Peak quality
+- Comprehensive implementation
+- Full testing
+
+**Task 2 (15-35% context for simple, 30-50% for complex):**
+- Still good quality
+- Context pressure manageable
+- Natural stopping point for complex work
+
+**Task 3 (35-50% context for simple only):**
+- Only include for simple tasks
+- Skip for complex work
+- Better to split complex work at 2 tasks
+
+**Task 4+ (50%+ context):**
+- NEVER do this
+- Quality guaranteed to degrade
+- Should have split earlier
+
+**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
+
+**The principle:** Each plan completes within 50% context. Task count is flexible based on complexity.
+</task_rule>
+
+<split_signals>
+
+<always_split>
+
+**1. More than 3 tasks**
+- Even if tasks seem small
+- Each additional task increases degradation risk
+- Split into logical groups of 2-3
+
+**2. Multiple subsystems**
+```
+❌ Bad (1 plan):
+- Database schema (3 files)
+- API routes (5 files)
+- UI components (8 files)
+Total: 16 files, 1 plan → guaranteed degradation
+
+✅ Good (3 plans):
+- 01-01-PLAN.md: Database schema (3 files, 2 tasks)
+- 01-02-PLAN.md: API routes (5 files, 3 tasks)
+- 01-03-PLAN.md: UI components (8 files, 3 tasks)
+Total: 16 files, 3 plans → consistent quality
+```
+
+**3. Any task with >5 file modifications**
+- Large tasks burn context fast
+- Split by file groups or logical units
+- Better: 3 plans of 2 files each vs 1 plan of 6 files
+
+**4. Checkpoint + implementation work**
+- Checkpoints require user interaction (context preserved)
+- Implementation after checkpoint should be separate plan
+
+✅ Good split:
+- 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)
+- Clear boundary, clean handoff
+</always_split>
+
+<consider_splitting>
+
+**1. Estimated >5 files modified total**
+- Context from reading existing code
+- Context from diffs
+- Context from responses
+- Adds up faster than expected
+
+**2. Complex domains (auth, payments, data modeling)**
+- These require careful thinking
+- Burns more context per task than simple CRUD
+- Split more aggressively
+
+**3. Any uncertainty about approach**
+- "Figure out X" phase separate from "implement X" phase
+- Don't mix exploration and implementation
+
+**4. Natural semantic boundaries**
+- Setup → Core → Features
+- Backend → Frontend
+- Configuration → Implementation → Testing
+</consider_splitting>
+</split_signals>
+
+<splitting_strategies>
+
+<by_subsystem>
+
+**Phase:** "Authentication System"
+
+**Split:**
+```
+- 03-01-PLAN.md: Database models (User, Session tables + relations)
+- 03-02-PLAN.md: Auth API (register, login, logout endpoints)
+- 03-03-PLAN.md: Protected routes (middleware, JWT validation)
+- 03-04-PLAN.md: UI components (login form, registration form)
+```
+
+Each plan: 2-3 tasks, single subsystem, clean commits.
+</by_subsystem>
+
+<by_dependency>
+
+**Phase:** "Payment Integration"
+
+**Split:**
+```
+- 04-01-PLAN.md: Stripe setup (webhook endpoints via API, env vars, test mode)
+- 04-02-PLAN.md: Subscription logic (plans, checkout, customer portal)
+- 04-03-PLAN.md: Frontend integration (pricing page, payment flow)
+```
+
+Later plans depend on earlier completion. Sequential execution, fresh context each time.
+</by_dependency>
+
+<by_complexity>
+
+**Phase:** "Dashboard Buildout"
+
+**Split:**
+```
+- 05-01-PLAN.md: Layout shell (simple: sidebar, header, routing)
+- 05-02-PLAN.md: Data fetching (moderate: TanStack Query setup, API integration)
+- 05-03-PLAN.md: Data visualization (complex: charts, tables, real-time updates)
+```
+
+Complex work gets its own plan with full context budget.
+</by_complexity>
+
+<by_verification_points>
+
+**Phase:** "Deployment Pipeline"
+
+**Split:**
+```
+- 06-01-PLAN.md: Vercel setup (deploy via CLI, configure domains)
+  → Ends with checkpoint:human-verify "check xyz.vercel.app loads"
+
+- 06-02-PLAN.md: Environment config (secrets via CLI, env vars)
+  → Autonomous (no checkpoints) → subagent execution
+
+- 06-03-PLAN.md: CI/CD (GitHub Actions, preview deploys)
+  → Ends with checkpoint:human-verify "check PR preview works"
+```
+
+Verification checkpoints create natural boundaries. Autonomous plans between checkpoints execute via subagent with fresh context.
+</by_verification_points>
+</splitting_strategies>
+
+<autonomous_vs_interactive>
+
+**Critical optimization:** Plans without checkpoints don't need main context.
+
+<autonomous_plans>
+- Contains only `type="auto"` tasks
+- No user interaction needed
+- **Execute via subagent with fresh 200k context**
+- Impossible to degrade (always starts at 0%)
+- Creates SUMMARY, commits, reports back
+- Can run in parallel (multiple subagents)
+</autonomous_plans>
+
+<interactive_plans>
+- Contains `checkpoint:human-verify` or `checkpoint:decision` tasks
+- Requires user interaction
+- Must execute in main context
+- Still target 50% context (2-3 tasks)
+
+**Planning guidance:** If splitting a phase, try to:
+- Group autonomous work together (→ subagent)
+- Separate interactive work (→ main context)
+- Maximize autonomous plans (more fresh contexts)
+
+Example:
+```
+Phase: Feature X
+- 07-01-PLAN.md: Backend (autonomous) → subagent
+- 07-02-PLAN.md: Frontend (autonomous) → subagent
+- 07-03-PLAN.md: Integration test (has checkpoint:human-verify) → main context
+```
+
+Two fresh contexts, one interactive verification. Perfect.
+</interactive_plans>
+</autonomous_vs_interactive>
+
+<anti_patterns>
+
+<antipattern_comprehensive>
+
+```
+Plan: "Complete Authentication System"
+Tasks:
+1. Database models
+2. Migration files
+3. Auth API endpoints
+4. JWT utilities
+5. Protected route middleware
+6. Password hashing
+7. Login form component
+8. Registration form component
+
+Result: 8 tasks, 80%+ context, degradation at task 4-5
+```
+
+**Why this fails:**
+- Task 1-3: Good quality
+- Task 4-5: "I'll do these concisely" = degradation begins
+- Task 6-8: Rushed, minimal, poor quality
+</antipattern_comprehensive>
+
+<pattern_atomic>
+
+```
+Split into 4 plans:
+
+Plan 1: "Auth Database Models" (2 tasks)
+- Database schema (User, Session)
+- Migration files
+
+Plan 2: "Auth API Core" (3 tasks)
+- Register endpoint
+- Login endpoint
+- JWT utilities
+
+Plan 3: "Auth API Protection" (2 tasks)
+- Protected route middleware
+- Logout endpoint
+
+Plan 4: "Auth UI Components" (2 tasks)
+- Login form
+- Registration form
+```
+
+**Why this succeeds:**
+- Each plan: 2-3 tasks, 30-40% context
+- All tasks: Peak quality throughout
+- Git history: 4 focused commits
+- Easy to verify each piece
+- Rollback is surgical
+</pattern_atomic>
+
+<antipattern_efficiency_trap>
+
+```
+Thinking: "These tasks are small, let's do 6 to be efficient"
+
+Result: Task 1-2 are good, task 3-4 begin degrading, task 5-6 are rushed
+```
+
+**Why this fails:** You're optimizing for fewer plans, not quality. The "efficiency" is false - poor quality requires more rework.
+</antipattern_efficiency_trap>
+
+<pattern_quality_first>
+
+```
+Thinking: "These tasks are small, but let's do 2-3 to guarantee quality"
+
+Result: All tasks peak quality, clean commits, no rework needed
+```
+
+**Why this succeeds:** You optimize for quality, which is true efficiency. No rework = faster overall.
+</pattern_quality_first>
+</anti_patterns>
+
+<estimating_context>
+
+**Rough heuristics for plan size:**
+
+<file_counts>
+- 0-3 files modified: Small task (~10-15% context)
+- 4-6 files modified: Medium task (~20-30% context)
+- 7+ files modified: Large task (~40%+ context) - split this
+</file_counts>
+
+<complexity>
+- Simple CRUD: ~15% per task
+- Business logic: ~25% per task
+- Complex algorithms: ~40% per task
+- Domain modeling: ~35% per task
+</complexity>
+
+<two_task_plan>
+- 2 simple tasks: ~30% total ✅ Plenty of room
+- 2 medium tasks: ~50% total ✅ At target
+- 2 complex tasks: ~80% total ❌ Too tight, split
+</two_task_plan>
+
+<three_task_plan>
+- 3 simple tasks: ~45% total ✅ Good
+- 3 medium tasks: ~75% total ⚠️ Pushing it
+- 3 complex tasks: 120% total ❌ Impossible, split
+
+**Conservative principle:** When in doubt, split. Better to have an extra plan than degraded quality.
+</three_task_plan>
+</estimating_context>
+
+<atomic_commits>
+
+**What we're optimizing for:** Beautiful git history where each commit is:
+- Focused (2-3 related changes)
+- Complete (fully implemented, tested)
+- Documented (clear commit message)
+- Reviewable (small enough to understand)
+- Revertable (surgical rollback possible)
+
+**Bad git history (large plans):**
+```
+feat(auth): Complete authentication system
+- Added 16 files
+- Modified 8 files
+- 1200 lines changed
+- Contains: models, API, UI, middleware, utilities
+```
+
+Impossible to review, hard to understand, can't revert without losing everything.
+
+**Good git history (atomic plans):**
+```
+feat(auth-01): Add User and Session database models
+- Added schema files
+- Added migration
+- 45 lines changed
+
+feat(auth-02): Implement register and login API endpoints
+- Added /api/auth/register
+- Added /api/auth/login
+- Added JWT utilities
+- 120 lines changed
+
+feat(auth-03): Add protected route middleware
+- Added middleware/auth.ts
+- Added tests
+- 60 lines changed
+
+feat(auth-04): Build login and registration forms
+- Added LoginForm component
+- Added RegisterForm component
+- 90 lines changed
+```
+
+Each commit tells a story. Each is reviewable. Each is revertable. This is craftsmanship.
+</atomic_commits>
+
+<quality_assurance>
+
+**The guarantee:** When you follow the 2-3 task rule with 50% context target:
+
+1. **Consistency:** First task has same quality as last task
+2. **Thoroughness:** No "I'll complete X concisely" degradation
+3. **Documentation:** Full context budget for comments/tests
+4. **Error handling:** Space for proper validation and edge cases
+5. **Testing:** Room for comprehensive test coverage
+
+**The cost:** More plans to manage.
+
+**The benefit:** Consistent excellence. No rework. Clean history. Maintainable code.
+
+**The trade-off is worth it.**
+</quality_assurance>
+
+<summary>
+
+**2-3 tasks, 50% context target:**
+- All tasks: Peak quality
+- Git: Atomic, surgical commits
+- Quality: Consistent excellence
+- 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.
+</summary>
+</scope_estimation>

package/get-shit-done/templates/config.json

@@ -0,0 +1,17 @@
+{
+  "mode": "interactive",
+  "gates": {
+    "confirm_project": true,
+    "confirm_phases": true,
+    "confirm_roadmap": true,
+    "confirm_breakdown": true,
+    "confirm_plan": true,
+    "execute_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
+  }
+}