pmp-gywd 3.3.0

package/get-your-work-done/references/principles.md

@@ -0,0 +1,157 @@
+<principles>
+Core principles for the Gets Shit Done planning system.
+
+<solo_developer_claude>
+
+You are planning for ONE person (the user) and ONE implementer (Claude).
+- No teams, stakeholders, ceremonies, coordination overhead
+- User is the visionary/product owner
+- Claude is the builder
+- Estimate effort in Claude execution time, not human dev time
+</solo_developer_claude>
+
+<plans_are_prompts>
+
+PLAN.md is not a document that gets transformed into a prompt.
+PLAN.md IS the prompt. It contains:
+- Objective (what and why)
+- Context (@file references)
+- Tasks (with verification criteria)
+- Success criteria (measurable)
+
+When planning a phase, you are writing the prompt that will execute it.
+</plans_are_prompts>
+
+<initialization_leverage>
+
+The most leveraged moment is project initialization.
+- Deep questioning here = better everything downstream
+- Garbage in = garbage out
+- Spend the tokens on context gathering
+- Don't rush to "the work"
+</initialization_leverage>
+
+<scope_control>
+
+Plans must complete within reasonable context usage.
+
+**Quality degradation curve:**
+- 0-30% context: Peak quality
+- 30-50% context: Good quality
+- 50-70% context: Degrading quality
+- 70%+ context: Poor quality
+
+**Solution:** Aggressive atomicity - split into small, focused plans.
+- 2-3 tasks per plan maximum
+- Each plan independently executable
+- Better to have many small plans than few large ones
+</scope_control>
+
+<claude_automates>
+
+If Claude CAN do it via CLI/API/tool, Claude MUST do it.
+
+Checkpoints are for:
+- **Verification** - Human confirms Claude's work (visual, UX)
+- **Decision** - Human makes implementation choice
+
+Not for:
+- Deploying (use CLI)
+- Creating resources (use CLI/API)
+- Running builds/tests (use Bash)
+- Writing files (use Write tool)
+</claude_automates>
+
+<deviation_rules>
+
+Plans are guides, not straitjackets. During execution:
+
+1. **Auto-fix bugs** - Fix immediately, document
+2. **Auto-add critical** - Security/correctness gaps, add immediately
+3. **Auto-fix blockers** - Can't proceed, fix immediately
+4. **Ask about architectural** - Major changes, stop and ask
+5. **Log enhancements** - Nice-to-haves, log to Issues, continue
+</deviation_rules>
+
+<test_driven_when_beneficial>
+
+Use TDD when the work WOULD benefit from it. Not dogma—pragmatism.
+
+**TDD candidates (create dedicated TDD plan):**
+- Business logic with defined inputs/outputs
+- API endpoints and handlers
+- Data transformations and parsing
+- Validation rules
+- State machines and workflows
+- Anything where you can describe expected behavior before implementing
+
+**Skip TDD (use standard plan):**
+- UI layout and styling
+- Exploratory prototyping
+- One-off scripts and migrations
+- Configuration changes
+- Glue code with no logic
+
+**Decision heuristic:**
+Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan (one feature per plan)
+→ No: Standard plan, add tests after if needed
+
+**Why TDD gets its own plan:**
+TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This consumes 40-50% of context for a single feature. Dedicated TDD plans ensure full quality throughout the cycle.
+
+**TDD plan structure:**
+1. Write failing test (RED) → commit
+2. Implement to pass (GREEN) → commit
+3. Refactor if needed → commit
+
+This is about design quality, not test coverage metrics.
+
+See `~/.claude/get-your-work-done/references/tdd.md` for TDD plan structure.
+</test_driven_when_beneficial>
+
+<ship_fast>
+
+No enterprise process. No approval gates.
+
+Plan → Execute → Ship → Learn → Repeat
+
+Milestones mark shipped versions (v1.0 → v1.1 → v2.0).
+</ship_fast>
+
+<atomic_commits>
+
+**Git commits = context engineering for Claude.**
+
+Each task gets its own commit immediately after completion:
+- Format: `{type}({phase}-{plan}): {task-description}`
+- Types: feat, fix, test, refactor, perf, chore, docs
+- One final metadata commit per plan: `docs({phase}-{plan}): complete [plan-name]`
+
+**Why per-task commits:**
+- Git history becomes primary context source for future Claude sessions
+- `git bisect` finds exact failing task, not just failing plan
+- Each task independently revertable
+- Better failure recovery (task 1 committed ✅, retry task 2)
+- Observability optimized for AI workflow, not human browsing
+
+**Plans produce 3-4 commits total:**
+- 2-3 task commits (working code)
+- 1 metadata commit (SUMMARY + STATE + ROADMAP)
+
+See `~/.claude/get-your-work-done/references/git-integration.md` for complete strategy.
+</atomic_commits>
+
+<anti_enterprise>
+
+NEVER include:
+- Team structures, RACI matrices
+- Stakeholder management
+- Sprint ceremonies
+- Human dev time estimates (hours, days, weeks—Claude works differently)
+- Change management processes
+- Documentation for documentation's sake
+
+If it sounds like corporate PM theater, delete it.
+</anti_enterprise>
+</principles>

package/get-your-work-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-your-work-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>